@woosh/meep-engine 3.58.0 → 3.60.0

package/src/shade/renderer/particles/shaders/chunk_particle_billboard_vertex.js

@@ -1,6 +1,6 @@
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 import { PARTICLE_RECORD_HEADER_EMITTER, PARTICLE_RECORD_WORD_COUNT } from "../ParticleConstants.js";
-import { EMITTER_ATTRIBUTE_ABSENT } from "../data/PARTICLE_EMITTER_STRUCT.js";
+import { PARTICLE_FIELD_ABSENT } from "../data/PARTICLE_EMITTER_STRUCT.js";
 import { chunk_particle_emitter } from "../data/chunk_particle_emitter.js";
 import { chunk_particle_header } from "../data/particle_header.js";
 import { chunk_particle_render_math } from "./chunk_particle_render_math.js";
@@ -26,7 +26,7 @@ export const chunk_particle_billboard_vertex = CodeChunk.from(
     /* language=wgsl */ `
 const PARTICLE_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
 const PARTICLE_HEADER_EMITTER : u32 = ${PARTICLE_RECORD_HEADER_EMITTER}u;
-const PARTICLE_ATTRIBUTE_ABSENT : u32 = ${EMITTER_ATTRIBUTE_ABSENT}u;
+const PARTICLE_FIELD_ABSENT : u32 = ${PARTICLE_FIELD_ABSENT}u;
 
 struct ParticleVertexOut {
     @builtin(position) clip : vec4<f32>,
@@ -61,18 +61,18 @@ fn particle_billboard_vertex(vi : u32, ii : u32) -> ParticleVertexOut {
     let em = particle_emitter_read(&emitter_database, emitter_index);
 
     var world_center = vec3<f32>(0.0);
-    if (em.render_position != PARTICLE_ATTRIBUTE_ABSENT) { world_center = particle_read_vec(base, em.render_position, 3u).xyz; }
+    if (em.render_position != PARTICLE_FIELD_ABSENT) { world_center = particle_read_vec(base, em.render_position, 3u).xyz; }
     var size = 1.0;
-    if (em.render_size != PARTICLE_ATTRIBUTE_ABSENT) { size = bitcast<f32>(pool[base + em.render_size]); }
+    if (em.render_size != PARTICLE_FIELD_ABSENT) { size = bitcast<f32>(pool[base + em.render_size]); }
     var color = vec4<f32>(1.0);
-    if (em.render_color != PARTICLE_ATTRIBUTE_ABSENT) { color = particle_read_vec(base, em.render_color, 4u); }
+    if (em.render_color != PARTICLE_FIELD_ABSENT) { color = particle_read_vec(base, em.render_color, 4u); }
     // the identity when the effect binds none
     var orientation = vec4<f32>(0.0, 0.0, 0.0, 1.0);
-    if (em.render_orientation != PARTICLE_ATTRIBUTE_ABSENT) { orientation = particle_read_vec(base, em.render_orientation, 4u); }
+    if (em.render_orientation != PARTICLE_FIELD_ABSENT) { orientation = particle_read_vec(base, em.render_orientation, 4u); }
     var frame = 0.0;
-    if (em.render_frame != PARTICLE_ATTRIBUTE_ABSENT) { frame = bitcast<f32>(pool[base + em.render_frame]); }
+    if (em.render_frame != PARTICLE_FIELD_ABSENT) { frame = bitcast<f32>(pool[base + em.render_frame]); }
     var velocity = vec3<f32>(0.0);
-    if (em.render_velocity != PARTICLE_ATTRIBUTE_ABSENT) { velocity = particle_read_vec(base, em.render_velocity, 3u).xyz; }
+    if (em.render_velocity != PARTICLE_FIELD_ABSENT) { velocity = particle_read_vec(base, em.render_velocity, 3u).xyz; }
 
     let cam_right = camera.transform[0].xyz;
     let cam_up = camera.transform[1].xyz;

package/src/shade/renderer/particles/shaders/chunk_particle_render_math.js

@@ -51,7 +51,7 @@ struct ParticleBasis {
 // A unit quaternion out of whatever a program wrote. A program integrating a spin drifts off unit
 // length, and an unnormalised quaternion turns a vector by its rotation AND scales it by its squared
 // length — the drift would show as size. The zero quaternion stays zero, which quat_rotate_v3 reads
-// as no rotation at all, so an attribute nobody wrote yet is the identity rather than a NaN.
+// as no rotation at all, so a particle field nobody wrote yet is the identity rather than a NaN.
 fn particle_orientation_unit(q : vec4<f32>) -> vec4<f32> {
     return q * inverseSqrt(max(dot(q, q), 1e-30));
 }

package/src/shade/renderer/particles/shaders/chunk_particle_setup_context.d.ts

@@ -10,6 +10,9 @@
  * result. The caller fetches the node with `scene_read_node(&scene_database, em.node)`, and the age
  * with {@link ./chunk_particle_emitter_age.js}.
  *
+ * It also sets `vm_ctx.emitter_field_offset` from the record, so the program's emitter field reads
+ * find this emitter's block.
+ *
  * The RNG seed is `hash_lowbias32_vec3u` over (emitter seed, slot, frame) — the engine's house
  * hash, not a private one. It only has to be well mixed, since `random()` does the real work from
  * here, and `rnd_state` feeds a PCG whose LCG step has a nonzero increment, so no seed value

package/src/shade/renderer/particles/shaders/chunk_particle_setup_context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_particle_setup_context.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_setup_context.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,2CAFU,SAAS,CA8BhB;0BA1DuB,oCAAoC"}
+{"version":3,"file":"chunk_particle_setup_context.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_setup_context.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,2CAFU,SAAS,CA+BhB;0BA9DuB,oCAAoC"}

package/src/shade/renderer/particles/shaders/chunk_particle_setup_context.js

@@ -17,6 +17,9 @@ import { chunk_particle_vm } from "../vm/chunk_particle_vm.js";
  * result. The caller fetches the node with `scene_read_node(&scene_database, em.node)`, and the age
  * with {@link ./chunk_particle_emitter_age.js}.
  *
+ * It also sets `vm_ctx.emitter_field_offset` from the record, so the program's emitter field reads
+ * find this emitter's block.
+ *
  * The RNG seed is `hash_lowbias32_vec3u` over (emitter seed, slot, frame) — the engine's house
  * hash, not a private one. It only has to be well mixed, since `random()` does the real work from
  * here, and `rnd_state` feeds a PCG whose LCG step has a nonzero increment, so no seed value
@@ -49,6 +52,7 @@ fn particle_setup_context(
     vm_ctx.emitter_position = (transform * vec4<f32>(0.0, 0.0, 0.0, 1.0)).xyz;
     vm_ctx.emitter_direction = normalize((transform * vec4<f32>(0.0, 0.0, -1.0, 0.0)).xyz);
     vm_ctx.emitter_up = normalize((transform * vec4<f32>(0.0, 1.0, 0.0, 0.0)).xyz);
+    vm_ctx.emitter_field_offset = em.field_offset;
     rnd_state = hash_lowbias32_vec3u(vec3<u32>(em.seed, slot, frame));
 }
 `, [

package/src/shade/renderer/particles/shaders/shader_particle_field_bind.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Threads per workgroup of {@link shader_particle_field_bind}: one per binding row, a page group
+ * per workgroup, as the emitter tick walks its table.
+ * @type {number}
+ */
+export const PARTICLE_FIELD_BIND_WORKGROUP_SIZE: number;
+/**
+ * The transform bindings: one thread per row of the `field_bindings` table, reading the bound row's
+ * composed `global` out of the scene database and writing the channel the binding asks for into the
+ * field section of the program buffer — a global field, or a word of an emitter's block.
+ *
+ * It runs once a frame, after the hierarchy pass has composed the rows and before the spawn
+ * commands and the emitter tick, so every VM pass of the frame reads this frame's transforms. That
+ * is what lets a field follow a row only the GPU composes — an animated joint — with nothing copied
+ * through the CPU, as the emitter's own `EMITTER_POSITION` does. The host records it only while the
+ * table has rows.
+ *
+ * The program buffer is bound read-write here and only here. A bound word is written from scratch
+ * every frame, so whatever the CPU last uploaded to it is overwritten before anything reads it.
+ *
+ * Each channel is computed the way the emitter's builtin of the same name is in
+ * `chunk_particle_setup_context`, so a field bound to an entity reads as that entity's emitter
+ * builtins would. The orientation is the rotation left once each axis is normalised and a mirror
+ * is taken out of x.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_field_bind: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_particle_field_bind.d.ts.map

package/src/shade/renderer/particles/shaders/shader_particle_field_bind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_particle_field_bind.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_field_bind.js"],"names":[],"mappings":"AAUA;;;;GAIG;AACH,iDAFU,MAAM,CAEqC;AAgFrD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,yCAFU,aAAa,CAMpB;8BAvH2B,+BAA+B"}

package/src/shade/renderer/particles/shaders/shader_particle_field_bind.js

@@ -0,0 +1,121 @@
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { chunk_quat_from_m3 } from "../../shader/chunk/geometry/quaternion/chunk_quat_from_m3.js";
+import { chunk_scene_database_access } from "../../scene/chunk_scene_database_access.js";
+import { PARTICLE_PROGRAM_FIELD_BASE_WORD } from "../ParticleConstants.js";
+import { PARTICLE_FIELD_BINDING_DESCRIPTOR } from "../data/PARTICLE_DATABASE_SPEC.js";
+import { PARTICLE_FIELD_BINDING_CHANNEL } from "../data/PARTICLE_FIELD_BINDING.js";
+
+/**
+ * Threads per workgroup of {@link shader_particle_field_bind}: one per binding row, a page group
+ * per workgroup, as the emitter tick walks its table.
+ * @type {number}
+ */
+export const PARTICLE_FIELD_BIND_WORKGROUP_SIZE = 64;
+
+const GROUP_SIZE = PARTICLE_FIELD_BIND_WORKGROUP_SIZE;
+
+const PG = PARTICLE_FIELD_BINDING_DESCRIPTOR.page_iterator_symbol_prefix(GROUP_SIZE, false);
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addStorageBuffer("scene_database", WebGPUArray.u32, false)
+    .addStorageBuffer("emitter_database", WebGPUArray.u32, false)
+    .addStorageBuffer("program", WebGPUArray.u32, true);
+
+const body = CodeChunk.from(/* language=wgsl */ `
+const FIELD_BIND_POSITION : u32 = ${PARTICLE_FIELD_BINDING_CHANNEL.POSITION}u;
+const FIELD_BIND_DIRECTION : u32 = ${PARTICLE_FIELD_BINDING_CHANNEL.DIRECTION}u;
+const FIELD_BIND_UP : u32 = ${PARTICLE_FIELD_BINDING_CHANNEL.UP}u;
+const FIELD_BIND_PROGRAM_FIELD_BASE_WORD : u32 = ${PARTICLE_PROGRAM_FIELD_BASE_WORD}u;
+
+@compute @workgroup_size(${GROUP_SIZE}, 1, 1)
+fn main(
+    @builtin(workgroup_id) wg_id : vec3<u32>,
+    @builtin(local_invocation_index) local_id : u32,
+) {
+    // page_address is uniform across the workgroup, so this branch is uniform.
+    if (!${PG}_setup(&emitter_database, wg_id.x, local_id)) {
+        return;
+    }
+
+    let slot_in_page = ${PG}_slot_in_page(local_id);
+
+    if (slot_in_page >= ${PG}_ELEMENTS_PER_PAGE || !${PG}_is_occupied(slot_in_page)) {
+        return;
+    }
+
+    let bound = ${PG}_read(&emitter_database, slot_in_page);
+    let transform = scene_read_node(&scene_database, bound.source).global;
+
+    var value = vec4<f32>(0.0);
+    var words = 3u;
+
+    if (bound.channel == FIELD_BIND_POSITION) {
+        value = vec4<f32>((transform * vec4<f32>(0.0, 0.0, 0.0, 1.0)).xyz, 0.0);
+    } else if (bound.channel == FIELD_BIND_DIRECTION) {
+        value = vec4<f32>(normalize((transform * vec4<f32>(0.0, 0.0, -1.0, 0.0)).xyz), 0.0);
+    } else if (bound.channel == FIELD_BIND_UP) {
+        value = vec4<f32>(normalize((transform * vec4<f32>(0.0, 1.0, 0.0, 0.0)).xyz), 0.0);
+    } else {
+        // the axes as products rather than column reads, as the builtins take them
+        let y = normalize((transform * vec4<f32>(0.0, 1.0, 0.0, 0.0)).xyz);
+        let z = normalize((transform * vec4<f32>(0.0, 0.0, 1.0, 0.0)).xyz);
+        var x = normalize((transform * vec4<f32>(1.0, 0.0, 0.0, 0.0)).xyz);
+
+        // A mirrored transform is a reflection, which no quaternion is: take the mirror out of x,
+        // and what is left is the rotation.
+        if (dot(cross(x, y), z) < 0.0) {
+            x = -x;
+        }
+
+        let rotation = mat3x3<f32>(x, y, z);
+        value = quat_from_m3(rotation);
+        words = 4u;
+    }
+
+    let k = program[FIELD_BIND_PROGRAM_FIELD_BASE_WORD] + bound.word;
+
+    program[k] = bitcast<u32>(value.x);
+    program[k + 1u] = bitcast<u32>(value.y);
+    program[k + 2u] = bitcast<u32>(value.z);
+
+    if (words > 3u) {
+        program[k + 3u] = bitcast<u32>(value.w);
+    }
+}
+`, [
+    PARTICLE_FIELD_BINDING_DESCRIPTOR.chunk_iterate(GROUP_SIZE, false),
+    chunk_scene_database_access,
+    chunk_quat_from_m3,
+]);
+
+/**
+ * The transform bindings: one thread per row of the `field_bindings` table, reading the bound row's
+ * composed `global` out of the scene database and writing the channel the binding asks for into the
+ * field section of the program buffer — a global field, or a word of an emitter's block.
+ *
+ * It runs once a frame, after the hierarchy pass has composed the rows and before the spawn
+ * commands and the emitter tick, so every VM pass of the frame reads this frame's transforms. That
+ * is what lets a field follow a row only the GPU composes — an animated joint — with nothing copied
+ * through the CPU, as the emitter's own `EMITTER_POSITION` does. The host records it only while the
+ * table has rows.
+ *
+ * The program buffer is bound read-write here and only here. A bound word is written from scratch
+ * every frame, so whatever the CPU last uploaded to it is overwritten before anything reads it.
+ *
+ * Each channel is computed the way the emitter's builtin of the same name is in
+ * `chunk_particle_setup_context`, so a field bound to an entity reads as that entity's emitter
+ * builtins would. The orientation is the rotation left once each axis is normalised and a mirror
+ * is taken out of x.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_field_bind = ComputeShader.from({
+    label: "Particle Field Bind",
+    resources,
+    body,
+});

package/src/shade/renderer/particles/vm/PARTICLE_VM_CONTEXT_STRUCT.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PARTICLE_VM_CONTEXT_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/vm/PARTICLE_VM_CONTEXT_STRUCT.js"],"names":[],"mappings":"AAGA;;GAEG;AACH,sDASU;6BAdmB,mCAAmC"}
+{"version":3,"file":"PARTICLE_VM_CONTEXT_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/vm/PARTICLE_VM_CONTEXT_STRUCT.js"],"names":[],"mappings":"AAGA;;GAEG;AACH,sDAWU;6BAhBmB,mCAAmC"}

package/src/shade/renderer/particles/vm/PARTICLE_VM_CONTEXT_STRUCT.js

@@ -1,4 +1,4 @@
-import { f32, vec3f } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { f32, u32, vec3f } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
 
 /**
@@ -13,4 +13,6 @@ export const PARTICLE_VM_CONTEXT_STRUCT = WebGPUStruct.from({
     emitter_position: vec3f,
     emitter_direction: vec3f,
     emitter_up: vec3f,
+    /** where the emitter's block of emitter fields starts, in words from the field section's base */
+    emitter_field_offset: u32,
 }).pack();

