@woosh/meep-engine 3.16.0 → 3.17.0

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

@@ -6,17 +6,28 @@ import {
 } from "../ParticleConstants.js";
 import { ParticleProgram } from "./ParticleProgram.js";
 import {
+    pack_swizzle,
+    swizzle_selector,
     VM_BUILTIN,
     VM_ISA,
+    VM_KIND,
     VM_MAX_WIDTH,
     VM_OP,
     VM_OPERAND,
+    VM_SWIZZLE_BROADCAST,
     VM_WIDTH,
+    vm_decode_dst,
+    vm_decode_kind,
     vm_decode_op,
     vm_decode_width,
-    vm_encode_word0,
+    vm_f32_bits,
+    vm_f32_value,
+    vm_operand_base,
+    vm_operand_pattern,
     vm_operation_width,
-    vm_visit_register_operands,
+    vm_pack_instruction,
+    vm_register,
+    vm_visit_register_runs,
 } from "./ParticleVMISA.js";
 
 /**
@@ -42,12 +53,13 @@ import {
  * .init                         ; section — everything until the next section directive
  *   LOAD_BUILTIN.3 r0, EMITTER_POSITION
  *   RANDOM.2 r1
- *   SCALE.2 r1, r1, r2
+ *   MUL.2 r1, r1, #0.5          ; a literal where a register could stand
  *   STORE_ATTR r1, @1, 3        ; store r1 into the 3-component attribute at record word 1
  *
  * .update
  *   LOAD_ATTR.1 r0, @7, 1
  *   CMP_GE.1 r0, r0, r1
+ *   MOV.3 r2, r0.xxx            ; a register read through a swizzle: lane 0 three times
  *   KILL r0
  * ```
  *
@@ -62,16 +74,24 @@ import {
  *
  * | role | spelling | example |
  * |---|---|---|
- * | register / destination | `r<slot>` | `r3` |
+ * | destination | `r<slot>` | `r3` |
+ * | register source | `r<slot>`, optionally `.<selectors>` | `r3`, `r3.yyy`, `r0.zyx` |
+ * | literal source | `#<float>` | `#1.5` |
  * | constant-pool word | `c<word>` | `c0` |
  * | attribute word offset | `@<word>` | `@7` |
  * | attribute component count | a bare integer `1..4` | `3` |
  * | builtin | a {@link VM_BUILTIN} name | `EMITTER_POSITION` |
  * | curve handle | `k<handle>` | `k2` |
- * | swizzle pattern | `.<four of xyzw>` | `.xxyz` |
  *
- * `STORE_ATTR` and `KILL` carry a *source* register in the destination slot — the ISA's own
- * encoding, spelled here the way it is encoded rather than reordered to read like a store.
+ * A register source's selectors say which lane of the value each lane of the instruction reads, one
+ * letter of `xyzw` per lane the instruction spans; left off, lane `c` reads lane `c`. A literal is
+ * the same value in every lane. The destination is only ever a plain register.
+ *
+ * ## What older text still means
+ *
+ * Two mnemonics that were opcodes are now spellings of an operand, and documents that carry them read
+ * as the instruction they meant: `SWIZZLE.n rd, rs, .xyzw` is `MOV.n rd, rs.xyzw`, and `SCALE.n rd,
+ * rv, rs` is `MUL.n rd, rv, rs.xxxx`. The disassembler never writes either.
  */
 
 /** Section directive introducing the INIT stream. @type {string} */
@@ -86,11 +106,12 @@ export const PARTICLE_ASSEMBLY_DIRECTIVE_REGISTERS = ".registers";
 /** Directive declaring one constant-pool entry. @type {string} */
 export const PARTICLE_ASSEMBLY_DIRECTIVE_CONST = ".const";
 
+/** Opens a literal in a register slot: `#1.5`. @type {string} */
+export const PARTICLE_ASSEMBLY_IMMEDIATE_PREFIX = "#";
+
 /**
- * Separates a mnemonic from the lane count it spans: `ADD.3`.
- *
- * The same character opens a directive and a swizzle pattern, but never in this position — a line
- * starts with either a directive or a mnemonic, and a swizzle is an operand.
+ * Separates a mnemonic from the lane count it spans: `ADD.3`. Also separates a register from its
+ * selectors: `r3.yyy`. The same character opens a directive, but never in either of those positions.
  *
  * @type {string}
  */
