@woosh/meep-engine 3.15.0 → 3.17.0

package/src/shade/renderer/particles/isa/ParticleVMISA.js

@@ -7,32 +7,72 @@
  *
  * ## Encoding
  *
- * Every instruction is a fixed run of {@link PARTICLE_VM_INSTRUCTION_WORDS} `u32` words:
+ * Every instruction is {@link PARTICLE_VM_INSTRUCTION_WORDS} `u32` words — the size of one
+ * `vec4<u32>`, so the four loads that fetch it are one 16-byte load by the time a shader compiler is
+ * done with them:
  *
- *     [ op, dst, s0, s1, s2 ]
+ *     [ op | width << 8 | kinds << 16 | dst << 24,   s0,   s1,   s2 ]
  *
- * `dst` is the destination register for value-producing ops. `s0/s1/s2` are usually source register
- * indices, but some opcodes reinterpret them as immediates (constant-pool index, attribute word
- * offset + component count, curve handle, builtin id, random mode, swizzle pattern). The
- * `operands` array below documents, per opcode, what each slot means.
+ * Word 0 packs the opcode (bits 0..7), the lane count the operation spans (8..10), the kind of each
+ * source (two bits per slot at 16..21) and the destination register (24..31). The other three words
+ * are the sources. Registers hold single floats, so a `vec3` value is three consecutive slots and an
+ * `ADD` with width 3 adds three lanes; widths are what stop every value costing four registers.
  *
- * Registers are `vec4f`; scalars occupy `.x`. There is no control flow: conditionals are expressed
- * with CMP + SELECT and destruction with KILL, which keeps the interpreter a single flat `switch`
- * inside a bounded loop — friendly to both the WGSL emulator and real hardware.
+ * ## Operands
+ *
+ * A source word means what its kind says — see {@link VM_KIND}:
+ *
+ * - `NONE`: not an operand the VM resolves — an unused slot, or a raw field the opcode reads for
+ *   itself: an attribute offset, a component count, a builtin id, a curve handle, a pool index.
+ * - `REG`: a register operand. Bits 0..7 are the first slot, bits 8..15 a swizzle — see below.
+ * - `IMM`: the word IS the `f32` bit pattern of a literal, read in every lane. A scalar or a
+ *   lane-uniform vector costs no register and no load; only a vector whose lanes differ still goes
+ *   through the pool with `LOAD_CONST`.
+ *
+ * The kinds exist so the interpreter can resolve every source the same way, before the opcode runs
+ * and without consulting a table: it reads the kind, gathers the lanes, and the opcode body sees
+ * three four-lane values whatever they came from. A kind is encoding, not an opcode mode.
+ *
+ * ## Swizzles
+ *
+ * Every register operand carries a swizzle: four two-bit lane selectors in bits 8..15, packed as
+ * {@link pack_swizzle} packs them, and stored XOR the identity pattern `.xyzw`
+ * ({@link VM_SWIZZLE_IDENTITY}). That choice is what makes a bare slot index a register operand:
+ * with a zero swizzle byte lane `c` reads slot `base + c`, the run as it lies, and `r5.xxxx` is the
+ * same word with the selectors that name lane 0 four times. Lane `c` of an operand reads slot
+ * `base + selector[c]`, so an operand reaches as far into the file as its widest selector below the
+ * instruction's width — never further, whatever the selectors above the width say.
+ *
+ * Swizzles are why there is no `SWIZZLE` opcode and no `SCALE`: a permutation or a broadcast is a
+ * `MOV` whose source is swizzled, and a vector times a scalar is `MUL v, s.xxxx`. Both were
+ * opcodes that existed to do what an operand can now say for itself, which is the direction the
+ * ISA takes whenever it can — see {@link VM_OP} for the holes they left.
+ *
+ * ## Resolution before execution
+ *
+ * The interpreter reads every source lane before it writes any destination lane. Operands may
+ * therefore overlap the destination in any way — `MOV.2 r0, r0.yx` swaps two slots in place — and
+ * there is no aliasing rule for a program to break. The reductions write one lane whatever they
+ * read (see {@link VM_DEST}); a few opcodes fix their lane count (see {@link VM_WIDTH}).
+ *
+ * There is no control flow: conditionals are `CMP` + `SELECT` and destruction is `KILL`, which
+ * keeps the interpreter a flat `switch` inside a bounded loop.
  */
 