package/src/shade/renderer/particles/vm/ParticleVMReference.d.ts

@@ -20,7 +20,7 @@ export function u32_to_unit_f32(u: number): number;
 /**
  * Execute one section of a particle program against a single particle record.
  *
- * The record is mutated in place (attribute stores). Registers are local. Returns whether the
+ * The record is mutated in place (particle field stores). Registers are local. Returns whether the
  * particle asked to be destroyed and the advanced RNG state so the caller can persist it.
  *
  * This is the CPU reference semantics — the WGSL interpreter is written to match it exactly, and the
@@ -43,22 +43,30 @@ export function u32_to_unit_f32(u: number): number;
  * which models the fused product, and `FRACT`, whose subtraction cannot round twice.
  *
  * @param {object} params
- * @param {Uint32Array} params.words instruction words for the section (SPAWN or UPDATE)
+ * @param {Uint32Array} params.words instruction words for the section (INIT or UPDATE)
  * @param {Float32Array} params.constants constant pool, one float per word
  * @param {number} params.register_count size of the register file in `f32` slots
- * @param {Uint32Array} params.record particle record words (mutated in place); attributes are f32 bits
+ * @param {Uint32Array} params.record particle record words (mutated in place); particle fields are
+ *   f32 bits
  * @param {number[][]} [params.builtins] builtin values indexed by {@link VM_BUILTIN} id, each a 4-array
+ * @param {Uint32Array} [params.emitter_fields] the emitter's block of emitter fields, as f32 bit
+ *   patterns; a read past its end is zero
+ * @param {Uint32Array} [params.global_fields] the global fields as f32 bit patterns, laid out by the
+ *   system's global layout — the program must be linked against it, as placing it in the heap
+ *   does; a read past its end is zero
  * @param {number} [params.rng_state] initial RNG state (u32)
  * @param {ParticleVMWindSampler|null} [params.sample_wind] how `SAMPLE_WIND` is answered; still air
  *   when left out
  * @returns {{ killed: boolean, rng_state: number }}
  */