@@ -104,18 +125,21 @@ export const PARTICLE_ASSEMBLY_WIDTH_SEPARATOR = ".";
  * a bound the parser tries to allocate that pool and takes the page with it, which is a worse answer
  * to a typo than a marker on the line.
  *
- * Generous against any real program: an effect's constants are its literals, and the whole
- * instruction budget is {@link PARTICLE_VM_MAX_INSTRUCTIONS} per section.
- *
  * @type {number}
  */
 export const PARTICLE_ASSEMBLY_MAX_CONSTANTS = 4096;
 
+/** Lane selector characters, indexed by the 2-bit selector value a swizzle packs. @type {string} */
+const SWIZZLE_LANES = "xyzw";
+
 /**
- * Lane selector characters, indexed by the 2-bit selector value the `SWIZZLE` opcode packs.
- * @type {string}
+ * Mnemonics that were opcodes and are now operand spellings, read for the documents that carry them.
+ * @type {Map<string, {op: number, form: string}>}
  */
-const SWIZZLE_LANES = "xyzw";
+const LEGACY_MNEMONICS = new Map([
+    ["SWIZZLE", { op: VM_OP.MOV, form: "swizzle" }],
+    ["SCALE", { op: VM_OP.MUL, form: "scale" }],
+]);
 
 /**
  * Mnemonic -> opcode, derived from {@link VM_ISA} so the two cannot drift.
@@ -154,6 +178,10 @@ const BUILTIN_NAME_BY_ID = invert(VM_BUILTIN);
  * @property {string} message
  */
 
