@woosh/meep-engine 3.58.0 → 3.59.0

package/src/shade/renderer/particles/isa/particle_assembly.d.ts

@@ -65,6 +65,7 @@ export function assemble_particle_program(text: string): ParticleProgram;
  * ```
  * ; a comment, or // a comment
  * .registers 6                  ; register file size in slots, optional (derived from use when absent)
+ * .global gust 1                ; a global field the program reads, 1 component: global_field:0 below
  * .const c0 0                   ; one word of the constant pool; indices must be dense from 0
  * .const c1 2
  *
@@ -72,10 +73,11 @@ export function assemble_particle_program(text: string): ParticleProgram;
  *   LOAD_BUILTIN.3 r0, EMITTER_POSITION
  *   RANDOM.2 r1
  *   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
+ *   STORE_PARTICLE_FIELD r1, @1, 3  ; r1 into the 3-component particle field at record word 1
  *
  * .update
- *   LOAD_ATTR.1 r0, @7, 1
+ *   LOAD_PARTICLE_FIELD.1 r0, @7, 1
+ *   LOAD_BUILTIN.1 r1, global_field:0
  *   CMP_GE.1 r0, r0, r1
  *   MOV.3 r2, r0.xxx            ; a register read through a swizzle: lane 0 three times
  *   KILL r0
@@ -83,8 +85,8 @@ export function assemble_particle_program(text: string): ParticleProgram;
  *
  * The `.n` on a mnemonic is the lane count the instruction spans — `ADD.3` adds three lanes. It is
  * written for every opcode that reads the width field, which is all of them bar the handful whose
- * lane count is fixed (`HALT`, `NOP`, `KILL`, `CROSS`) and `STORE_ATTR`, whose width is by
- * definition the component count it already spells as an operand. Left off, it falls back to the
+ * lane count is fixed (`HALT`, `NOP`, `KILL`, `CROSS`) and `STORE_PARTICLE_FIELD`, whose width is
+ * by definition the component count it already spells as an operand. Left off, it falls back to the
  * opcode's natural width, so text typed by hand need not carry one.
  *
  * Operand spelling follows the slot's role in {@link VM_ISA}, so every token is unambiguous where it
@@ -96,9 +98,11 @@ export function assemble_particle_program(text: string): ParticleProgram;
  * | 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` |
+ * | particle field word offset | `@<word>` | `@7` |
+ * | particle field component count | a bare integer `1..4` | `3` |
  * | builtin | a {@link VM_BUILTIN} name | `EMITTER_POSITION` |
+ * | emitter field | `emitter_field:<word>`, a word offset into the emitter's block | `emitter_field:3` |
+ * | global field | `global_field:<n>`, import `n` (a word offset once placed) | `global_field:0` |
  *
  * 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
@@ -109,6 +113,9 @@ export function assemble_particle_program(text: string): ParticleProgram;
  * 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.
+ *
+ * `LOAD_ATTR` and `STORE_ATTR` are older names of `LOAD_PARTICLE_FIELD` and `STORE_PARTICLE_FIELD`,
+ * and read as those. The disassembler writes the current names.
  */
 /** Section directive introducing the INIT stream. @type {string} */
 export const PARTICLE_ASSEMBLY_SECTION_INIT: string;
@@ -118,6 +125,13 @@ export const PARTICLE_ASSEMBLY_SECTION_UPDATE: string;
 export const PARTICLE_ASSEMBLY_DIRECTIVE_REGISTERS: string;
 /** Directive declaring one constant-pool entry. @type {string} */
 export const PARTICLE_ASSEMBLY_DIRECTIVE_CONST: string;