-export function execute_particle_vm({ words, constants, register_count, record, builtins, rng_state, sample_wind, }: {
+export function execute_particle_vm({ words, constants, register_count, record, builtins, emitter_fields, global_fields, rng_state, sample_wind, }: {
     words: Uint32Array;
     constants: Float32Array;
     register_count: number;
     record: Uint32Array;
     builtins?: number[][];
+    emitter_fields?: Uint32Array;
+    global_fields?: Uint32Array;
     rng_state?: number;
     sample_wind?: ParticleVMWindSampler | null;
 }): {

package/src/shade/renderer/particles/vm/ParticleVMReference.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleVMReference.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/vm/ParticleVMReference.js"],"names":[],"mappings":"AA4BA;;;;;;;GAOG;AACH,gCAHW,MAAM,GACJ;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAW5C;AAED;;;;;GAKG;AACH,mCAHW,MAAM,GACJ,MAAM,CAIlB;AAiFD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH;IAV+B,KAAK,EAAzB,WAAW;IACU,SAAS,EAA9B,YAAY;IACG,cAAc,EAA7B,MAAM;IACc,MAAM,EAA1B,WAAW;IACS,QAAQ,GAA5B,MAAM,EAAE,EAAE;IACM,SAAS,GAAzB,MAAM;IAC8B,WAAW,GAA/C,qBAAqB,GAAC,IAAI;IAExB;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAmWlD;;;;;;;;;;;;0CAlZU,YAAY,KACZ,MAAM,KACN,MAAM,KACN,MAAM,KACJ,IAAI"}
+{"version":3,"file":"ParticleVMReference.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/vm/ParticleVMReference.js"],"names":[],"mappings":"AA+BA;;;;;;;GAOG;AACH,gCAHW,MAAM,GACJ;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAW5C;AAED;;;;;GAKG;AACH,mCAHW,MAAM,GACJ,MAAM,CAIlB;AA2FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH;IAhB+B,KAAK,EAAzB,WAAW;IACU,SAAS,EAA9B,YAAY;IACG,cAAc,EAA7B,MAAM;IACc,MAAM,EAA1B,WAAW;IAES,QAAQ,GAA5B,MAAM,EAAE,EAAE;IACW,cAAc,GAAnC,WAAW;IAEU,aAAa,GAAlC,WAAW;IAGK,SAAS,GAAzB,MAAM;IAC8B,WAAW,GAA/C,qBAAqB,GAAC,IAAI;IAExB;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAqXlD;;;;;;;;;;;;0CA1aU,YAAY,KACZ,MAAM,KACN,MAAM,KACN,MAAM,KACJ,IAAI"}

package/src/shade/renderer/particles/vm/ParticleVMReference.js

@@ -4,6 +4,9 @@ import {
 } from "../ParticleConstants.js";
 import {
     VM_BUILTIN_COMPONENTS,
+    VM_BUILTIN_EMITTER_FIELD_BASE,
+    VM_BUILTIN_FIELD_INDEX_MASK,
+    VM_BUILTIN_GLOBAL_FIELD_BASE,
     VM_BUILTIN_PADDING,
     VM_DEST,
     VM_DST_MASK,
@@ -88,12 +91,22 @@ for (const [op, meta] of VM_ISA) {
 
 const {
     ABS, ACOS, ADD, ASIN, ATAN2, CLAMP, CMP_EQ, CMP_GE, CMP_GT, CMP_LE, CMP_LT, COS, CROSS,
-    DISTANCE, DIV, DOT, EXP, FLOOR, FRACT, HALT, KILL, LENGTH, LOAD_ATTR, LOAD_BUILTIN, LOAD_CONST,
+    DISTANCE, DIV, DOT, EXP, FLOOR, FRACT, HALT, KILL, LENGTH, LOAD_PARTICLE_FIELD, LOAD_BUILTIN, LOAD_CONST,
     LOG, MAD, MAX, MIN, MIX, MOV, MUL, NEG, NOP, NORMALIZE, POW, RANDOM, RSQRT, SAMPLE_WIND, SELECT,
-    SIN, SMOOTHSTEP, SQRT, STEP, STORE_ATTR, SUB, TAN,
+    SIN, SMOOTHSTEP, SQRT, STEP, STORE_PARTICLE_FIELD, SUB, TAN,
 } = VM_OP;
 const KIND_REG = VM_KIND.REG;
 const KIND_IMM = VM_KIND.IMM;
+const EMITTER_FIELD_BASE = VM_BUILTIN_EMITTER_FIELD_BASE;
+const GLOBAL_FIELD_BASE = VM_BUILTIN_GLOBAL_FIELD_BASE;
+const FIELD_INDEX_MASK = VM_BUILTIN_FIELD_INDEX_MASK;
+
+/** @type {Uint32Array} */
+const NO_FIELDS = new Uint32Array(0);
+
+// One word reinterpreted: a field is stored as f32 bit patterns, as the pool and the record are.
+const FIELD_WORD = new Uint32Array(1);
+const FIELD_WORD_F32 = new Float32Array(FIELD_WORD.buffer);
 const OPCODE_MASK = VM_OP_MASK;
 const WIDTH_SHIFT = VM_WIDTH_SHIFT;
 const WIDTH_MASK = VM_WIDTH_MASK;
@@ -137,7 +150,7 @@ const LITERAL_U32 = new Uint32Array(LITERAL_F32.buffer);
 /**
  * Execute one section of a particle program against a single particle record.
  *
- * The record is mutated in place (attribute stores). Registers are local. Returns whether the
+ * The record is mutated in place (particle field stores). Registers are local. Returns whether the
  * particle asked to be destroyed and the advanced RNG state so the caller can persist it.
  *
  * This is the CPU reference semantics — the WGSL interpreter is written to match it exactly, and the
@@ -160,11 +173,17 @@ const LITERAL_U32 = new Uint32Array(LITERAL_F32.buffer);
  * which models the fused product, and `FRACT`, whose subtraction cannot round twice.
  *
  * @param {object} params
- * @param {Uint32Array} params.words instruction words for the section (SPAWN or UPDATE)
+ * @param {Uint32Array} params.words instruction words for the section (INIT or UPDATE)
  * @param {Float32Array} params.constants constant pool, one float per word
  * @param {number} params.register_count size of the register file in `f32` slots
- * @param {Uint32Array} params.record particle record words (mutated in place); attributes are f32 bits
+ * @param {Uint32Array} params.record particle record words (mutated in place); particle fields are
+ *   f32 bits
  * @param {number[][]} [params.builtins] builtin values indexed by {@link VM_BUILTIN} id, each a 4-array
+ * @param {Uint32Array} [params.emitter_fields] the emitter's block of emitter fields, as f32 bit
+ *   patterns; a read past its end is zero
+ * @param {Uint32Array} [params.global_fields] the global fields as f32 bit patterns, laid out by the
+ *   system's global layout — the program must be linked against it, as placing it in the heap
+ *   does; a read past its end is zero
  * @param {number} [params.rng_state] initial RNG state (u32)
  * @param {ParticleVMWindSampler|null} [params.sample_wind] how `SAMPLE_WIND` is answered; still air
  *   when left out
@@ -176,13 +195,15 @@ export function execute_particle_vm({
     register_count,
     record,
     builtins = [],
+    emitter_fields = NO_FIELDS,
+    global_fields = NO_FIELDS,
     rng_state = 0,
     sample_wind = null,
 }) {
     // Register file: one f32 per slot. A value of width w occupies w consecutive slots.
     const reg = new Float32Array(register_count);
 
-    // Reinterpret the record's u32 words as f32 for attribute load/store.
+    // Reinterpret the record's u32 words as f32 for particle field load/store.
     const record_f32 = new Float32Array(record.buffer, record.byteOffset, record.length);
 
     let state = rng_state >>> 0;
@@ -268,17 +289,33 @@ export function execute_particle_vm({
                 for (let i = 0; i < w; i++) d[i] = constants[s0 + i];
                 break;
 
-            case LOAD_ATTR:
-                // Lanes past the attribute's component count read zero — a one-component attribute
-                // asked for at width 3 is (x, 0, 0), which is what widening it costs: nothing.
+            case LOAD_PARTICLE_FIELD:
+                // Lanes past the particle field's component count read zero — a one-component
+                // particle field asked for at width 3 is (x, 0, 0), which is what widening it
+                // costs: nothing.
                 for (let i = 0; i < w; i++) d[i] = i < s1 ? record_f32[s0 + i] : 0;
                 break;
 
-            case STORE_ATTR:
+            case STORE_PARTICLE_FIELD:
                 for (let i = 0; i < s2; i++) record_f32[s1 + i] = a[i];
                 break;
 
             case LOAD_BUILTIN: {
+                if (s0 >= EMITTER_FIELD_BASE) {
+                    // A field: `w` words from the emitter's block or the global ones, as the WGSL
+                    // reads them out of the field section.
+                    const fields = s0 >= GLOBAL_FIELD_BASE ? global_fields : emitter_fields;
+                    const index = s0 & FIELD_INDEX_MASK;
+
+                    for (let i = 0; i < w; i++) {
+                        const k = index + i;
+
+                        FIELD_WORD[0] = k < fields.length ? fields[k] : 0;
+                        d[i] = FIELD_WORD_F32[0];
+                    }
+                    break;
+                }
+
                 /*
                  The host supplies the builtin's OWN lanes; the ISA supplies the rest.
 
@@ -440,7 +477,7 @@ export function execute_particle_vm({
             // answer for a vector crossed with itself — where the device subtracts `inf - inf` and
             // gets NaN. a = b = (0, 1e20, 1e20) is the shortest witness, and a NaN that exists
             // only on the GPU is the worst shape this takes: invisible in the editor preview, and
-            // loose in a position attribute from the first frame it appears.
+            // loose in a position particle field from the first frame it appears.
             case CROSS:
                 d[0] = Math.fround(Math.fround(a[1] * b[2]) - Math.fround(a[2] * b[1]));
                 d[1] = Math.fround(Math.fround(a[2] * b[0]) - Math.fround(a[0] * b[2]));

package/src/shade/renderer/particles/vm/chunk_particle_vm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_particle_vm.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/vm/chunk_particle_vm.js"],"names":[],"mappings":"AAkVA;;;GAGG;AACH,gCAFU,SAAS,CAEmG;0BArV5F,oCAAoC"}
+{"version":3,"file":"chunk_particle_vm.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/vm/chunk_particle_vm.js"],"names":[],"mappings":"AAwWA;;;GAGG;AACH,gCAFU,SAAS,CAEmG;0BA3W5F,oCAAoC"}

package/src/shade/renderer/particles/vm/chunk_particle_vm.js

@@ -3,6 +3,9 @@ import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 import {
     PARTICLE_VM_INSTRUCTION_WORDS,
     VM_BUILTIN,
+    VM_BUILTIN_EMITTER_FIELD_BASE,
+    VM_BUILTIN_FIELD_INDEX_MASK,
+    VM_BUILTIN_GLOBAL_FIELD_BASE,
     VM_DST_MASK,
     VM_DST_SHIFT,
     VM_KIND,
@@ -19,6 +22,7 @@ import {
 } from "../isa/ParticleVMISA.js";
 import {
     PARTICLE_PROGRAM_CODE_BASE_WORD,
+    PARTICLE_PROGRAM_FIELD_BASE_WORD,
     PARTICLE_PROGRAM_HEADER_WORDS,
     PARTICLE_VM_MAX_INSTRUCTIONS,
 } from "../ParticleConstants.js";
@@ -48,12 +52,13 @@ import { PARTICLE_VM_CONTEXT_STRUCT } from "./PARTICLE_VM_CONTEXT_STRUCT.js";
  * ## A lane per statement, never a computed component
  *
  * Nothing here indexes a vector by a variable. {@link vm_source} fills `v.x`, `v.y`, `v.z`, `v.w`
- * one statement each behind a width test; the stores, the pool and attribute loads and the RNG draws
- * do the same; the write-back is four predicated stores. The obvious loop — `for (c < lanes) {
- * v[c] = ... }` — is the same program and three times slower on an RTX 4090 (5.0 ms against 1.7 ms
- * for the simulate pass of a 4876-instruction effect at 20k alive): a vector written through a
- * computed index is addressable memory as far as the compiler is concerned, so `a`, `b`, `c` and `d`
- * all moved to local memory and every lane became a store and a reload. Spelled out, they stay in
+ * one statement each behind a width test; the stores, the pool and particle field loads and the RNG
+ * draws do the same; the write-back is four predicated stores. The obvious loop —
+ * `for (c < lanes) { v[c] = ... }` — is the same program and three times slower on an RTX 4090
+ * (5.0 ms against 1.7 ms for the simulate pass of a 4876-instruction effect at 20k alive): a
+ * vector written through a computed index is addressable memory as far as the compiler is
+ * concerned, so `a`, `b`, `c` and `d` all moved to local memory and every lane became a store and a
+ * reload. Spelled out, they stay in
  * registers, and an instruction costs what it did under the per-opcode loops (within noise at 50k
  * and 200k alive on the same effect), with the literal kind's savings on top. The register file is
  * the one dynamically indexed array, as it always was.
@@ -124,9 +129,11 @@ import { PARTICLE_VM_CONTEXT_STRUCT } from "./PARTICLE_VM_CONTEXT_STRUCT.js";
  *   populate `vm_ctx` before invoking {@link particle_vm_execute}.
  * - `particle_vm_execute(program, code_offset, instruction_count, constant_offset, pool,
  *   record_base)` runs one section. `program` is the packed program buffer — header, constant pool,
- *   code, see `ParticleConstants.PARTICLE_PROGRAM_HEADER_WORDS` — so code and data are one binding.
- *   Attributes are read/written as f32 bit patterns inside `pool` at `record_base +
- *   attribute_offset`.
+ *   code, fields, see `ParticleConstants.PARTICLE_PROGRAM_HEADER_WORDS` — so code and data are one
+ *   binding. Particle fields are read/written as f32 bit patterns inside `pool` at
+ *   `record_base + particle_field_offset`. Emitter and global fields are read through
+ *   `LOAD_BUILTIN` from the field section: a global field at its offset from the section's base, an
+ *   emitter field from `vm_ctx.emitter_field_offset`, which `vm_ctx` must carry.
  * - The three section parameters may be per-lane or wave-uniform; the interpreter is the same
  *   either way, but not its cost. Simulate passes them through `subgroupBroadcastFirst` because
  *   its waves are one program by construction (`../shaders/shader_particle_simulate.js`), and the
@@ -140,6 +147,7 @@ const PARTICLE_VM_MAX_INSTRUCTIONS : u32 = ${PARTICLE_VM_MAX_INSTRUCTIONS}u;
 const PARTICLE_VM_INSTRUCTION_WORDS : u32 = ${PARTICLE_VM_INSTRUCTION_WORDS}u;
 const PARTICLE_PROGRAM_HEADER_WORDS : u32 = ${PARTICLE_PROGRAM_HEADER_WORDS}u;
 const PARTICLE_PROGRAM_CODE_BASE_WORD : u32 = ${PARTICLE_PROGRAM_CODE_BASE_WORD}u;
+const PARTICLE_PROGRAM_FIELD_BASE_WORD : u32 = ${PARTICLE_PROGRAM_FIELD_BASE_WORD}u;
 
 var<private> vm_killed : bool;
 var<private> vm_ctx : ${PARTICLE_VM_CONTEXT_STRUCT.wgsl_ref};
@@ -238,9 +246,9 @@ fn particle_vm_execute(
                 if (w > 2u) { d.z = bitcast<f32>((*program)[k + 2u]); }
                 if (w > 3u) { d.w = bitcast<f32>((*program)[k + 3u]); }
             }
-            case ${VM_OP.LOAD_ATTR}u: {
-                // Lanes past the attribute's component count read zero, which is how a narrow
-                // attribute reaches a wider operation for free.
+            case ${VM_OP.LOAD_PARTICLE_FIELD}u: {
+                // Lanes past the particle field's component count read zero, which is how a narrow
+                // particle field reaches a wider operation for free.
                 let k = record_base + s0;
                 let n = min(w, s1);
                 d.x = bitcast<f32>((*pool)[k]);
@@ -248,7 +256,7 @@ fn particle_vm_execute(
                 if (n > 2u) { d.z = bitcast<f32>((*pool)[k + 2u]); }
                 if (n > 3u) { d.w = bitcast<f32>((*pool)[k + 3u]); }
             }
-            case ${VM_OP.STORE_ATTR}u: {
+            case ${VM_OP.STORE_PARTICLE_FIELD}u: {
                 // One record word per component; the width is the component count.
                 let k = record_base + s1;
                 (*pool)[k] = bitcast<u32>(a.x);
@@ -257,7 +265,21 @@ fn particle_vm_execute(
                 if (s2 > 3u) { (*pool)[k + 3u] = bitcast<u32>(a.w); }
                 lanes = 0u;
             }
-            case ${VM_OP.LOAD_BUILTIN}u: { d = vm_load_builtin(s0); }
+            case ${VM_OP.LOAD_BUILTIN}u: {
+                if (s0 < ${VM_BUILTIN_EMITTER_FIELD_BASE}u) {
+                    d = vm_load_builtin(s0);
+                } else {
+                    // A field: the instruction's width in words from the field section, as
+                    // LOAD_CONST reads the pool. A global field is at its offset from the section's
+                    // base; an emitter field from the emitter's own block.
+                    var k = (*program)[PARTICLE_PROGRAM_FIELD_BASE_WORD] + (s0 & ${VM_BUILTIN_FIELD_INDEX_MASK}u);
+                    if (s0 < ${VM_BUILTIN_GLOBAL_FIELD_BASE}u) { k = k + vm_ctx.emitter_field_offset; }
+                    d.x = bitcast<f32>((*program)[k]);
+                    if (w > 1u) { d.y = bitcast<f32>((*program)[k + 1u]); }
+                    if (w > 2u) { d.z = bitcast<f32>((*program)[k + 2u]); }
+                    if (w > 3u) { d.w = bitcast<f32>((*program)[k + 3u]); }
+                }
+            }
             case ${VM_OP.KILL}u: {
                 if (a.x > 0.0) { vm_killed = true; }
                 lanes = 0u;

package/src/shade/renderer/path_tracer/shader/INDIRECT_TEXTURE_FILTER.d.ts

@@ -0,0 +1,13 @@
+/**
+ * How a shader reads the resident material textures — decided by {@link chunk_indirect_sample_texture},
+ * so the material reads written once (`sample_material_data`, `sample_material_alpha`) take one filter
+ * or the other by the pipeline they are linked into.
+ *
+ * Whether the pass averages its reads is the pass's, so it is fixed per shader: `Stochastic`, the
+ * default, for every pass that never sets it; `Exact` for the card capture, which stores each read.
+ *
+ * @type {ShaderSwitch}
+ */
+export const INDIRECT_TEXTURE_FILTER: ShaderSwitch;
+import { ShaderSwitch } from "../../shader/compiler/ShaderSwitch.js";
+//# sourceMappingURL=INDIRECT_TEXTURE_FILTER.d.ts.map

package/src/shade/renderer/path_tracer/shader/INDIRECT_TEXTURE_FILTER.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"INDIRECT_TEXTURE_FILTER.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/shader/INDIRECT_TEXTURE_FILTER.js"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,sCAFU,YAAY,CAEqF;6BAb9E,uCAAuC"}

package/src/shade/renderer/path_tracer/shader/INDIRECT_TEXTURE_FILTER.js

@@ -0,0 +1,14 @@
+import { ShaderSwitch } from "../../shader/compiler/ShaderSwitch.js";
+import { IndirectTextureFilter } from "./IndirectTextureFilter.js";
+
+/**
+ * How a shader reads the resident material textures — decided by {@link chunk_indirect_sample_texture},
+ * so the material reads written once (`sample_material_data`, `sample_material_alpha`) take one filter
+ * or the other by the pipeline they are linked into.
+ *
+ * Whether the pass averages its reads is the pass's, so it is fixed per shader: `Stochastic`, the
+ * default, for every pass that never sets it; `Exact` for the card capture, which stores each read.
+ *
+ * @type {ShaderSwitch}
+ */
+export const INDIRECT_TEXTURE_FILTER = ShaderSwitch.enum('indirect texture filter', IndirectTextureFilter);

package/src/shade/renderer/path_tracer/shader/IndirectTextureFilter.d.ts

@@ -0,0 +1,10 @@
+/**
+ * How a read of the resident material textures (`indirect_sample_texture`) takes the texture filtered
+ * at a level: trilinearly, bilinear at the two levels around it and those lerped.
+ */
+export type IndirectTextureFilter = number;
+export namespace IndirectTextureFilter {
+    let Stochastic: number;
+    let Exact: number;
+}
+//# sourceMappingURL=IndirectTextureFilter.d.ts.map

package/src/shade/renderer/path_tracer/shader/IndirectTextureFilter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IndirectTextureFilter.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/shader/IndirectTextureFilter.js"],"names":[],"mappings":";;;;oCAIU,MAAM"}

package/src/shade/renderer/path_tracer/shader/IndirectTextureFilter.js

@@ -0,0 +1,15 @@
+/**
+ * How a read of the resident material textures (`indirect_sample_texture`) takes the texture filtered
+ * at a level: trilinearly, bilinear at the two levels around it and those lerped.
+ *
+ * @enum {number}
+ */
+export const IndirectTextureFilter = {
+    /**
+     * One tap of the filter, a texel of the two levels' eight drawn with its weight: what the filter
+     * gives on average, for a pass that averages many reads into each result — the path tracer.
+     */
+    Stochastic: 0,
+    /** The filter itself, every tap weighed: for a pass that keeps each read as it is — the card capture. */
+    Exact: 1,
+};

package/src/shade/renderer/path_tracer/shader/chunk_indirect_sample_tangent_normal.d.ts

@@ -1,7 +1,8 @@
 /**
- * A resident material's tangent-space normal at `uv`, from its normal texture in the atlas — or +Z,
- * the geometric normal exactly, when it has none (`id` is GPU_DATABASE_NULL; see
- * INDIRECT_MATERIAL_STRUCT's `texture_normal` for why there is no default texture to read instead).
+ * A resident material's tangent-space normal at `uv`, from its normal texture in the atlas at `level`
+ * (see {@link chunk_indirect_sample_texture}) — or +Z, the geometric normal exactly, when it has none
+ * (`id` is GPU_DATABASE_NULL; see INDIRECT_MATERIAL_STRUCT's `texture_normal` for why there is no
+ * default texture to read instead).
  *
  * Reads the `textures` atlas binding, which {@link chunk_indirect_sample_texture} leaves to the
  * shader that includes it.

package/src/shade/renderer/path_tracer/shader/chunk_indirect_sample_tangent_normal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_indirect_sample_tangent_normal.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/shader/chunk_indirect_sample_tangent_normal.js"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH,mDAFU,SAAS,CAeZ;0BA1BmB,oCAAoC"}
+{"version":3,"file":"chunk_indirect_sample_tangent_normal.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/shader/chunk_indirect_sample_tangent_normal.js"],"names":[],"mappings":"AAKA;;;;;;;;;;GAUG;AACH,mDAFU,SAAS,CAeZ;0BA3BmB,oCAAoC"}