+/** Words per instruction. Four, so an instruction is one `vec4<u32>` fetch. @type {number} */
+export const PARTICLE_VM_INSTRUCTION_WORDS = 4;
+
 /**
- * Operand slot roles, used for documentation, assembler validation and disassembly.
+ * Operand slot roles: what an opcode reads a source slot as. Used for assembler validation,
+ * disassembly and for deriving each slot's {@link VM_KIND}.
  * @enum {string}
  */
 export const VM_OPERAND = {
     /** unused slot (must be 0) */
     NONE: "none",
-    /** register index in `[0, PARTICLE_VM_REGISTER_COUNT)` */
+    /** a register operand — a slot with a swizzle, or a literal */
     REG: "reg",
-    /** destination register index */
-    DST: "dst",
-    /** constant-pool index */
+    /** constant-pool word index */
     CONST: "const",
     /** attribute word offset within the record */
     ATTR_OFFSET: "attr_offset",
@@ -42,10 +82,6 @@ export const VM_OPERAND = {
     BUILTIN: "builtin",
     /** curve handle (row index into the animation-curve table) */
     CURVE: "curve",
-    /** random mode (see {@link VM_RANDOM_MODE}) */
-    RANDOM_MODE: "random_mode",
-    /** packed swizzle pattern: four 2-bit lane selectors, lane i in bits `[2i, 2i+2)` */
-    SWIZZLE: "swizzle",
 };
 
 /**
@@ -53,11 +89,11 @@ export const VM_OPERAND = {
  * @enum {number}
  */
 export const VM_BUILTIN = {
-    /** simulation time-step (seconds), broadcast to all lanes */
+    /** simulation time-step (seconds), in `.x` */
     DELTA_TIME: 0,
     /**
-     * Emitter age (seconds). NOT YET POPULATED — the host passes currently supply 0; per-emitter age
-     * tracking on the GPU is pending. Use {@link VM_BUILTIN.TIME} in effects until it lands.
+     * Emitter age (seconds): how long the emitter's table row has been running, as the emitter tick
+     * pass integrates it on the GPU (`data/PARTICLE_EMITTER_STATE.js`). Restarts with the row.
      */
     EMITTER_AGE: 1,
     /** emitter world position, `.xyz` */
@@ -75,22 +111,26 @@ export const VM_BUILTIN = {
 };
 
 /**
- * Random distribution modes for the `RANDOM` opcode.
- * @enum {number}
+ * How many lanes each builtin fills. The lanes past that read zero when a load is wider — see
+ * `vm_load_builtin` in {@link ../vm/chunk_particle_vm.js} — so this is a builtin's type as far as
+ * a program is concerned, and it is what types a `builtin` node in a graph.
+ *
+ * @type {Object<number, number>}
  */
-export const VM_RANDOM_MODE = {
-    /** four independent uniforms in `[0, 1)` */
-    UNIFORM: 0,
-    /** uniform in `[-1, 1)` per lane */
-    UNIFORM_SIGNED: 1,
-    /** a point on the unit sphere in `.xyz` (w = 0) */
-    UNIT_SPHERE: 2,
-    /** a point in the unit disk in `.xy` (z = w = 0) */
-    UNIT_DISK: 3,
-};
+export const VM_BUILTIN_COMPONENTS = Object.freeze({
+    [VM_BUILTIN.DELTA_TIME]: 1,
+    [VM_BUILTIN.EMITTER_AGE]: 1,
+    [VM_BUILTIN.EMITTER_POSITION]: 3,
+    [VM_BUILTIN.EMITTER_DIRECTION]: 3,
+    [VM_BUILTIN.EMITTER_UP]: 3,
+    [VM_BUILTIN.PARTICLE_INDEX]: 1,
+    [VM_BUILTIN.SPAWN_FRACTION]: 1,
+    [VM_BUILTIN.TIME]: 1,
+});
 
 /**
- * Opcodes. Numbers are stable wire values — never renumber, only append.
+ * Opcodes. Numbers are stable wire values — never renumber, only append. 19 was `SCALE` and 45 was
+ * `SWIZZLE`; both are spelled by an operand swizzle now and the numbers stay unused.
  * @enum {number}
  */
 export const VM_OP = {
@@ -112,7 +152,6 @@ export const VM_OP = {
     MAX: 16,
     MIX: 17,
     CLAMP: 18,
-    SCALE: 19,
 
     NEG: 20,
     ABS: 21,
@@ -126,13 +165,17 @@ export const VM_OP = {
     POW: 29,
     STEP: 30,
     SMOOTHSTEP: 31,
+    RSQRT: 32,
+    TAN: 33,
+    ASIN: 34,
+    ACOS: 35,
+    ATAN2: 36,
 
     DOT: 40,
     CROSS: 41,
     LENGTH: 42,
     NORMALIZE: 43,
     DISTANCE: 44,
-    SWIZZLE: 45,
 
     CMP_LT: 50,
     CMP_LE: 51,
@@ -145,34 +188,436 @@ export const VM_OP = {
     CURVE: 61,
 };
 
-const D = VM_OPERAND.DST;
+/**
+ * How an opcode reads the instruction's width field — the lane count it operates on.
+ * @enum {string}
+ */
+export const VM_WIDTH = {
+    /** operates on no lanes at all (`HALT`, `NOP`) */
+    NONE: "none",
+    /** the width field gives the lane count, `1..4` */
+    VARIABLE: "variable",
+    /** always one lane, whatever the field says (`KILL`) */
+    ONE: "one",
+    /** always three lanes (`CROSS`) */
+    THREE: "three",
+};
+
+/**
+ * How many lanes an opcode writes to its destination, relative to the operation's width.
+ * @enum {string}
+ */
+export const VM_DEST = {
+    /** writes nothing (`HALT`, `NOP`, `STORE_ATTR`, `KILL`) */
+    NONE: "none",
+    /** writes as many lanes as the operation is wide */
+    WIDTH: "width",
+    /** reduces to a single lane, whatever the operation's width (`DOT`, `LENGTH`, `DISTANCE`) */
+    ONE: "one",
+};
+
+/**
+ * Widest an operation may be. Registers hold scalars; four is what a `vec4` value needs and what a
+ * two-bit lane selector can address.
+ * @type {number}
+ */
+export const VM_MAX_WIDTH = 4;
+
+// --- word 0 -----------------------------------------------------------------------------------
+
+/** Mask selecting the opcode out of word 0. @type {number} */
+export const VM_OP_MASK = 0xff;
+
+/** Bit position of the width field in word 0. @type {number} */
+export const VM_WIDTH_SHIFT = 8;
+
+/** Mask selecting the width out of word 0, once shifted down. @type {number} */
+export const VM_WIDTH_MASK = 0x7;
+
+/**
+ * What a source word means. Wire values; never renumber.
+ * @enum {number}
+ */
+export const VM_KIND = {
+    /** not an operand: an unused slot, or a raw field the opcode reads itself */
+    NONE: 0,
+    /** a register operand: base slot in bits 0..7, swizzle in bits 8..15 */
+    REG: 1,
+    /** the `f32` bit pattern of a literal, read in every lane */
+    IMM: 2,
+};
+
+/**
+ * Bit position of the first source's kind in word 0. Source `n` has its two kind bits at
+ * `VM_KIND_SHIFT + 2n`, so the three together are bits 16..21.
+ * @type {number}
+ */
+export const VM_KIND_SHIFT = 16;
+
+/** Bits per kind field. @type {number} */
+export const VM_KIND_BITS = 2;
+
+/** Mask selecting one kind field, once shifted down. @type {number} */
+export const VM_KIND_MASK = 0x3;
+
+/** Mask selecting all three kind fields, once shifted down by {@link VM_KIND_SHIFT}. @type {number} */
+const VM_KINDS_MASK = 0x3f;
+
+/** Bit position of the destination register in word 0. @type {number} */
+export const VM_DST_SHIFT = 24;
+
+/** Mask selecting the destination register out of word 0, once shifted down. @type {number} */
+export const VM_DST_MASK = 0xff;
+
+/**
+ * Pack word 0.
+ *
+ * @param {number} op
+ * @param {number} width lane count, `0..4`
+ * @param {number} dst destination register, `0..255`
+ * @param {number} kinds the three source kinds as one field — see {@link vm_pack_kinds}
+ * @returns {number}
+ */
+export function vm_encode_word0(op, width, dst, kinds) {
+    return (
+        (op & VM_OP_MASK)
+        | ((width & VM_WIDTH_MASK) << VM_WIDTH_SHIFT)
+        | ((kinds & VM_KINDS_MASK) << VM_KIND_SHIFT)
+        | ((dst & VM_DST_MASK) << VM_DST_SHIFT)
+    ) >>> 0;
+}
+
+/**
+ * The three source kinds as the one field {@link vm_encode_word0} takes.
+ *
+ * @param {number} s0
+ * @param {number} s1
+ * @param {number} s2
+ * @returns {number}
+ */
+export function vm_pack_kinds(s0, s1, s2) {
+    return (
+        (s0 & VM_KIND_MASK)
+        | ((s1 & VM_KIND_MASK) << VM_KIND_BITS)
+        | ((s2 & VM_KIND_MASK) << (2 * VM_KIND_BITS))
+    ) >>> 0;
+}
+
+/** @param {number} word0 @returns {number} opcode */
+export function vm_decode_op(word0) {
+    return word0 & VM_OP_MASK;
+}
+
+/** @param {number} word0 @returns {number} lane count */
+export function vm_decode_width(word0) {
+    return (word0 >>> VM_WIDTH_SHIFT) & VM_WIDTH_MASK;
+}
+
+/** @param {number} word0 @returns {number} destination register */
+export function vm_decode_dst(word0) {
+    return (word0 >>> VM_DST_SHIFT) & VM_DST_MASK;
+}
+
+/** @param {number} word0 @returns {number} the three source kinds as one field */
+export function vm_decode_kinds(word0) {
+    return (word0 >>> VM_KIND_SHIFT) & VM_KINDS_MASK;
+}
+
+/**
+ * @param {number} word0
+ * @param {number} slot source slot, `0..2`
+ * @returns {number} a {@link VM_KIND}
+ */
+export function vm_decode_kind(word0, slot) {
+    return (word0 >>> (VM_KIND_SHIFT + slot * VM_KIND_BITS)) & VM_KIND_MASK;
+}
+
+/** @returns {number} word 0 with its width replaced */
+export function vm_with_width(word0, width) {
+    return ((word0 & ~(VM_WIDTH_MASK << VM_WIDTH_SHIFT)) | ((width & VM_WIDTH_MASK) << VM_WIDTH_SHIFT)) >>> 0;
+}
+
+/** @returns {number} word 0 with its destination replaced */
+export function vm_with_dst(word0, dst) {
+    return ((word0 & ~(VM_DST_MASK << VM_DST_SHIFT)) | ((dst & VM_DST_MASK) << VM_DST_SHIFT)) >>> 0;
+}
+
+/** @returns {number} word 0 with one source's kind replaced */
+export function vm_with_kind(word0, slot, kind) {
+    const shift = VM_KIND_SHIFT + slot * VM_KIND_BITS;
+
+    return ((word0 & ~(VM_KIND_MASK << shift)) | ((kind & VM_KIND_MASK) << shift)) >>> 0;
+}
+
+// --- register operands ------------------------------------------------------------------------
+
+/**
+ * Pack a swizzle pattern from four lane selectors: selector `i` in bits `[2i, 2i+2)`, values
+ * 0=x, 1=y, 2=z, 3=w.
+ *
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} w
+ * @returns {number}
+ */
+export function pack_swizzle(x, y, z, w) {
+    return (x & 3) | ((y & 3) << 2) | ((z & 3) << 4) | ((w & 3) << 6);
+}
+
+/**
+ * @param {number} pattern
+ * @param {number} lane
+ * @returns {number} the lane the pattern selects for output lane `lane`
+ */
+export function swizzle_selector(pattern, lane) {
+    return (pattern >>> (2 * lane)) & 3;
+}
+
+/** The pattern that reads a run as it lies: `.xyzw`. @type {number} */
+export const VM_SWIZZLE_IDENTITY = pack_swizzle(0, 1, 2, 3);
+
+/** The pattern that reads lane 0 in every lane: `.xxxx`. @type {number} */
+export const VM_SWIZZLE_BROADCAST = pack_swizzle(0, 0, 0, 0);
+
+/** Mask selecting the base slot out of a register operand word. @type {number} */
+export const VM_OPERAND_BASE_MASK = 0xff;
+
+/** Bit position of the swizzle byte in a register operand word. @type {number} */
+export const VM_OPERAND_SWIZZLE_SHIFT = 8;
+
+/**
+ * A register operand word: a base slot read through a pattern.
+ *
+ * The pattern is stored XOR {@link VM_SWIZZLE_IDENTITY}, so the identity is a zero byte and a bare
+ * slot index is the run at that slot. Nothing else about the word depends on that choice; read the
+ * pattern back with {@link vm_operand_pattern} rather than the bits.
+ *
+ * @param {number} base first register slot
+ * @param {number} [pattern] a packed swizzle; the run as it lies when left out
+ * @returns {number}
+ */
+export function vm_register(base, pattern = VM_SWIZZLE_IDENTITY) {
+    return ((base & VM_OPERAND_BASE_MASK) | (((pattern ^ VM_SWIZZLE_IDENTITY) & 0xff) << VM_OPERAND_SWIZZLE_SHIFT)) >>> 0;
+}
+
+/** @param {number} word a register operand @returns {number} its base slot */
+export function vm_operand_base(word) {
+    return word & VM_OPERAND_BASE_MASK;
+}
+
+/** @param {number} word a register operand @returns {number} its swizzle, as {@link pack_swizzle} packs one */
+export function vm_operand_pattern(word) {
+    return ((word >>> VM_OPERAND_SWIZZLE_SHIFT) & 0xff) ^ VM_SWIZZLE_IDENTITY;
+}
+
+/**
+ * @param {number} word a register operand
+ * @param {number} lane
+ * @returns {number} the slot lane `lane` of the operand reads
+ */
+export function vm_operand_slot(word, lane) {
+    return vm_operand_base(word) + swizzle_selector(vm_operand_pattern(word), lane);
+}
+
+/** @returns {number} the operand moved to another base, keeping its swizzle */
+export function vm_operand_with_base(word, base) {
+    return vm_register(base, vm_operand_pattern(word));
+}
+
+/**
+ * How far into the file a register operand reaches when `lanes` lanes of it are read: one past the
+ * widest selector among them. The selectors above `lanes` are never read and do not count.
+ *
+ * @param {number} word a register operand
+ * @param {number} lanes how many lanes the instruction reads of it
+ * @returns {number}
+ */
+export function vm_operand_span(word, lanes) {
+    const pattern = vm_operand_pattern(word);
+
+    let span = 1;
+
+    for (let lane = 0; lane < lanes; lane++) {
+        span = Math.max(span, swizzle_selector(pattern, lane) + 1);
+    }
+
+    return span;
+}
+
+/**
+ * The canonical spelling of a register operand read at `lanes` lanes: the base is the lowest slot
+ * any lane reads, and selectors above the lanes read are the identity, since they name nothing. So
+ * `r0.yz` is `r1`, `r0.zy` is `r1.yx`, and a broadcast of lane 3 is the run at lane 3 — one
+ * spelling per meaning, which is what lets two instructions be compared word for word.
+ *
+ * @param {number} word a register operand
+ * @param {number} lanes how many lanes the instruction reads of it
+ * @returns {number}
+ */
+export function vm_canonical_register(word, lanes) {
+    const pattern = vm_operand_pattern(word);
+
+    let lowest = lanes > 0 ? 3 : 0;
+
+    for (let lane = 0; lane < lanes; lane++) {
+        lowest = Math.min(lowest, swizzle_selector(pattern, lane));
+    }
+
+    let canonical = 0;
+
+    for (let lane = 0; lane < VM_MAX_WIDTH; lane++) {
+        const selector = lane < lanes ? swizzle_selector(pattern, lane) - lowest : lane;
+
+        canonical |= selector << (2 * lane);
+    }
+
+    return vm_register(vm_operand_base(word) + lowest, canonical);
+}
+
+// --- immediates -------------------------------------------------------------------------------
+
+/** Scratch for converting between a literal and its bits. */
+const F32_SCRATCH = new Float32Array(1);
+
+/** @type {Uint32Array} the same four bytes */
+const U32_SCRATCH = new Uint32Array(F32_SCRATCH.buffer);
+
+/** @param {number} value @returns {number} the `f32` bit pattern the value rounds to */
+export function vm_f32_bits(value) {
+    F32_SCRATCH[0] = value;
+
+    return U32_SCRATCH[0];
+}
+
+/** @param {number} bits @returns {number} the `f32` those bits are */
+export function vm_f32_value(bits) {
+    U32_SCRATCH[0] = bits;
+
+    return F32_SCRATCH[0];
+}
+
+/**
+ * A literal source operand, as `InstructionStream.emit` takes one in a source slot.
+ *
+ * @param {number} value
+ * @returns {{kind: number, word: number}}
+ */
+export function vm_immediate(value) {
+    return { kind: VM_KIND.IMM, word: vm_f32_bits(value) };
+}
+
+// --- the opcode table -------------------------------------------------------------------------
+
+/**
+ * Widths are read out of the opcode's metadata; see {@link VM_ISA}.
+ *
+ * @param {number} op
+ * @param {number} width the instruction's width field
+ * @returns {number} the lane count the opcode actually operates on
+ */
+export function vm_operation_width(op, width) {
+    const meta = VM_ISA.get(op);
+
+    if (meta === undefined) {
+        return 0;
+    }
+
+    switch (meta.width) {
+        case VM_WIDTH.NONE: return 0;
+        case VM_WIDTH.ONE: return 1;
+        case VM_WIDTH.THREE: return 3;
+        default: return width;
+    }
+}
+
+/**
+ * How many lanes an instruction writes to its destination register.
+ * @param {number} op
+ * @param {number} width the instruction's width field
+ * @returns {number}
+ */
+export function vm_dest_width(op, width) {
+    const meta = VM_ISA.get(op);
+
+    if (meta === undefined) {
+        return 0;
+    }
+
+    switch (meta.dest) {
+        case VM_DEST.NONE: return 0;
+        case VM_DEST.ONE: return 1;
+        default: return vm_operation_width(op, width);
+    }
+}
+
 const R = VM_OPERAND.REG;
 const _ = VM_OPERAND.NONE;
 
 /**
- * Per-opcode metadata: mnemonic + the role of each of the three operand slots `[s0, s1, s2]`.
+ * Per-opcode metadata: mnemonic, whether it writes a destination, and the role of each source slot.
  *
  * Keyed by opcode number. Used by the assembler for validation/disassembly and by the parity
  * meta-test to enforce that every opcode is handled by both executors.
- * @type {Map<number, {name: string, dst: boolean, operands: [string, string, string]}>}
+ * @type {Map<number, {name: string, dst: boolean, operands: [string, string, string], width: string, dest: string, default_width: number, min_width: number, scalar_operands: number[]}>}
  */
 export const VM_ISA = new Map();
 
-function def(op, name, dst, s0 = _, s1 = _, s2 = _) {
+/**
+ * @param {number} op
+ * @param {string} name
+ * @param {boolean} dst whether the opcode writes a destination register
+ * @param {string} [s0]
+ * @param {string} [s1]
+ * @param {string} [s2]
+ * @param {object} [options]
+ * @param {string} [options.width] see {@link VM_WIDTH}; variable unless the opcode's lane count is fixed
+ * @param {string} [options.dest] see {@link VM_DEST}; as wide as the operation unless it reduces
+ * @param {number} [options.default_width] width the assembler uses when the text does not say
+ * @param {number} [options.min_width] narrowest the opcode is meaningful at
+ * @param {number[]} [options.scalar_operands] source slots read as a single lane whatever the width
+ */
+function def(op, name, dst, s0 = _, s1 = _, s2 = _, options = {}) {
     if (VM_ISA.has(op)) {
         throw new Error(`Duplicate opcode ${op} (${name})`);
     }
-    VM_ISA.set(op, { name, dst, operands: [s0, s1, s2] });
+
+    const width = options.width ?? VM_WIDTH.VARIABLE;
+    const dest = dst ? (options.dest ?? VM_DEST.WIDTH) : VM_DEST.NONE;
+
+    let default_width = options.default_width ?? VM_MAX_WIDTH;
+
+    if (width === VM_WIDTH.NONE) {
+        default_width = 0;
+    } else if (width === VM_WIDTH.ONE) {
+        default_width = 1;
+    } else if (width === VM_WIDTH.THREE) {
+        default_width = 3;
+    }
+
+    VM_ISA.set(op, {
+        name,
+        dst,
+        operands: [s0, s1, s2],
+        width,
+        dest,
+        default_width,
+        min_width: options.min_width ?? 1,
+        scalar_operands: options.scalar_operands ?? [],
+    });
 }
 
-def(VM_OP.HALT, "HALT", false);
-def(VM_OP.NOP, "NOP", false);
+def(VM_OP.HALT, "HALT", false, _, _, _, { width: VM_WIDTH.NONE });
+def(VM_OP.NOP, "NOP", false, _, _, _, { width: VM_WIDTH.NONE });
 def(VM_OP.MOV, "MOV", true, R);
 def(VM_OP.LOAD_CONST, "LOAD_CONST", true, VM_OPERAND.CONST);
 def(VM_OP.LOAD_ATTR, "LOAD_ATTR", true, VM_OPERAND.ATTR_OFFSET, VM_OPERAND.COMP);
-def(VM_OP.STORE_ATTR, "STORE_ATTR", true, VM_OPERAND.ATTR_OFFSET, VM_OPERAND.COMP); // dst slot holds the SOURCE register
+// The value to store is an ordinary source — a register run or a literal — and the width must equal
+// the component count, since a store cannot write lanes the value does not have.
+def(VM_OP.STORE_ATTR, "STORE_ATTR", false, R, VM_OPERAND.ATTR_OFFSET, VM_OPERAND.COMP);
 def(VM_OP.LOAD_BUILTIN, "LOAD_BUILTIN", true, VM_OPERAND.BUILTIN);
-def(VM_OP.KILL, "KILL", true); // dst slot holds the CONDITION register
+// The condition is one lane of an ordinary source.
+def(VM_OP.KILL, "KILL", false, R, _, _, { width: VM_WIDTH.ONE });
 
 def(VM_OP.ADD, "ADD", true, R, R);
 def(VM_OP.SUB, "SUB", true, R, R);
@@ -183,7 +628,6 @@ def(VM_OP.MIN, "MIN", true, R, R);
 def(VM_OP.MAX, "MAX", true, R, R);
 def(VM_OP.MIX, "MIX", true, R, R, R);
 def(VM_OP.CLAMP, "CLAMP", true, R, R, R);
-def(VM_OP.SCALE, "SCALE", true, R, R);
 
 def(VM_OP.NEG, "NEG", true, R);
 def(VM_OP.ABS, "ABS", true, R);
@@ -197,13 +641,23 @@ def(VM_OP.LOG, "LOG", true, R);
 def(VM_OP.POW, "POW", true, R, R);
 def(VM_OP.STEP, "STEP", true, R, R);
 def(VM_OP.SMOOTHSTEP, "SMOOTHSTEP", true, R, R, R);
+def(VM_OP.RSQRT, "RSQRT", true, R);
+def(VM_OP.TAN, "TAN", true, R);
+def(VM_OP.ASIN, "ASIN", true, R);
+def(VM_OP.ACOS, "ACOS", true, R);
+// `atan2(y, x)`: the angle of the point, with the quadrant the signs put it in — so the first
+// source is the one a plot puts on the vertical axis, as it is in every shading language.
+def(VM_OP.ATAN2, "ATAN2", true, R, R);
 
-def(VM_OP.DOT, "DOT", true, R, R);
-def(VM_OP.CROSS, "CROSS", true, R, R);
-def(VM_OP.LENGTH, "LENGTH", true, R);
-def(VM_OP.NORMALIZE, "NORMALIZE", true, R);
-def(VM_OP.DISTANCE, "DISTANCE", true, R, R);
-def(VM_OP.SWIZZLE, "SWIZZLE", true, R, VM_OPERAND.SWIZZLE);
+// The reductions read `width` lanes and write one. Whatever wants the result wider reads it through
+// an `.xxxx` swizzle, which is what tracking widths is for.
+def(VM_OP.DOT, "DOT", true, R, R, _, { dest: VM_DEST.ONE, default_width: 3 });
+// A cross product is three lanes wide. It may be asked for a fourth, which it writes as zero, but
+// never for fewer, so `min_width` is a floor rather than a fix.
+def(VM_OP.CROSS, "CROSS", true, R, R, _, { default_width: 3, min_width: 3 });
+def(VM_OP.LENGTH, "LENGTH", true, R, _, _, { dest: VM_DEST.ONE, default_width: 3 });
+def(VM_OP.NORMALIZE, "NORMALIZE", true, R, _, _, { default_width: 3 });
+def(VM_OP.DISTANCE, "DISTANCE", true, R, R, _, { dest: VM_DEST.ONE, default_width: 3 });
 
 def(VM_OP.CMP_LT, "CMP_LT", true, R, R);
 def(VM_OP.CMP_LE, "CMP_LE", true, R, R);
@@ -212,27 +666,201 @@ def(VM_OP.CMP_GE, "CMP_GE", true, R, R);
 def(VM_OP.CMP_EQ, "CMP_EQ", true, R, R);
 def(VM_OP.SELECT, "SELECT", true, R, R, R);
 
-def(VM_OP.RANDOM, "RANDOM", true, VM_OPERAND.RANDOM_MODE);
-def(VM_OP.CURVE, "CURVE", true, VM_OPERAND.CURVE, R);
+// One independent uniform draw in `[0, 1)` per lane, and nothing else: a shaped distribution is
+// arithmetic a program writes over this draw — see ../graph/particle_graph_distributions.js.
+def(VM_OP.RANDOM, "RANDOM", true);
+// `t` is one lane; the sampled value fills the destination's width.
+def(VM_OP.CURVE, "CURVE", true, VM_OPERAND.CURVE, R, _, { scalar_operands: [1] });
+
+// --- packing an instruction ---------------------------------------------------------------------
 
 /**
+ * The four words of an instruction, with every register operand in its canonical spelling.
+ *
+ * Both the assembler's `InstructionStream.emit` and the assembly parser build instructions here, so
+ * the one encoding rule that is a choice rather than a fact — how a swizzle is spelled — is made in
+ * one place: selectors above the lanes an operand is read at are the identity, and a run of
+ * consecutive selectors is the identity at a higher base. Two instructions that mean the same thing
+ * then have the same words, which is what lets the optimizer compare them.
+ *
  * @param {number} op
- * @returns {string} mnemonic, or `OP_<n>` if unknown
+ * @param {number} width lane count, `0..4`
+ * @param {number} dst destination register
+ * @param {number[]} kinds a {@link VM_KIND} per source slot
+ * @param {number[]} sources the three source words
+ * @returns {number[]}
  */
-export function vm_op_name(op) {
+export function vm_pack_instruction(op, width, dst, kinds, sources) {
     const meta = VM_ISA.get(op);
-    return meta === undefined ? `OP_${op}` : meta.name;
+    const operation_width = vm_operation_width(op, width);
+    const words = [vm_encode_word0(op, width, dst, vm_pack_kinds(kinds[0], kinds[1], kinds[2])), 0, 0, 0];
+
+    for (let slot = 0; slot < 3; slot++) {
+        const word = sources[slot] >>> 0;
+
+        words[1 + slot] = kinds[slot] === VM_KIND.REG && meta !== undefined
+            ? vm_canonical_register(word, meta.scalar_operands.includes(slot) ? 1 : operation_width)
+            : word;
+    }
+
+    return words;
 }
 
 /**
- * Pack a swizzle pattern from four lane selectors into the 8-bit form used by the `SWIZZLE` opcode.
- * Selector values: 0=x, 1=y, 2=z, 3=w.
- * @param {number} x
- * @param {number} y
- * @param {number} z
- * @param {number} w
- * @returns {number}
+ * An encoded instruction, re-spelled canonically — what a pass wants after it has moved an operand.
+ *
+ * @param {ArrayLike<number>} words the four words of a single instruction
+ * @returns {number[]}
  */
-export function pack_swizzle(x, y, z, w) {
-    return (x & 3) | ((y & 3) << 2) | ((z & 3) << 4) | ((w & 3) << 6);
+export function vm_repack_instruction(words) {
+    const word0 = words[0];
+
+    return vm_pack_instruction(
+        vm_decode_op(word0),
+        vm_decode_width(word0),
+        vm_decode_dst(word0),
+        [vm_decode_kind(word0, 0), vm_decode_kind(word0, 1), vm_decode_kind(word0, 2)],
+        [words[1], words[2], words[3]]
+    );
+}
+
+// --- reading an instruction ---------------------------------------------------------------------
+
+/**
+ * @typedef {object} ParticleVMOperand
+ * @property {number} slot source slot, `0..2`
+ * @property {number} kind a {@link VM_KIND}, never `NONE`
+ * @property {number} word the source word as encoded
+ * @property {number} lanes how many lanes the instruction reads of it: the operation's width, or one
+ *   for a slot the ISA marks scalar
+ * @property {number} span register slots the operand reaches from its base, for a register; `0` for a
+ *   literal
+ */
+
+/**
+ * Visit every source operand of an instruction — every slot whose kind is not `NONE` — with how
+ * many lanes the opcode reads of it and how far into the file it reaches.
+ *
+ * The rules for the reach are not uniform and live here rather than in each caller: a source is
+ * read as wide as the operation runs unless the ISA marks that slot scalar, and a register operand
+ * reaches as far as its widest selector among the lanes read.
+ *
+ * @param {ArrayLike<number>} words an instruction stream
+ * @param {number} base index of the instruction's first word
+ * @param {function(ParticleVMOperand):void} visit the one object is reused between calls; copy it
+ *   to keep it
+ */
+export function vm_visit_operands(words, base, visit) {
+    const word0 = words[base];
+    const op = vm_decode_op(word0);
+    const meta = VM_ISA.get(op);
+
+    if (meta === undefined) {
+        return;
+    }
+
+    const operation_width = vm_operation_width(op, vm_decode_width(word0));
+    const operand = { slot: 0, kind: 0, word: 0, lanes: 0, span: 0 };
+
+    for (let slot = 0; slot < 3; slot++) {
+        const kind = vm_decode_kind(word0, slot);
+
+        if (kind === VM_KIND.NONE) {
+            continue;
+        }
+
+        const word = words[base + 1 + slot];
+        const lanes = meta.scalar_operands.includes(slot) ? 1 : operation_width;
+
+        operand.slot = slot;
+        operand.kind = kind;
+        operand.word = word;
+        operand.lanes = lanes;
+        operand.span = kind === VM_KIND.REG ? vm_operand_span(word, lanes) : 0;
+        visit(operand);
+    }
+}
+
+/**
+ * Visit every run of the register file an instruction touches, as the slot it starts at and how
+ * many consecutive slots it reaches: the destination as far as the opcode writes, and each register
+ * source as far as its selectors read. What anyone sizing or bounds-checking the file wants; a
+ * literal is not a run of the file and is not visited.
+ *
+ * @param {ArrayLike<number>} words an instruction stream
+ * @param {number} base index of the instruction's first word
+ * @param {function(number, number):void} visit called `(slot, span)` per run
+ */
+export function vm_visit_register_runs(words, base, visit) {
+    const word0 = words[base];
+    const op = vm_decode_op(word0);
+    const dest = vm_dest_width(op, vm_decode_width(word0));
+
+    if (dest > 0) {
+        visit(vm_decode_dst(word0), dest);
+    }
+
+    vm_visit_operands(words, base, (operand) => {
+        if (operand.kind === VM_KIND.REG) {
+            visit(vm_operand_base(operand.word), operand.span);
+        }
+    });
+}
+
+/**
+ * Whether the kind bits of an instruction agree with what its opcode reads: a register-role slot
+ * carries a register or a literal, every other slot carries nothing. Both the assembler and
+ * `ParticleProgram.validate` ask here rather than each restating the rule.
+ *
+ * @param {ArrayLike<number>} words an instruction stream
+ * @param {number} base index of the instruction's first word
+ * @returns {string|null} what is wrong, or `null` when nothing is
+ */
+export function vm_kinds_problem(words, base) {
+    const word0 = words[base];
+    const meta = VM_ISA.get(vm_decode_op(word0));
+
+    if (meta === undefined) {
+        return null;
+    }
+
+    for (let slot = 0; slot < 3; slot++) {
+        const kind = vm_decode_kind(word0, slot);
+        const role = meta.operands[slot];
+
+        if (kind > VM_KIND.IMM) {
+            return `s${slot} has operand kind ${kind}, which the ISA does not define`;
+        }
+
+        if (role === VM_OPERAND.REG && kind === VM_KIND.NONE) {
+            return `s${slot} of ${meta.name} must be a register or a literal`;
+        }
+
+        if (role !== VM_OPERAND.REG && kind !== VM_KIND.NONE) {
+            return `s${slot} of ${meta.name} is ${role === VM_OPERAND.NONE ? "unused" : `a ${role}`} and has no kind`;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * The kinds an opcode's sources carry when every register-role slot holds a register: the default
+ * an assembler starts from, before any literal is marked.
+ *
+ * @param {number} op
+ * @returns {number} a kinds field for {@link vm_encode_word0}
+ */
+export function vm_register_kinds(op) {
+    const meta = VM_ISA.get(op);
+
+    if (meta === undefined) {
+        return 0;
+    }
+
+    return vm_pack_kinds(
+        meta.operands[0] === R ? VM_KIND.REG : VM_KIND.NONE,
+        meta.operands[1] === R ? VM_KIND.REG : VM_KIND.NONE,
+        meta.operands[2] === R ? VM_KIND.REG : VM_KIND.NONE
+    );
 }