+/**
+ * Global field import directive: `.global gust 1` imports the system's global field `gust`, one
+ * component wide. Imports are numbered in the order they are written, which is the order a
+ * `global_field:N` operand indexes them by.
+ * @type {string}
+ */
+export const PARTICLE_ASSEMBLY_DIRECTIVE_GLOBAL: string;
 /** Opens a literal in a register slot: `#1.5`. @type {string} */
 export const PARTICLE_ASSEMBLY_IMMEDIATE_PREFIX: string;
 /**

package/src/shade/renderer/particles/isa/particle_assembly.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"particle_assembly.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/isa/particle_assembly.js"],"names":[],"mappings":"AAyKA;;;;;;;;GAQG;AAMH;;;;;;;;;;;GAWG;AACH,sDALW,eAAe;IAEE,MAAM,GAAvB,MAAM;IACJ,MAAM,CAmClB;AAwJD;;;;;;;;;;;GAWG;AACH,8CAHW,MAAM,GACJ;IAAC,OAAO,EAAE,eAAe,GAAC,IAAI,CAAC;IAAC,WAAW,EAAE,0BAA0B,EAAE,CAAA;CAAC,CA8ItF;AAED;;;;;;;;GAQG;AACH,gDAJW,MAAM,GACJ,eAAe,CAkB3B;AA9gBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAEH,oEAAoE;AACpE,6CAD0D,MAAM,CACV;AAEtD,sEAAsE;AACtE,+CAD4D,MAAM,CACR;AAE1D,+DAA+D;AAC/D,oDADqD,MAAM,CACO;AAElE,kEAAkE;AAClE,gDADwD,MAAM,CACJ;AAE1D,iEAAiE;AACjE,iDADuD,MAAM,CACP;AAEtD;;;;;GAKG;AACH,gDAFU,MAAM,CAEqC;AAErD;;;;;;;;;GASG;AACH,8CAFU,MAAM,CAEoC;;;;;;;;;;UA+CtC,MAAM;aACN,MAAM;;;;;;UA6hBN,MAAM;;;;UACN,MAAM;;;;gBACN,MAAM;;;;YACN,MAAM;;gCA1sBY,sBAAsB"}
+{"version":3,"file":"particle_assembly.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/isa/particle_assembly.js"],"names":[],"mappings":"AAuMA;;;;;;;;GAQG;AAMH;;;;;;;;;;;GAWG;AACH,sDALW,eAAe;IAEE,MAAM,GAAvB,MAAM;IACJ,MAAM,CAuClB;AAgKD;;;;;;;;;;;GAWG;AACH,8CAHW,MAAM,GACJ;IAAC,OAAO,EAAE,eAAe,GAAC,IAAI,CAAC;IAAC,WAAW,EAAE,0BAA0B,EAAE,CAAA;CAAC,CAwJtF;AAED;;;;;;;;GAQG;AACH,gDAJW,MAAM,GACJ,eAAe,CAkB3B;AA7jBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AAEH,oEAAoE;AACpE,6CAD0D,MAAM,CACV;AAEtD,sEAAsE;AACtE,+CAD4D,MAAM,CACR;AAE1D,+DAA+D;AAC/D,oDADqD,MAAM,CACO;AAElE,kEAAkE;AAClE,gDADwD,MAAM,CACJ;AAE1D;;;;;GAKG;AACH,iDAFU,MAAM,CAE4C;AAE5D,iEAAiE;AACjE,iDADuD,MAAM,CACP;AAEtD;;;;;GAKG;AACH,gDAFU,MAAM,CAEqC;AAErD;;;;;;;;;GASG;AACH,8CAFU,MAAM,CAEoC;;;;;;;;;;UAyDtC,MAAM;aACN,MAAM;;;;;;UAgkBN,MAAM;;;;UACN,MAAM;;;;gBACN,MAAM;;;;YACN,MAAM;;gCA3wBY,sBAAsB"}

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

@@ -9,6 +9,11 @@ import {
     pack_swizzle,
     swizzle_selector,
     VM_BUILTIN,
+    VM_BUILTIN_FIELD_INDEX_MASK,
+    vm_builtin_emitter_field,
+    vm_builtin_global_field,
+    vm_builtin_is_emitter_field,
+    vm_builtin_is_global_field,
     VM_ISA,
     VM_KIND,
     VM_MAX_WIDTH,
@@ -47,6 +52,7 @@ import {
  * ```
  * ; a comment, or // a comment
  * .registers 6                  ; register file size in slots, optional (derived from use when absent)
+ * .global gust 1                ; a global field the program reads, 1 component: global_field:0 below
  * .const c0 0                   ; one word of the constant pool; indices must be dense from 0
  * .const c1 2
  *
@@ -54,10 +60,11 @@ import {
  *   LOAD_BUILTIN.3 r0, EMITTER_POSITION
  *   RANDOM.2 r1
  *   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
+ *   STORE_PARTICLE_FIELD r1, @1, 3  ; r1 into the 3-component particle field at record word 1
  *
  * .update
- *   LOAD_ATTR.1 r0, @7, 1
+ *   LOAD_PARTICLE_FIELD.1 r0, @7, 1
+ *   LOAD_BUILTIN.1 r1, global_field:0
  *   CMP_GE.1 r0, r0, r1
  *   MOV.3 r2, r0.xxx            ; a register read through a swizzle: lane 0 three times
  *   KILL r0
@@ -65,8 +72,8 @@ import {
  *
  * The `.n` on a mnemonic is the lane count the instruction spans — `ADD.3` adds three lanes. It is
  * written for every opcode that reads the width field, which is all of them bar the handful whose
- * lane count is fixed (`HALT`, `NOP`, `KILL`, `CROSS`) and `STORE_ATTR`, whose width is by
- * definition the component count it already spells as an operand. Left off, it falls back to the
+ * lane count is fixed (`HALT`, `NOP`, `KILL`, `CROSS`) and `STORE_PARTICLE_FIELD`, whose width is
+ * by definition the component count it already spells as an operand. Left off, it falls back to the
  * opcode's natural width, so text typed by hand need not carry one.
  *
  * Operand spelling follows the slot's role in {@link VM_ISA}, so every token is unambiguous where it
@@ -78,9 +85,11 @@ import {
  * | 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` |
+ * | particle field word offset | `@<word>` | `@7` |
+ * | particle field component count | a bare integer `1..4` | `3` |
  * | builtin | a {@link VM_BUILTIN} name | `EMITTER_POSITION` |
+ * | emitter field | `emitter_field:<word>`, a word offset into the emitter's block | `emitter_field:3` |
+ * | global field | `global_field:<n>`, import `n` (a word offset once placed) | `global_field:0` |
  *
  * 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
@@ -91,6 +100,9 @@ import {
  * 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.
+ *
+ * `LOAD_ATTR` and `STORE_ATTR` are older names of `LOAD_PARTICLE_FIELD` and `STORE_PARTICLE_FIELD`,
+ * and read as those. The disassembler writes the current names.
  */
 
 /** Section directive introducing the INIT stream. @type {string} */