+// ---------------------------------------------------------------------------------------------
+// Disassembly
+// ---------------------------------------------------------------------------------------------
+
 /**
  * Render a compiled program as assembly text.
  *
@@ -216,13 +244,14 @@ function disassemble_instruction(words, base) {
     if (meta === undefined) {
         // Not reachable from a validated program, but a disassembler that throws is useless for
         // looking at the thing that went wrong.
-        return `; unknown opcode ${op} [${words[base + 1]}, ${words[base + 2]}, ${words[base + 3]}, ${words[base + 4]}]`;
+        return `; unknown opcode ${op} [${words[base + 1]}, ${words[base + 2]}, ${words[base + 3]}]`;
     }
 
+    const operation_width = vm_operation_width(op, width);
     const operands = [];
 
     if (meta.dst) {
-        operands.push(`r${words[base + 1]}`);
+        operands.push(`r${vm_decode_dst(word0)}`);
     }
 
     for (let slot = 0; slot < 3; slot++) {
@@ -232,7 +261,15 @@ function disassemble_instruction(words, base) {
             continue;
         }
 
-        operands.push(format_operand(role, words[base + 2 + slot]));
+        const word = words[base + 1 + slot];
+
+        if (role !== VM_OPERAND.REG) {
+            operands.push(format_operand(role, word));
+        } else if (vm_decode_kind(word0, slot) === VM_KIND.IMM) {
+            operands.push(`${PARTICLE_ASSEMBLY_IMMEDIATE_PREFIX}${format_float(vm_f32_value(word))}`);
+        } else {
+            operands.push(format_register(word, meta.scalar_operands.includes(slot) ? 1 : operation_width));
+        }
     }
 
     const mnemonic = meta.name + format_width_suffix(op, meta, width);
@@ -262,15 +299,36 @@ function format_width_suffix(op, meta, width) {
 }
 
 /**
- * @param {string} role a {@link VM_OPERAND} value
+ * A register source: its slot, and the selectors of the lanes read wherever they are not the lane
+ * itself.
+ *
+ * @param {number} word a register operand
+ * @param {number} lanes lanes the instruction reads of it
+ * @returns {string}
+ */
+function format_register(word, lanes) {
+    const pattern = vm_operand_pattern(word);
+
+    let identity = true;
+    let selectors = "";
+
+    for (let lane = 0; lane < lanes; lane++) {
+        const selector = swizzle_selector(pattern, lane);
+
+        identity = identity && selector === lane;
+        selectors += SWIZZLE_LANES.charAt(selector);
+    }
+
+    return `r${vm_operand_base(word)}${identity ? "" : PARTICLE_ASSEMBLY_WIDTH_SEPARATOR + selectors}`;
+}
+
+/**
+ * @param {string} role a {@link VM_OPERAND} value other than the register one
  * @param {number} value
  * @returns {string}
  */
 function format_operand(role, value) {
     switch (role) {
-        case VM_OPERAND.REG:
-        case VM_OPERAND.DST:
-            return `r${value}`;
         case VM_OPERAND.CONST:
             return `c${value}`;
         case VM_OPERAND.ATTR_OFFSET:
@@ -281,27 +339,11 @@ function format_operand(role, value) {
             return BUILTIN_NAME_BY_ID.get(value) ?? String(value);
         case VM_OPERAND.CURVE:
             return `k${value}`;
-        case VM_OPERAND.SWIZZLE:
-            return format_swizzle(value);
         default:
             return String(value);
     }
 }
 
-/**
- * @param {number} packed four 2-bit lane selectors
- * @returns {string} `.xyzw` form
- */
-function format_swizzle(packed) {
-    let result = ".";
-
-    for (let lane = 0; lane < 4; lane++) {
-        result += SWIZZLE_LANES.charAt((packed >>> (lane * 2)) & 3);
-    }
-
-    return result;
-}
-
 /**
  * A float spelled so it reads back as itself.
  *
@@ -335,6 +377,10 @@ function format_float(value) {
     return String(value);
 }
 
+// ---------------------------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------------------------
+
 /**
  * Read assembly text into a program, reporting every problem rather than stopping at the first.
  *
@@ -353,7 +399,7 @@ export function parse_particle_assembly(text) {
 
     const report = (line, message) => diagnostics.push({ line, message });
 
-    /** @type {number[]} flat constant pool, 4 floats per entry */
+    /** @type {number[]} flat constant pool, one float per word */
     const constants = [];
     /** @type {Set<number>} constant indices a `.const` directive has already claimed */
     const declared_constants = new Set();
@@ -446,7 +492,7 @@ export function parse_particle_assembly(text) {
     }
 
     // dense constant indices: c0..cN-1 with nothing missing, so a pool index means the same thing
-    // here as it does in the arena
+    // here as it does in the heap
     for (let i = 0; i < constants.length; i++) {
         if (!declared_constants.has(i)) {
             report(0, `Constant c${i} is referenced by the pool's length but never declared`);
@@ -456,7 +502,7 @@ export function parse_particle_assembly(text) {
     const register_count = declared_register_count === -1 ? register_high_water : declared_register_count;
 
     if (register_count > PARTICLE_VM_REGISTER_SLOTS) {
-        report(0, `Register file is ${PARTICLE_VM_REGISTER_SLOTS} slots, the program asks for ${register_count}`);
+        report(0, `A VM instruction can address ${PARTICLE_VM_REGISTER_SLOTS} slots, the program asks for ${register_count}`);
     }
 
     const constant_word_count = constants.length;
@@ -532,11 +578,12 @@ function check_stream_references(stream, register_count, constant_word_count, re
     for (let i = 0; i < instruction_count; i++) {
         const base = i * PARTICLE_VM_INSTRUCTION_WORDS;
         const line = stream.lines[i];
-        const meta = VM_ISA.get(vm_decode_op(words[base]));
+        const op = vm_decode_op(words[base]);
+        const meta = VM_ISA.get(op);
 
         // An operand of width w occupies w consecutive slots, so it is the END of the run that has
         // to be inside the file: `MOV.4 r30` starts inside a 32-slot file and finishes outside one.
-        vm_visit_register_operands(words, base, (index, span) => {
+        vm_visit_register_runs(words, base, (index, span) => {
             if (index + span <= register_count) {
                 return;
             }
@@ -550,29 +597,27 @@ function check_stream_references(stream, register_count, constant_word_count, re
             );
         });
 
-        for (let slot = 0; slot < 3; slot++) {
-            const role = meta.operands[slot];
-            const value = words[base + 2 + slot];
-
-            if (role === VM_OPERAND.CONST) {
-                // The load reads one word per lane, so the whole run has to be inside the pool.
-                const span = vm_operation_width(vm_decode_op(words[base]), vm_decode_width(words[base]));
+        if (op === VM_OP.LOAD_CONST) {
+            // The load reads one word per lane, so the whole run has to be inside the pool.
+            const first = words[base + 1];
+            const span = vm_operation_width(op, vm_decode_width(words[base]));
 
-                if (value + span > constant_word_count) {
-                    report(
-                        line,
-                        `c${value} reads ${span} word${span === 1 ? "" : "s"}, past the end of the `
-                        + `${constant_word_count}-word constant pool`
-                    );
-                }
+            if (first + span > constant_word_count) {
+                report(
+                    line,
+                    `c${first} reads ${span} word${span === 1 ? "" : "s"}, past the end of the `
+                    + `${constant_word_count}-word constant pool`
+                );
             }
         }
 
         // An attribute access past the end of a record is not caught by GPU robustness: the address
         // still lands inside the pool buffer, and reads or corrupts the NEXT particle's record.
-        if (meta.operands[0] === VM_OPERAND.ATTR_OFFSET) {
-            const offset = words[base + 2];
-            const components = words[base + 3];
+        const offset_slot = meta.operands.indexOf(VM_OPERAND.ATTR_OFFSET);
+
+        if (offset_slot !== -1) {
+            const offset = words[base + 1 + offset_slot];
+            const components = words[base + 2 + offset_slot];
 
             if (offset + components > PARTICLE_RECORD_WORD_COUNT) {
                 report(
@@ -671,6 +716,14 @@ function parse_directive(line, line_number, report) {
     return null;
 }
 
+/**
+ * @typedef {object} ParsedOperand
+ * @property {number} kind a {@link VM_KIND}: `REG` or `IMM` for a register-role slot, `NONE` for any other
+ * @property {number} word the operand word
+ * @property {number} [selectors] for a register written with selectors, how many the text spelled
+ * @property {string} [token] the text the operand was read from, for messages
+ */
+
 /**
  * @param {string} line already stripped of comments and trimmed
  * @param {number} line_number
@@ -688,7 +741,8 @@ function parse_instruction(line, line_number, report) {
     const mnemonic = separator === -1 ? head : head.slice(0, separator);
     const width_text = separator === -1 ? "" : head.slice(separator + 1);
 
-    const opcode = OPCODE_BY_NAME.get(mnemonic);
+    const legacy = LEGACY_MNEMONICS.get(mnemonic) ?? null;
+    const opcode = legacy === null ? OPCODE_BY_NAME.get(mnemonic) : legacy.op;
 
     if (opcode === undefined) {
         report(line_number, `Unknown instruction '${mnemonic}'`);
@@ -723,11 +777,88 @@ function parse_instruction(line, line_number, report) {
 
     const tokens = rest.split(",").map(t => t.trim()).filter(t => t !== "");
 
-    /** roles the operands fill, in the order they are written */
+    const parsed = legacy === null
+        ? parse_operands(meta, tokens, line_number, report)
+        : parse_legacy_operands(legacy.form, mnemonic, tokens, line_number, report);
+
+    if (parsed === null) {
+        return null;
+    }
+
+    const { dst, sources } = parsed;
+
+    // The attribute ops measure themselves in components unless the text says otherwise: a load may
+    // be widened past its attribute (the lanes beyond read zero), a store may not — it writes one
+    // record word per lane, so its width IS the component count.
+    if (opcode === VM_OP.LOAD_ATTR && width_text === "") {
+        width = sources[1].word;
+    }
+
+    if (opcode === VM_OP.STORE_ATTR) {
+        if (width_text !== "" && width !== sources[2].word) {
+            report(line_number, `STORE_ATTR width ${width} must equal its component count ${sources[2].word}`);
+            return null;
+        }
+
+        width = sources[2].word;
+    }
+
+    // Selectors are written one per lane read, and the lane count is known only now that the width
+    // is: `r6.xx` on a three-lane read would otherwise quietly be `r6.xxz`.
+    const operation_width = vm_operation_width(opcode, width);
+
+    for (let slot = 0; slot < sources.length; slot++) {
+        const source = sources[slot];
+        const lanes = meta.scalar_operands.includes(slot) ? 1 : operation_width;
+
+        if (source.kind === VM_KIND.REG && source.selectors !== undefined && source.selectors > 0 && source.selectors !== lanes) {
+            report(
+                line_number,
+                `${meta.name} reads ${lanes} lane${lanes === 1 ? "" : "s"} of '${source.token}', `
+                + `which names ${source.selectors} selector${source.selectors === 1 ? "" : "s"}; write one per lane`
+            );
+            return null;
+        }
+    }
+
+    const words = vm_pack_instruction(
+        opcode,
+        width,
+        dst,
+        sources.map(source => source.kind),
+        sources.map(source => source.word)
+    );
+
+    // Registers are scalar slots, so what the file has to hold is where the widest operand ENDS.
+    // Sizing it by the largest index written down leaves a `RANDOM.3 r0` writing r1 and r2 outside
+    // the file it derived, which the interpreter reads back as zero and the reference as nothing.
+    let register_reach = 0;
+
+    vm_visit_register_runs(words, 0, (slot, span) => {
+        if (slot + span > register_reach) {
+            register_reach = slot + span;
+        }
+    });
+
+    return { words, register_reach };
+}
+
+/**
+ * The operands of an ordinary instruction, in the order they are written: the destination when the
+ * opcode has one, then every source whose role is not `NONE`.
+ *
+ * @param {object} meta the opcode's {@link VM_ISA} entry
+ * @param {string[]} tokens
+ * @param {number} line_number
+ * @param {function(number, string):void} report
+ * @returns {{dst: number, sources: ParsedOperand[]}|null}
+ */
+function parse_operands(meta, tokens, line_number, report) {
+    /** roles the written operands fill, in order */
     const roles = [];
 
     if (meta.dst) {
-        roles.push(VM_OPERAND.DST);
+        roles.push("dst");
     }
 
     for (let slot = 0; slot < 3; slot++) {
@@ -745,86 +876,181 @@ function parse_instruction(line, line_number, report) {
         return null;
     }
 
-    // Word 0 is filled in at the end, once the operands are known: the attribute ops take their
-    // width from their component count.
-    const words = [0, 0, 0, 0, 0];
-
+    let dst = 0;
+    const sources = [none(), none(), none()];
     let slot_cursor = 0;
 
     for (let i = 0; i < roles.length; i++) {
-        const role = roles[i];
-        const value = parse_operand(role, tokens[i], line_number, report);
-
-        if (value === null) {
-            return null;
-        }
+        if (roles[i] === "dst") {
+            dst = parse_destination(tokens[i], line_number, report);
 
-        if (i === 0 && meta.dst) {
-            words[1] = value;
-        } else {
-            // source slots are written in ISA order, skipping the ones marked NONE
-            while (meta.operands[slot_cursor] === VM_OPERAND.NONE) {
-                slot_cursor++;
+            if (dst === null) {
+                return null;
             }
 
-            words[2 + slot_cursor] = value;
+            continue;
+        }
+
+        // source slots are written in ISA order, skipping the ones marked NONE
+        while (meta.operands[slot_cursor] === VM_OPERAND.NONE) {
             slot_cursor++;
         }
+
+        const operand = roles[i] === VM_OPERAND.REG
+            ? parse_register_operand(tokens[i], line_number, report)
+            : parse_plain_operand(roles[i], tokens[i], line_number, report);
+
+        if (operand === null) {
+            return null;
+        }
+
+        sources[slot_cursor] = operand;
+        slot_cursor++;
     }
 
-    // The attribute ops measure themselves in components unless the text says otherwise: a load may
-    // be widened past its attribute (the lanes beyond read zero), a store may not — it writes one
-    // record word per lane, so its width IS the component count.
-    if (opcode === VM_OP.LOAD_ATTR && width_text === "") {
-        width = words[3];
+    return { dst, sources };
+}
+
+/**
+ * The operands of a legacy mnemonic, rewritten as the instruction it now spells.
+ *
+ * `SWIZZLE rd, rs, .xyzw` reads its pattern into `rs`'s swizzle; `SCALE rd, rv, rs` reads `rs`
+ * through `.xxxx`. A literal in either source position is what it is — one value in every lane —
+ * and the pattern or broadcast changes nothing about it.
+ *
+ * @param {string} form `"swizzle"` or `"scale"`
+ * @param {string} mnemonic as written, for messages
+ * @param {string[]} tokens
+ * @param {number} line_number
+ * @param {function(number, string):void} report
+ * @returns {{dst: number, sources: ParsedOperand[]}|null}
+ */
+function parse_legacy_operands(form, mnemonic, tokens, line_number, report) {
+    if (tokens.length !== 3) {
+        report(line_number, `${mnemonic} takes 3 operands, got ${tokens.length}`);
+        return null;
     }
 
-    if (opcode === VM_OP.STORE_ATTR) {
-        if (width_text !== "" && width !== words[3]) {
-            report(line_number, `STORE_ATTR width ${width} must equal its component count ${words[3]}`);
+    const dst = parse_destination(tokens[0], line_number, report);
+
+    if (dst === null) {
+        return null;
+    }
+
+    if (form === "swizzle") {
+        const source = parse_register_operand(tokens[1], line_number, report);
+        const pattern = parse_swizzle_pattern(tokens[2]);
+
+        if (source === null) {
             return null;
         }
 
-        width = words[3];
+        if (pattern === null) {
+            report(line_number, `Expected a swizzle like '.xyzw', got '${tokens[2]}'`);
+            return null;
+        }
+
+        return { dst, sources: [with_pattern(source, pattern), none(), none()] };
     }
 
-    words[0] = vm_encode_word0(opcode, width);
+    const vector = parse_register_operand(tokens[1], line_number, report);
+    const scalar = parse_register_operand(tokens[2], line_number, report);
 
-    // Registers are scalar slots, so what the file has to hold is where the widest operand ENDS.
-    // Sizing it by the largest index written down leaves a `RANDOM.3 r0` writing r1 and r2 outside
-    // the file it derived, which the interpreter reads back as zero and the reference as nothing.
-    let register_reach = 0;
+    if (vector === null || scalar === null) {
+        return null;
+    }
 
-    vm_visit_register_operands(words, 0, (slot, span) => {
-        if (slot + span > register_reach) {
-            register_reach = slot + span;
-        }
-    });
+    return { dst, sources: [vector, with_pattern(scalar, VM_SWIZZLE_BROADCAST), none()] };
+}
 
-    return { words, register_reach };
+/** @returns {ParsedOperand} the operand of an unused slot */
+function none() {
+    return { kind: VM_KIND.NONE, word: 0 };
+}
+
+/**
+ * @param {ParsedOperand} operand
+ * @param {number} pattern
+ * @returns {ParsedOperand} a register operand read through `pattern`; a literal, unchanged
+ */
+function with_pattern(operand, pattern) {
+    return operand.kind === VM_KIND.REG
+        ? { kind: VM_KIND.REG, word: vm_register(vm_operand_base(operand.word), pattern), token: operand.token }
+        : operand;
 }
 
 /**
- * @param {string} role
  * @param {string} token
  * @param {number} line_number
  * @param {function(number, string):void} report
- * @returns {number|null}
+ * @returns {number|null} the destination register
  */
-function parse_operand(role, token, line_number, report) {
-    switch (role) {
-        case VM_OPERAND.DST:
-        case VM_OPERAND.REG: {
-            const index = parse_prefixed(token, "r");
+function parse_destination(token, line_number, report) {
+    const index = parse_prefixed(token, "r");
 
-            if (index === null) {
-                report(line_number, `Expected a register like 'r0', got '${token}'`);
-                return null;
-            }
+    if (index === null) {
+        report(line_number, `A destination is a register like 'r0', got '${token}'`);
+        return null;
+    }
+
+    return index;
+}
+
+/**
+ * An operand in a register slot: a register, optionally read through selectors, or a literal.
+ *
+ * @param {string} token
+ * @param {number} line_number
+ * @param {function(number, string):void} report
+ * @returns {ParsedOperand|null}
+ */
+function parse_register_operand(token, line_number, report) {
+    const register = /^r(\d+)(?:\.([xyzw]{1,4}))?$/i.exec(token);
+
+    if (register !== null) {
+        const selectors = register[2] ?? "";
+        const lanes = [0, 1, 2, 3].map(lane => (lane < selectors.length
+            ? SWIZZLE_LANES.indexOf(selectors.charAt(lane).toLowerCase())
+            : lane));
+
+        return {
+            kind: VM_KIND.REG,
+            word: vm_register(Number.parseInt(register[1], 10), pack_swizzle(lanes[0], lanes[1], lanes[2], lanes[3])),
+            selectors: selectors.length,
+            token,
+        };
+    }
 
-            return index;
+    if (token.startsWith(PARTICLE_ASSEMBLY_IMMEDIATE_PREFIX)) {
+        const value = parse_float(token.slice(PARTICLE_ASSEMBLY_IMMEDIATE_PREFIX.length));
+
+        if (value === null) {
+            report(line_number, `Expected a literal like '${PARTICLE_ASSEMBLY_IMMEDIATE_PREFIX}1.5', got '${token}'`);
+            return null;
         }
 
+        // The word IS the f32: what a Float32Array would hold for this value, read back as bits.
+        return { kind: VM_KIND.IMM, word: vm_f32_bits(value) };
+    }
+
+    report(
+        line_number,
+        `Expected a register like 'r0' or 'r0.xxy', or a literal like `
+        + `'${PARTICLE_ASSEMBLY_IMMEDIATE_PREFIX}1.5', got '${token}'`
+    );
+
+    return null;
+}
+
+/**
+ * @param {string} role a role other than the register one
+ * @param {string} token
+ * @param {number} line_number
+ * @param {function(number, string):void} report
+ * @returns {ParsedOperand|null}
+ */
+function parse_plain_operand(role, token, line_number, report) {
+    switch (role) {
         case VM_OPERAND.CONST: {
             const index = parse_prefixed(token, "c");
 
@@ -833,23 +1059,18 @@ function parse_operand(role, token, line_number, report) {
                 return null;
             }
 
-            return index;
+            return { kind: VM_KIND.NONE, word: index };
         }
 
         case VM_OPERAND.ATTR_OFFSET: {
-            if (!token.startsWith("@")) {
-                report(line_number, `Expected an attribute offset like '@1', got '${token}'`);
-                return null;
-            }
-
-            const offset = parse_unsigned(token.slice(1));
+            const offset = token.startsWith("@") ? parse_unsigned(token.slice(1)) : null;
 
             if (offset === null) {
                 report(line_number, `Expected an attribute offset like '@1', got '${token}'`);
                 return null;
             }
 
-            return offset;
+            return { kind: VM_KIND.NONE, word: offset };
         }
 
         case VM_OPERAND.COMP: {
@@ -860,11 +1081,14 @@ function parse_operand(role, token, line_number, report) {
                 return null;
             }
 
-            return components;
+            return { kind: VM_KIND.NONE, word: components };
         }
 
-        case VM_OPERAND.BUILTIN:
-            return parse_enum_operand(token, VM_BUILTIN, "builtin", line_number, report);
+        case VM_OPERAND.BUILTIN: {
+            const id = parse_enum_operand(token, VM_BUILTIN, "builtin", line_number, report);
+
+            return id === null ? null : { kind: VM_KIND.NONE, word: id };
+        }
 
         case VM_OPERAND.CURVE: {
             const handle = parse_prefixed(token, "k");
@@ -874,18 +1098,7 @@ function parse_operand(role, token, line_number, report) {
                 return null;
             }
 
-            return handle;
-        }
-
-        case VM_OPERAND.SWIZZLE: {
-            const packed = parse_swizzle(token);
-
-            if (packed === null) {
-                report(line_number, `Expected a swizzle like '.xyzw', got '${token}'`);
-                return null;
-            }
-
-            return packed;
+            return { kind: VM_KIND.NONE, word: handle };
         }
 
         default:
@@ -924,10 +1137,12 @@ function parse_enum_operand(token, enumeration, label, line_number, report) {
 }
 
 /**
+ * A legacy `SWIZZLE` pattern: exactly four selectors behind a dot.
+ *
  * @param {string} token
- * @returns {number|null} the packed 8-bit pattern
+ * @returns {number|null} the packed pattern
  */
-function parse_swizzle(token) {
+function parse_swizzle_pattern(token) {
     if (token.length !== 5 || !token.startsWith(".")) {
         return null;
     }