@@ -105,6 +117,14 @@ export const PARTICLE_ASSEMBLY_DIRECTIVE_REGISTERS = ".registers";
 /** Directive declaring one constant-pool entry. @type {string} */
 export const PARTICLE_ASSEMBLY_DIRECTIVE_CONST = ".const";
 
+/**
+ * Global field import directive: `.global gust 1` imports the system's global field `gust`, one
+ * component wide. Imports are numbered in the order they are written, which is the order a
+ * `global_field:N` operand indexes them by.
+ * @type {string}
+ */
+export const PARTICLE_ASSEMBLY_DIRECTIVE_GLOBAL = ".global";
+
 /** Opens a literal in a register slot: `#1.5`. @type {string} */
 export const PARTICLE_ASSEMBLY_IMMEDIATE_PREFIX = "#";
 
@@ -140,6 +160,16 @@ const LEGACY_MNEMONICS = new Map([
     ["SCALE", { op: VM_OP.MUL, form: "scale" }],
 ]);
 
+/**
+ * Older names of opcodes, mapped to the current ones, so text written under them still assembles.
+ * The operands are the same.
+ * @type {ReadonlyMap<string, string>}
+ */
+const RENAMED_MNEMONICS = new Map([
+    ["LOAD_ATTR", "LOAD_PARTICLE_FIELD"],
+    ["STORE_ATTR", "STORE_PARTICLE_FIELD"],
+]);
+
 /**
  * Mnemonic -> opcode, derived from {@link VM_ISA} so the two cannot drift.
  * @type {Map<string, number>}
@@ -198,6 +228,10 @@ export function disassemble_particle_program(program, { indent = "    " } = {})
 
     lines.push(`${PARTICLE_ASSEMBLY_DIRECTIVE_REGISTERS} ${program.register_count}`);
 
+    for (const entry of program.global_imports) {
+        lines.push(`${PARTICLE_ASSEMBLY_DIRECTIVE_GLOBAL} ${entry.name} ${entry.components}`);
+    }
+
     const constants = program.constants;
 
     // The pool is a flat run of words that instructions index into at whatever width they read, so
@@ -279,10 +313,10 @@ function disassemble_instruction(words, base) {
 /**
  * The `.n` a mnemonic wears to say how many lanes it spans.
  *
- * Only the opcodes that actually read the width field get one. `STORE_ATTR` is the exception among
- * those: its width is defined to be its component count, which is already written as an operand, so
- * a suffix there would be a second copy of one number and a chance to write them contradicting each
- * other.
+ * Only the opcodes that actually read the width field get one. `STORE_PARTICLE_FIELD` is the
+ * exception among those: its width is defined to be its component count, which is already written
+ * as an operand, so a suffix there would be a second copy of one number and a chance to write them
+ * contradicting each other.
  *
  * @param {number} op
  * @param {object} meta the opcode's {@link VM_ISA} entry
@@ -290,7 +324,7 @@ function disassemble_instruction(words, base) {
  * @returns {string}
  */
 function format_width_suffix(op, meta, width) {
-    if (meta.width !== VM_WIDTH.VARIABLE || op === VM_OP.STORE_ATTR) {
+    if (meta.width !== VM_WIDTH.VARIABLE || op === VM_OP.STORE_PARTICLE_FIELD) {
         return "";
     }
 
@@ -330,11 +364,19 @@ function format_operand(role, value) {
     switch (role) {
         case VM_OPERAND.CONST:
             return `c${value}`;
-        case VM_OPERAND.ATTR_OFFSET:
+        case VM_OPERAND.PARTICLE_FIELD_OFFSET:
             return `@${value}`;
         case VM_OPERAND.COMP:
             return String(value);
         case VM_OPERAND.BUILTIN:
+            if (vm_builtin_is_emitter_field(value)) {
+                return `${EMITTER_FIELD_SPELLING}${value & VM_BUILTIN_FIELD_INDEX_MASK}`;
+            }
+
+            if (vm_builtin_is_global_field(value)) {
+                return `${GLOBAL_FIELD_SPELLING}${value & VM_BUILTIN_FIELD_INDEX_MASK}`;
+            }
+
             return BUILTIN_NAME_BY_ID.get(value) ?? String(value);
         default:
             return String(value);
@@ -413,6 +455,9 @@ export function parse_particle_assembly(text) {
     /** @type {number} explicit `.registers`, or -1 when it should be derived from use */
     let declared_register_count = -1;
 
+    /** @type {Array<{name: string, components: number}>} `.global` imports, in the order written */
+    const global_imports = [];
+
     /** end of the furthest-reaching register operand any instruction writes down */
     let register_high_water = 0;
 
@@ -435,6 +480,12 @@ export function parse_particle_assembly(text) {
 
             if (directive.kind === "section") {
                 section = sections[directive.section];
+            } else if (directive.kind === "global") {
+                if (global_imports.some(entry => entry.name === directive.name)) {
+                    report(line_number, `Global field '${directive.name}' is imported more than once`);
+                } else {
+                    global_imports.push({ name: directive.name, components: directive.components });
+                }
             } else if (directive.kind === "registers") {
                 if (declared_register_count !== -1) {
                     report(line_number, `Duplicate ${PARTICLE_ASSEMBLY_DIRECTIVE_REGISTERS} directive`);
@@ -527,6 +578,7 @@ export function parse_particle_assembly(text) {
             update: new Uint32Array(sections.update.words),
             constants: new Float32Array(constants),
             register_count,
+            global_imports,
         }),
         diagnostics,
     };
@@ -608,9 +660,10 @@ function check_stream_references(stream, register_count, constant_word_count, re
             }
         }
 
-        // 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.
-        const offset_slot = meta.operands.indexOf(VM_OPERAND.ATTR_OFFSET);
+        // A particle field 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.
+        const offset_slot = meta.operands.indexOf(VM_OPERAND.PARTICLE_FIELD_OFFSET);
 
         if (offset_slot !== -1) {
             const offset = words[base + 1 + offset_slot];
@@ -619,7 +672,7 @@ function check_stream_references(stream, register_count, constant_word_count, re
             if (offset + components > PARTICLE_RECORD_WORD_COUNT) {
                 report(
                     line,
-                    `attribute access [${offset}, ${offset + components}) runs past the ${PARTICLE_RECORD_WORD_COUNT}-word particle record`
+                    `particle field access [${offset}, ${offset + components}) runs past the ${PARTICLE_RECORD_WORD_COUNT}-word particle record`
                 );
             }
         }
@@ -676,6 +729,18 @@ function parse_directive(line, line_number, report) {
         return { kind: "registers", count };
     }
 
+    if (head === PARTICLE_ASSEMBLY_DIRECTIVE_GLOBAL) {
+        const name = tokens[1];
+        const components = parse_unsigned(tokens[2]);
+
+        if (name === undefined || components === null || components < 1 || components > 4 || tokens.length > 3) {
+            report(line_number, `${PARTICLE_ASSEMBLY_DIRECTIVE_GLOBAL} needs a name and a component count 1..4, like '.global gust 1'`);
+            return null;
+        }
+
+        return { kind: "global", name, components };
+    }
+
     if (head === PARTICLE_ASSEMBLY_DIRECTIVE_CONST) {
         const index = parse_prefixed(tokens[1], "c");
 
@@ -735,7 +800,8 @@ function parse_instruction(line, line_number, report) {
 
     // `ADD.3` — mnemonic, then the lane count it spans.
     const separator = head.indexOf(PARTICLE_ASSEMBLY_WIDTH_SEPARATOR);
-    const mnemonic = separator === -1 ? head : head.slice(0, separator);
+    const written = separator === -1 ? head : head.slice(0, separator);
+    const mnemonic = RENAMED_MNEMONICS.get(written) ?? written;
     const width_text = separator === -1 ? "" : head.slice(separator + 1);
 
     const legacy = LEGACY_MNEMONICS.get(mnemonic) ?? null;
@@ -784,16 +850,16 @@ function parse_instruction(line, line_number, report) {
 
     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 === "") {
+    // The particle field ops measure themselves in components unless the text says otherwise: a
+    // load may be widened past its particle field (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_PARTICLE_FIELD && width_text === "") {
         width = sources[1].word;
     }
 
-    if (opcode === VM_OP.STORE_ATTR) {
+    if (opcode === VM_OP.STORE_PARTICLE_FIELD) {
         if (width_text !== "" && width !== sources[2].word) {
-            report(line_number, `STORE_ATTR width ${width} must equal its component count ${sources[2].word}`);
+            report(line_number, `STORE_PARTICLE_FIELD width ${width} must equal its component count ${sources[2].word}`);
             return null;
         }
 
@@ -1099,11 +1165,11 @@ function parse_plain_operand(role, token, line_number, report) {
             return { kind: VM_KIND.NONE, word: index };
         }
 
-        case VM_OPERAND.ATTR_OFFSET: {
+        case VM_OPERAND.PARTICLE_FIELD_OFFSET: {
             const offset = token.startsWith("@") ? parse_unsigned(token.slice(1)) : null;
 
             if (offset === null) {
-                report(line_number, `Expected an attribute offset like '@1', got '${token}'`);
+                report(line_number, `Expected a particle field offset like '@1', got '${token}'`);
                 return null;
             }
 
@@ -1122,6 +1188,12 @@ function parse_plain_operand(role, token, line_number, report) {
         }
 
         case VM_OPERAND.BUILTIN: {
+            const field = parse_field_operand(token);
+
+            if (field !== null) {
+                return { kind: VM_KIND.NONE, word: field };
+            }
+
             const id = parse_enum_operand(token, VM_BUILTIN, "builtin", line_number, report);
 
             return id === null ? null : { kind: VM_KIND.NONE, word: id };
@@ -1162,6 +1234,45 @@ function parse_enum_operand(token, enumeration, label, line_number, report) {
     return null;
 }
 
+/**
+ * How a builtin operand that reads an emitter field is spelled: `emitter_field:3` is the word at
+ * offset 3 of the emitter's block.
+ * @type {string}
+ */
+const EMITTER_FIELD_SPELLING = "emitter_field:";
+
+/**
+ * How a builtin operand that reads a global field is spelled: `global_field:2` is import 2 in a
+ * compiled program, and word 2 of the global fields once it is placed.
+ * @type {string}
+ */
+const GLOBAL_FIELD_SPELLING = "global_field:";
+
+/**
+ * A field operand of `LOAD_BUILTIN`, or `null` for a token that is not one — including an index
+ * past {@link VM_BUILTIN_FIELD_INDEX_MASK}, which then fails as a builtin name.
+ *
+ * @param {string} token
+ * @returns {number|null} the builtin id
+ */
+function parse_field_operand(token) {
+    const lower = token.toLowerCase();
+
+    if (lower.startsWith(EMITTER_FIELD_SPELLING)) {
+        const index = parse_unsigned(token.slice(EMITTER_FIELD_SPELLING.length));
+
+        return index === null || index > VM_BUILTIN_FIELD_INDEX_MASK ? null : vm_builtin_emitter_field(index);
+    }
+
+    if (lower.startsWith(GLOBAL_FIELD_SPELLING)) {
+        const index = parse_unsigned(token.slice(GLOBAL_FIELD_SPELLING.length));
+
+        return index === null || index > VM_BUILTIN_FIELD_INDEX_MASK ? null : vm_builtin_global_field(index);
+    }
+
+    return null;
+}
+
 /**
  * A legacy `SWIZZLE` pattern: exactly four selectors behind a dot.
  *

package/src/shade/renderer/particles/isa/particle_link_global_fields.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Link a program's global field reads, in place: every `LOAD_BUILTIN` of a global id, which in a
+ * compiled program names an import, is rewritten to name that import's word offset in the system's
+ * global layout.
+ *
+ * Programs are durable content compiled with no scene present, so they cannot carry a scene's
+ * offsets; this is what turns the one into the other. The program heap runs it on the copy of the
+ * code it places (see {@link ../runtime/ProgramHeap.js}), so the program it is keyed by stays
+ * unlinked and deduplication holds; the editor's preview runs it on a copy of its own.
+ *
+ * An index with no import behind it is left as it is: a program written as assembly may address the
+ * global words directly.
+ *
+ * @param {Uint32Array} words instruction words, linked in place
+ * @param {number} begin first word of the code to link
+ * @param {number} end one past the last
+ * @param {ArrayLike<number>} offsets the word offset of each import, by import index
+ */
+export function particle_link_global_fields(words: Uint32Array, begin: number, end: number, offsets: ArrayLike<number>): void;
+//# sourceMappingURL=particle_link_global_fields.d.ts.map

package/src/shade/renderer/particles/isa/particle_link_global_fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"particle_link_global_fields.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/isa/particle_link_global_fields.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;GAiBG;AACH,mDALW,WAAW,SACX,MAAM,OACN,MAAM,WACN,UAAU,MAAM,CAAC,QAoB3B"}

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

@@ -0,0 +1,46 @@
+import {
+    PARTICLE_VM_INSTRUCTION_WORDS,
+    VM_BUILTIN_FIELD_INDEX_MASK,
+    VM_OP,
+    VM_OP_MASK,
+    vm_builtin_global_field,
+    vm_builtin_is_global_field,
+} from "./ParticleVMISA.js";
+
+/**
+ * Link a program's global field reads, in place: every `LOAD_BUILTIN` of a global id, which in a
+ * compiled program names an import, is rewritten to name that import's word offset in the system's
+ * global layout.
+ *
+ * Programs are durable content compiled with no scene present, so they cannot carry a scene's
+ * offsets; this is what turns the one into the other. The program heap runs it on the copy of the
+ * code it places (see {@link ../runtime/ProgramHeap.js}), so the program it is keyed by stays
+ * unlinked and deduplication holds; the editor's preview runs it on a copy of its own.
+ *
+ * An index with no import behind it is left as it is: a program written as assembly may address the
+ * global words directly.
+ *
+ * @param {Uint32Array} words instruction words, linked in place
+ * @param {number} begin first word of the code to link
+ * @param {number} end one past the last
+ * @param {ArrayLike<number>} offsets the word offset of each import, by import index
+ */
+export function particle_link_global_fields(words, begin, end, offsets) {
+    for (let k = begin; k < end; k += PARTICLE_VM_INSTRUCTION_WORDS) {
+        if ((words[k] & VM_OP_MASK) !== VM_OP.LOAD_BUILTIN) {
+            continue;
+        }
+
+        const id = words[k + 1];
+
+        if (!vm_builtin_is_global_field(id)) {
+            continue;
+        }
+
+        const index = id & VM_BUILTIN_FIELD_INDEX_MASK;
+
+        if (index < offsets.length) {
+            words[k + 1] = vm_builtin_global_field(offsets[index]);
+        }
+    }
+}

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

@@ -98,11 +98,11 @@ function validate_stream(words, label, constant_word_count, register_count) {
             );
         }
 
-        // Attribute accesses must stay inside one record. An out-of-range offset is NOT caught by
-        // GPU robustness — record_base + offset lands inside the pool buffer, silently reading or
-        // corrupting the NEXT PARTICLE'S record.
-        if (op === VM_OP.LOAD_ATTR || op === VM_OP.STORE_ATTR) {
-            const first = op === VM_OP.LOAD_ATTR ? 1 : 2;
+        // Particle field accesses must stay inside one record. An out-of-range offset is NOT caught
+        // by GPU robustness — record_base + offset lands inside the pool buffer, silently reading
+        // or corrupting the NEXT PARTICLE'S record.
+        if (op === VM_OP.LOAD_PARTICLE_FIELD || op === VM_OP.STORE_PARTICLE_FIELD) {
+            const first = op === VM_OP.LOAD_PARTICLE_FIELD ? 1 : 2;
             const offset = words[base + first];
             const components = words[base + first + 1];
 
@@ -111,16 +111,16 @@ function validate_stream(words, label, constant_word_count, register_count) {
             assert.lessThanOrEqual(
                 offset + components,
                 PARTICLE_RECORD_WORD_COUNT,
-                `${label}[${i}] (${meta.name}): attribute access [${offset}, ${offset + components}) exceeds the ${PARTICLE_RECORD_WORD_COUNT}-word record`
+                `${label}[${i}] (${meta.name}): particle field access [${offset}, ${offset + components}) exceeds the ${PARTICLE_RECORD_WORD_COUNT}-word record`
             );
 
             // A store writes one record word per lane, so it cannot be asked for more words than
             // the value holds — the extra ones would come out of the next value.
-            if (op === VM_OP.STORE_ATTR) {
+            if (op === VM_OP.STORE_PARTICLE_FIELD) {
                 assert.equal(
                     width,
                     components,
-                    `${label}[${i}] (STORE_ATTR): width ${width} must equal the component count ${components}`
+                    `${label}[${i}] (STORE_PARTICLE_FIELD): width ${width} must equal the component count ${components}`
                 );
             }
         }