@woosh/meep-engine 3.47.0 → 3.50.0

package/src/shade/renderer/particles/runtime/ParticleEmitter.js

@@ -14,7 +14,7 @@ import { EMITTER_ATTRIBUTE_ABSENT, make_emitter_flags } from "../data/PARTICLE_E
  * @type {string[]}
  */
 export const EMITTER_RENDER_CHANNELS = Object.freeze([
-    "position", "size", "color", "rotation", "frame", "velocity",
+    "position", "size", "color", "orientation", "frame", "velocity",
 ]);
 
 /**
@@ -34,7 +34,7 @@ export const EMITTER_RENDER_CHANNEL_COMPONENTS = Object.freeze({
     position: 3,
     size: 1,
     color: 4,
-    rotation: 1,
+    orientation: 4,
     frame: 1,
     velocity: 3,
 });
@@ -207,8 +207,8 @@ export class ParticleEmitter {
     render_size = EMITTER_ATTRIBUTE_ABSENT;
     /** @type {number} record word offset of rgba colour */
     render_color = EMITTER_ATTRIBUTE_ABSENT;
-    /** @type {number} record word offset of roll angle, radians */
-    render_rotation = EMITTER_ATTRIBUTE_ABSENT;
+    /** @type {number} record word offset of the orientation, a quaternion (x, y, z, w) turning the sprite inside its projection mode's frame */
+    render_orientation = EMITTER_ATTRIBUTE_ABSENT;
     /** @type {number} record word offset of flipbook frame index */
     render_frame = EMITTER_ATTRIBUTE_ABSENT;
     /** @type {number} record word offset of velocity, read by the STRETCHED projection */
@@ -244,7 +244,7 @@ export class ParticleEmitter {
                 case "position": this.render_position = offset; break;
                 case "size": this.render_size = offset; break;
                 case "color": this.render_color = offset; break;
-                case "rotation": this.render_rotation = offset; break;
+                case "orientation": this.render_orientation = offset; break;
                 case "frame": this.render_frame = offset; break;
                 case "velocity": this.render_velocity = offset; break;
                 default:
@@ -282,7 +282,7 @@ export class ParticleEmitter {
             && this.render_position === other.render_position
             && this.render_size === other.render_size
             && this.render_color === other.render_color
-            && this.render_rotation === other.render_rotation
+            && this.render_orientation === other.render_orientation
             && this.render_frame === other.render_frame
             && this.render_velocity === other.render_velocity
             && is_typed_array_equals(this.flipbook, other.flipbook)
@@ -300,7 +300,7 @@ export class ParticleEmitter {
     hash() {
         const bindings = hash_mix3(
             hash_mix3(this.render_position, this.render_size, this.render_color),
-            hash_mix3(this.render_rotation, this.render_frame, this.render_velocity),
+            hash_mix3(this.render_orientation, this.render_frame, this.render_velocity),
             this.flags
         );
 
@@ -348,7 +348,7 @@ export class ParticleEmitter {
         this.render_position = other.render_position;
         this.render_size = other.render_size;
         this.render_color = other.render_color;
-        this.render_rotation = other.render_rotation;
+        this.render_orientation = other.render_orientation;
         this.render_frame = other.render_frame;
         this.render_velocity = other.render_velocity;
 

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

@@ -1 +1 @@
-{"version":3,"file":"chunk_particle_billboard_vertex.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_billboard_vertex.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;GAgBG;AACH,8CAFU,SAAS,CAyE6D;0BA/FtD,oCAAoC"}
+{"version":3,"file":"chunk_particle_billboard_vertex.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_billboard_vertex.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;GAgBG;AACH,8CAFU,SAAS,CA2E6D;0BAjGtD,oCAAoC"}

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

@@ -66,8 +66,9 @@ fn particle_billboard_vertex(vi : u32, ii : u32) -> ParticleVertexOut {
     if (em.render_size != PARTICLE_ATTRIBUTE_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); }
-    var rotation = 0.0;
-    if (em.render_rotation != PARTICLE_ATTRIBUTE_ABSENT) { rotation = bitcast<f32>(pool[base + em.render_rotation]); }
+    // 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); }
     var frame = 0.0;
     if (em.render_frame != PARTICLE_ATTRIBUTE_ABSENT) { frame = bitcast<f32>(pool[base + em.render_frame]); }
     var velocity = vec3<f32>(0.0);
@@ -79,7 +80,8 @@ fn particle_billboard_vertex(vi : u32, ii : u32) -> ParticleVertexOut {
     let cam_position = camera.transform[3].xyz;
 
     let projection = particle_emitter_projection(em.flags);
-    let offset = particle_billboard_offset(corner, size, rotation, cam_right, cam_up, cam_forward, velocity, projection);
+    let basis = particle_basis(orientation, cam_right, cam_up, cam_forward, velocity, projection);
+    let offset = particle_billboard_offset(corner, size, basis);
     let world = world_center + offset;
 
     var out : ParticleVertexOut;
@@ -87,7 +89,7 @@ fn particle_billboard_vertex(vi : u32, ii : u32) -> ParticleVertexOut {
     out.uv = particle_atlas_uv(corner * 0.5 + vec2<f32>(0.5), em.atlas_region, em.flipbook, frame);
     out.color = color;
     out.world_position = world;
-    out.normal = particle_billboard_normal(offset, cam_position - world, cam_forward, projection);
+    out.normal = particle_billboard_normal(offset, cam_position - world, basis);
     out.view_depth = -(camera.view_matrix * vec4<f32>(world, 1.0)).z;
     out.flags = em.flags;
     out.blend = particle_emitter_blend(em.flags);

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

@@ -2,15 +2,16 @@
  * Pure render-math helpers shared by every pass that draws a particle, kept separate so they can be
  * unit-tested in isolation (they take no bindings):
  *
- * - `particle_billboard_offset` — expand a quad corner into a world-space offset for each projection
- *   / orientation mode (camera-facing, velocity-stretched, ground-aligned, axis-locked, world).
+ * - `particle_basis` — where a particle's quad lies in the world: the projection mode's frame
+ *   (camera-facing, velocity-stretched, ground-aligned, axis-locked, world) composed with the
+ *   particle's own orientation, plus the mode's stretch.
+ * - `particle_billboard_offset` — expand a quad corner into a world-space offset on that basis.
  * - `particle_billboard_radius` — the largest offset that function can return, over every corner,
- *   every roll angle and every camera. What a bounds pass has to dilate a particle's centre by to
+ *   every orientation and every camera. What a bounds pass has to dilate a particle's centre by to
  *   hold its quad, and the reason it sits next to the function it bounds rather than with the bounds
  *   pass: the two are one statement, and they drift the moment they are written apart.
- * - `particle_billboard_normal` — the normal a lit particle is shaded with at a corner: the plane
- *   that function lays the quad in, turned to the side the camera sees and bent out toward the
- *   corner.
+ * - `particle_billboard_normal` — the normal a lit particle is shaded with at a corner: the basis's
+ *   face, turned to the side the camera sees and bent out toward the corner.
  * - `particle_atlas_uv` — map a local quad uv into an atlas sub-rect, honouring a flipbook grid +
  *   frame index (mirrors meep's AtlasPatch offset/scale convention).
  * - `particle_soft_fade` — soft-particle alpha fade from scene-vs-particle view depth.

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

@@ -1 +1 @@
-{"version":3,"file":"chunk_particle_render_math.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_render_math.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,yCAFU,SAAS,CA8JhB;0BArLuB,oCAAoC"}
+{"version":3,"file":"chunk_particle_render_math.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_render_math.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,yCAFU,SAAS,CA6LQ;0BAtND,oCAAoC"}

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

@@ -1,19 +1,21 @@
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_quat_rotate_v3 } from "../../shader/chunk/geometry/quaternion/chunk_v3_apply_quat.js";
 import { EMITTER_BLEND, EMITTER_PROJECTION } from "../data/PARTICLE_EMITTER_STRUCT.js";
 
 /**
  * Pure render-math helpers shared by every pass that draws a particle, kept separate so they can be
  * unit-tested in isolation (they take no bindings):
  *
- * - `particle_billboard_offset` — expand a quad corner into a world-space offset for each projection
- *   / orientation mode (camera-facing, velocity-stretched, ground-aligned, axis-locked, world).
+ * - `particle_basis` — where a particle's quad lies in the world: the projection mode's frame
+ *   (camera-facing, velocity-stretched, ground-aligned, axis-locked, world) composed with the
+ *   particle's own orientation, plus the mode's stretch.
+ * - `particle_billboard_offset` — expand a quad corner into a world-space offset on that basis.
  * - `particle_billboard_radius` — the largest offset that function can return, over every corner,
- *   every roll angle and every camera. What a bounds pass has to dilate a particle's centre by to
+ *   every orientation and every camera. What a bounds pass has to dilate a particle's centre by to
  *   hold its quad, and the reason it sits next to the function it bounds rather than with the bounds
  *   pass: the two are one statement, and they drift the moment they are written apart.
- * - `particle_billboard_normal` — the normal a lit particle is shaded with at a corner: the plane
- *   that function lays the quad in, turned to the side the camera sees and bent out toward the
- *   corner.
+ * - `particle_billboard_normal` — the normal a lit particle is shaded with at a corner: the basis's
+ *   face, turned to the side the camera sees and bent out toward the corner.
  * - `particle_atlas_uv` — map a local quad uv into an atlas sub-rect, honouring a flipbook grid +
  *   frame index (mirrors meep's AtlasPatch offset/scale convention).
  * - `particle_soft_fade` — soft-particle alpha fade from scene-vs-particle view depth.
@@ -36,65 +38,108 @@ const PARTICLE_BLEND_ALPHA : u32 = ${EMITTER_BLEND.ALPHA}u;
 const PARTICLE_BLEND_ADDITIVE : u32 = ${EMITTER_BLEND.ADDITIVE}u;
 const PARTICLE_BLEND_PREMULTIPLIED : u32 = ${EMITTER_BLEND.PREMULTIPLIED}u;
 
-// Expand a quad corner (components in {-1,+1}) into a world-space offset from the particle centre.
-fn particle_billboard_offset(
-    corner : vec2<f32>,
-    size : f32,
-    rotation : f32,
+// Where a particle's quad lies in the world: the directions its own +X, +Y and +Z point once the
+// projection mode's frame and the particle's orientation are composed, and how far the mode
+// elongates the sprite along its own +Y.
+struct ParticleBasis {
+    right : vec3<f32>,
+    up : vec3<f32>,
+    face : vec3<f32>,
+    stretch : f32,
+}
+
+// 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.
+fn particle_orientation_unit(q : vec4<f32>) -> vec4<f32> {
+    return q * inverseSqrt(max(dot(q, q), 1e-30));
+}
+
+// The basis a projection mode lays a particle's quad on.
+//
+// A mode contributes a frame and nothing else: a proper rotation whose x and y are the screen's
+// right and up for BILLBOARD, and whose z is the side the mode shows — toward the eye for the
+// camera-facing modes, world +Y for HORIZONTAL, world +Z for FACING_WORLD — so the sprite reads the
+// way round BILLBOARD draws it from that side rather than as its mirror image. STRETCHED adds its
+// elongation, which belongs to the sprite and stretches it along its own +Y.
+//
+// The particle's orientation is a rotation inside that frame. FACING_WORLD's frame is the world's,
+// so there it is the particle's rotation in the world; BILLBOARD's is the view's, so there it turns
+// the quad relative to the eye — a rotation about +Z is a roll on the screen. The frame is the one
+// part that depends on a view, which is why it is the renderer's and the rotation is the record's:
+// one record is drawn by every view, and no rotation written into it could face them all.
+fn particle_basis(
+    orientation : vec4<f32>,
     cam_right : vec3<f32>,
     cam_up : vec3<f32>,
     cam_forward : vec3<f32>,
     velocity_ws : vec3<f32>,
     projection : u32,
-) -> vec3<f32> {
-    // In-plane roll about the view direction.
-    let cr = cos(rotation);
-    let sr = sin(rotation);
-    let rc = vec2<f32>(corner.x * cr - corner.y * sr, corner.x * sr + corner.y * cr);
-
+) -> ParticleBasis {
     var right = cam_right;
     var up = cam_up;
+    var stretch = 1.0;
 
     if (projection == PARTICLE_PROJ_HORIZONTAL) {
+        // faces world +Y: seen from above with -Z at the top of the screen, it reads as on the page
         right = vec3<f32>(1.0, 0.0, 0.0);
-        up = vec3<f32>(0.0, 0.0, 1.0);
+        up = vec3<f32>(0.0, 0.0, -1.0);
     } else if (projection == PARTICLE_PROJ_VERTICAL) {
         up = vec3<f32>(0.0, 1.0, 0.0);
-        let r = cross(up, cam_forward);
+        let r = cross(cam_forward, up);
         let rl = length(r);
         right = select(vec3<f32>(1.0, 0.0, 0.0), r / rl, rl > 1e-5);
     } else if (projection == PARTICLE_PROJ_STRETCHED) {
-        // Align the quad's local Y with the screen-projected velocity and elongate it by the
-        // projected speed (a particle moving 2 units/s draws 3x as long as it is wide).
+        // Align the sprite's +Y with the screen-projected velocity and elongate it by the projected
+        // speed (a particle moving 2 units/s draws 3x as long as it is wide).
         let v_screen = vec2<f32>(dot(velocity_ws, cam_right), dot(velocity_ws, cam_up));
         let vl = length(v_screen);
         let dir = select(vec2<f32>(0.0, 1.0), v_screen / vl, vl > 1e-5);
-        let perp = vec2<f32>(-dir.y, dir.x);
-        let local = perp * rc.x + dir * rc.y * (1.0 + vl);
-        return (cam_right * local.x + cam_up * local.y) * size;
+        // the direction turned clockwise on the screen, so (right, up) is the camera's at rest
+        right = cam_right * dir.y - cam_up * dir.x;
+        up = cam_right * dir.x + cam_up * dir.y;
+        stretch = 1.0 + vl;
     } else if (projection == PARTICLE_PROJ_FACING_WORLD) {
-        // Fixed world-space orientation: the quad lies in the world XY plane (faces +/-Z) and the
-        // rotation attribute rolls it in that plane — independent of the camera.
         right = vec3<f32>(1.0, 0.0, 0.0);
         up = vec3<f32>(0.0, 1.0, 0.0);
     }
 
-    return (right * rc.x + up * rc.y) * size;
+    let face = cross(right, up);
+
+    // the orientation, as where it sends the sprite's own three axes
+    let q = particle_orientation_unit(orientation);
+    let ox = quat_rotate_v3(q, vec3<f32>(1.0, 0.0, 0.0));
+    let oy = quat_rotate_v3(q, vec3<f32>(0.0, 1.0, 0.0));
+    let oz = quat_rotate_v3(q, vec3<f32>(0.0, 0.0, 1.0));
+
+    var basis : ParticleBasis;
+    basis.right = right * ox.x + up * ox.y + face * ox.z;
+    basis.up = right * oy.x + up * oy.y + face * oy.z;
+    basis.face = right * oz.x + up * oz.y + face * oz.z;
+    basis.stretch = stretch;
+    return basis;
+}
+
+// Expand a quad corner (components in {-1,+1}) into a world-space offset from the particle centre.
+fn particle_billboard_offset(corner : vec2<f32>, size : f32, basis : ParticleBasis) -> vec3<f32> {
+    return (basis.right * corner.x + basis.up * (corner.y * basis.stretch)) * size;
 }
 
 // The radius of the sphere holding every offset particle_billboard_offset can return for a particle
-// of this size, velocity and projection — over all four corners, every roll angle, and any camera.
+// of this size, velocity and projection — over all four corners, every orientation, and any camera.
 //
-// A corner is (±1, ±1), so a rolled corner \`rc\` has |rc| = sqrt(2) whatever the angle: rotation
-// moves a corner around the quad's circumcircle, it does not shrink it. Every mode then lays \`rc\`
-// down on two orthonormal axes and scales by \`size\`, which makes |offset| = sqrt(2) * size exactly
-// — camera-facing, ground-aligned, axis-locked and world-facing alike, because "which two unit
-// axes" is the only thing that separates them.
+// A corner is (±1, ±1), so |corner| = sqrt(2). Every mode lays it on its basis, which is a rotation —
+// the mode's frame composed with the particle's orientation, both rotations — and scales it by
+// \`size\`, which makes |offset| = sqrt(2) * size exactly: camera-facing, ground-aligned, axis-locked
+// and world-facing alike, whatever way the particle is turned, because a rotation moves a corner
+// around a sphere and never off it. The orientation is therefore not an argument here, and the
+// bounds pass never reads it.
 //
-// STRETCHED is the one that reaches further: it elongates the corner along the screen-space
-// velocity by (1 + |v_screen|) before the same two axes. |v_screen| is a projection of the world
-// velocity onto two orthonormal axes and so is at most |v|, which is what makes the world-space
-// speed the camera-independent bound this needs to be.
+// STRETCHED is the one that reaches further: it elongates the sprite along its own +Y by
+// (1 + |v_screen|) before the rotation, which moves no corner further than that factor.
+// |v_screen| is a projection of the world velocity onto two orthonormal axes and so is at most |v|,
+// which is what makes the world-space speed the camera-independent bound this needs to be.
 //
 // Camera-independent is the requirement, not a nicety: the box this feeds is measured over one
 // frame and read on the next, by which time the camera has moved.
@@ -115,26 +160,14 @@ const PARTICLE_NORMAL_CURVATURE : f32 = 1.0;
 
 // The shading normal at a corner that particle_billboard_offset put at offset from the centre.
 //
-// Each projection mode lays the quad on two fixed axes, and the face normal is theirs: the camera
-// plane for BILLBOARD and STRETCHED, world up for HORIZONTAL, the camera direction flattened onto
-// the ground for VERTICAL (world Z when the camera looks straight down, as the offset falls back to
-// world X there), world Z for FACING_WORLD. A quad has two sides and is drawn from both, so the face
-// is turned toward to_camera, the vector from the corner to the eye, not the camera's axis: a
-// camera tilted up at a quad lying on the ground below it still sees its top.
-fn particle_billboard_normal(offset : vec3<f32>, to_camera : vec3<f32>, cam_forward : vec3<f32>, projection : u32) -> vec3<f32> {
-    var face = -cam_forward;
-
-    if (projection == PARTICLE_PROJ_HORIZONTAL) {
-        face = vec3<f32>(0.0, 1.0, 0.0);
-    } else if (projection == PARTICLE_PROJ_VERTICAL) {
-        let horizontal = vec3<f32>(cam_forward.x, 0.0, cam_forward.z);
-        let hl = length(horizontal);
-        face = select(vec3<f32>(0.0, 0.0, 1.0), horizontal / hl, hl > 1e-5);
-    } else if (projection == PARTICLE_PROJ_FACING_WORLD) {
-        face = vec3<f32>(0.0, 0.0, 1.0);
-    }
-
-    face = select(face, -face, dot(face, to_camera) < 0.0);
+// The face is the basis's own: the same frame and orientation that laid the quad down, so the two
+// cannot disagree about which way a mode faces. A stretch scales the sprite along a direction in
+// its own plane, which leaves the plane — and so the face — where it was. A quad has two sides and
+// is drawn from both, so the face is turned toward to_camera, the vector from the corner to the eye,
+// not the camera's axis: a camera tilted up at a quad lying on the ground below it still sees its
+// top.
+fn particle_billboard_normal(offset : vec3<f32>, to_camera : vec3<f32>, basis : ParticleBasis) -> vec3<f32> {
+    let face = select(basis.face, -basis.face, dot(basis.face, to_camera) < 0.0);
 
     // a zero-size particle has no corner to lean toward
     let ol = length(offset);
@@ -179,4 +212,4 @@ fn particle_premultiply(color : vec4<f32>, blend : u32) -> vec4<f32> {
     }
     return vec4<f32>(color.rgb * color.a, color.a);
 }
-`);
+`, [chunk_quat_rotate_v3]);

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

@@ -25,7 +25,7 @@ import { chunk_particle_lighting } from "./chunk_particle_lighting.js";
 /**
  * The particles' AVBOIT draw: the billboard quads at internal resolution, depth-tested against the
  * opaque scene, into the four accumulators the transparent meshes draw into
- * (`avboit_draw_fragment_body`). The particle counterpart of `shader_avboit_draw_ibl`.
+ * (`avboit_draw_fragment_body`). The particle counterpart of `shader_avboit_draw`.
  *
  * Per fragment: the atlas sample times the particle colour, the soft-depth fade against the scene
  * depth, lighting for an emitter flagged `EMITTER_FLAG.LIGHTING` (`chunk_particle_lighting`: the

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

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_emit.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_emit.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;GAGG;AACH,kDAA8E;AAE9E;;;;;;;;GAQG;AACH,4BAFU,YAAY,CAOK;AA2D3B,iDAIG;6BAhH0B,mCAAmC;8BAIlC,+BAA+B"}
+{"version":3,"file":"shader_particle_emit.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_emit.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;GAGG;AACH,kDAA8E;AAE9E;;;;;;;;GAQG;AACH,4BAFU,YAAY,CAOK;AA4D3B,iDAIG;6BAnH0B,mCAAmC;8BAIlC,+BAA+B"}

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

@@ -9,6 +9,8 @@ import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
 import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
 import { chunk_particle_vm_registers_fast } from "../vm/chunk_particle_vm_registers_fast.js";
+import { chunk_particle_vm_wind_field } from "../vm/chunk_particle_vm_wind_field.js";
+import { wind_field_add_resources } from "../../wind/wind_field_add_resources.js";
 import { chunk_particle_emit_step } from "./chunk_particle_emit_step.js";
 
 /**
@@ -55,7 +57,7 @@ const resources = new ShaderResourceSetDescriptor();
 
 resources.setImmediate('settings', EMIT_SETTINGS);
 
-resources.createGroup()
+wind_field_add_resources(resources.createGroup()
     .addStorageBuffer("scene_database", WebGPUArray.u32, false)
     .addStorageBuffer("emitter_database", WebGPUArray.u32, false)
     .addStorageBuffer("program", WebGPUArray.u32, false)
@@ -63,7 +65,7 @@ resources.createGroup()
     .addStorageBuffer("pool", WebGPUArray.u32, true)
     .addStorageBuffer("alive_out", WebGPUArray.u32, true)
     .addStorageBuffer("dead", WebGPUArray.u32, true)
-    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true));
 
 const body = CodeChunk.from(
     /* language=wgsl */
@@ -106,6 +108,7 @@ fn main(
     chunk_grid3d_to_index,
     chunk_particle_emit_step,
     chunk_particle_vm_registers_fast,
+    chunk_particle_vm_wind_field,
 ]);
 
 export const shader_particle_emit = ComputeShader.from({

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

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_emit_wide.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_emit_wide.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;GAIG;AACH,iDAFU,MAAM,CAGiD;AAgEjE,sDAIG;8BA5G2B,+BAA+B"}
+{"version":3,"file":"shader_particle_emit_wide.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_emit_wide.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;GAIG;AACH,iDAFU,MAAM,CAGiD;AAiEjE,sDAIG;8BA/G2B,+BAA+B"}

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

@@ -7,6 +7,8 @@ import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourc
 import { PARTICLE_VM_WIDE_LAUNCH_LANES } from "../ParticleConstants.js";
 import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
 import { chunk_particle_vm_registers_wide } from "../vm/chunk_particle_vm_registers_wide.js";
+import { chunk_particle_vm_wind_field } from "../vm/chunk_particle_vm_wind_field.js";
+import { wind_field_add_resources } from "../../wind/wind_field_add_resources.js";
 import { chunk_particle_emit_step } from "./chunk_particle_emit_step.js";
 import { EMIT_SETTINGS, PARTICLE_EMIT_WORKGROUP_SIZE } from "./shader_particle_emit.js";
 
@@ -47,7 +49,7 @@ const resources = new ShaderResourceSetDescriptor();
 
 resources.setImmediate('settings', EMIT_SETTINGS);
 
-resources.createGroup()
+wind_field_add_resources(resources.createGroup()
     .addStorageBuffer("scene_database", WebGPUArray.u32, false)
     .addStorageBuffer("emitter_database", WebGPUArray.u32, false)
     .addStorageBuffer("program", WebGPUArray.u32, false)
@@ -56,7 +58,7 @@ resources.createGroup()
     .addStorageBuffer("alive_out", WebGPUArray.u32, true)
     .addStorageBuffer("dead", WebGPUArray.u32, true)
     .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true)
-    .addStorageBuffer("vm_registers", WebGPUArray.from(f32), true);
+    .addStorageBuffer("vm_registers", WebGPUArray.from(f32), true));
 
 const body = CodeChunk.from(
     /* language=wgsl */
@@ -103,6 +105,7 @@ fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
 `, [
     chunk_particle_emit_step,
     chunk_particle_vm_registers_wide,
+    chunk_particle_vm_wind_field,
 ]);
 
 export const shader_particle_emit_wide = ComputeShader.from({

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

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_simulate.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_simulate.js"],"names":[],"mappings":";AAuDA;;;;;GAKG;AACH,gCAFU,YAAY,CAMS;AAsD/B,qDAIG;iDApH8C,yBAAyB;6BAJ7C,mCAAmC;8BAClC,+BAA+B"}
+{"version":3,"file":"shader_particle_simulate.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_simulate.js"],"names":[],"mappings":";AAyDA;;;;;GAKG;AACH,gCAFU,YAAY,CAMS;AAuD/B,qDAIG;iDAvH8C,yBAAyB;6BAJ7C,mCAAmC;8BAClC,+BAA+B"}

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

@@ -8,6 +8,8 @@ import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourc
 import { PARTICLE_SIMULATE_WORKGROUP_SIZE } from "../ParticleConstants.js";
 import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
 import { chunk_particle_vm_registers_fast } from "../vm/chunk_particle_vm_registers_fast.js";
+import { chunk_particle_vm_wind_field } from "../vm/chunk_particle_vm_wind_field.js";
+import { wind_field_add_resources } from "../../wind/wind_field_add_resources.js";
 import { chunk_particle_simulate_step } from "./chunk_particle_simulate_step.js";
 
 /**
@@ -69,7 +71,7 @@ const resources = new ShaderResourceSetDescriptor();
 
 resources.setImmediate('settings', SIMULATE_SETTINGS);
 
-resources.createGroup()
+wind_field_add_resources(resources.createGroup()
     .addStorageBuffer("scene_database", WebGPUArray.u32, false)
     .addStorageBuffer("emitter_database", WebGPUArray.u32, false)
     .addStorageBuffer("program", WebGPUArray.u32, false)
@@ -77,7 +79,7 @@ resources.createGroup()
     .addStorageBuffer("sim_list", WebGPUArray.u32, false)
     .addStorageBuffer("alive_out", WebGPUArray.u32, true)
     .addStorageBuffer("dead", WebGPUArray.u32, true)
-    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true));
 
 
 const body = CodeChunk.from(/* language=wgsl */ `
@@ -113,6 +115,7 @@ fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
 `, [
     chunk_particle_simulate_step,
     chunk_particle_vm_registers_fast,
+    chunk_particle_vm_wind_field,
 ]);
 
 body.addExtension(WebGPUExtensionType.Subgroups);

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

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_simulate_wide.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_simulate_wide.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH;;;GAGG;AACH,qDAFU,MAAM,CAGqD;AA6DrE,0DAIG;8BArH2B,+BAA+B"}
+{"version":3,"file":"shader_particle_simulate_wide.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_simulate_wide.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH;;;GAGG;AACH,qDAFU,MAAM,CAGqD;AA8DrE,0DAIG;8BAxH2B,+BAA+B"}

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

@@ -7,6 +7,8 @@ import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourc
 import { PARTICLE_SIMULATE_WORKGROUP_SIZE, PARTICLE_VM_WIDE_LAUNCH_LANES } from "../ParticleConstants.js";
 import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
 import { chunk_particle_vm_registers_wide } from "../vm/chunk_particle_vm_registers_wide.js";
+import { chunk_particle_vm_wind_field } from "../vm/chunk_particle_vm_wind_field.js";
+import { wind_field_add_resources } from "../../wind/wind_field_add_resources.js";
 import { chunk_particle_simulate_step } from "./chunk_particle_simulate_step.js";
 import { SIMULATE_SETTINGS } from "./shader_particle_simulate.js";
 
@@ -59,7 +61,7 @@ const resources = new ShaderResourceSetDescriptor();
 
 resources.setImmediate('settings', SIMULATE_SETTINGS);
 
-resources.createGroup()
+wind_field_add_resources(resources.createGroup()
     .addStorageBuffer("scene_database", WebGPUArray.u32, false)
     .addStorageBuffer("emitter_database", WebGPUArray.u32, false)
     .addStorageBuffer("program", WebGPUArray.u32, false)
@@ -68,7 +70,7 @@ resources.createGroup()
     .addStorageBuffer("alive_out", WebGPUArray.u32, true)
     .addStorageBuffer("dead", WebGPUArray.u32, true)
     .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true)
-    .addStorageBuffer("vm_registers", WebGPUArray.from(f32), true);
+    .addStorageBuffer("vm_registers", WebGPUArray.from(f32), true));
 
 
 const body = CodeChunk.from(/* language=wgsl */ `
@@ -110,6 +112,7 @@ fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
 `, [
     chunk_particle_simulate_step,
     chunk_particle_vm_registers_wide,
+    chunk_particle_vm_wind_field,
 ]);
 
 body.addExtension(WebGPUExtensionType.Subgroups);

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

@@ -49,17 +49,32 @@ export function u32_to_unit_f32(u: number): number;
  * @param {Uint32Array} params.record particle record words (mutated in place); attributes are f32 bits
  * @param {number[][]} [params.builtins] builtin values indexed by {@link VM_BUILTIN} id, each a 4-array
  * @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, }: {
+export function execute_particle_vm({ words, constants, register_count, record, builtins, rng_state, sample_wind, }: {
     words: Uint32Array;
     constants: Float32Array;
     register_count: number;
     record: Uint32Array;
     builtins?: number[][];
     rng_state?: number;
+    sample_wind?: ParticleVMWindSampler | null;
 }): {
     killed: boolean;
     rng_state: number;
 };
+/**
+ * How a CPU host answers `SAMPLE_WIND`: the wind at a world position, metres per second, written into
+ * `out[0]`, `out[1]` and `out[2]`.
+ *
+ * The opcode reads a resource the host binds, and on the GPU that is the scene's published wind field
+ * (`./chunk_particle_vm_wind_field.js`). A CPU host has no field to read; it answers what it can — a
+ * far field it was handed, typically — and a host that answers nothing reads still air. Called once
+ * per executed `SAMPLE_WIND`, with `out` a scratch of the executor's own that holds zeros on entry, so
+ * a sampler that writes nothing answers zero. It must not allocate: the editor's preview runs it for
+ * every live particle every frame.
+ */
+export type ParticleVMWindSampler = (out: Float32Array, x: number, y: number, z: number) => void;
 //# sourceMappingURL=ParticleVMReference.d.ts.map

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;AA8DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH;IAR+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;IACJ;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAuVlD"}
+{"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"}

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

@@ -89,8 +89,8 @@ 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,
-    LOG, MAD, MAX, MIN, MIX, MOV, MUL, NEG, NOP, NORMALIZE, POW, RANDOM, RSQRT, SELECT, SIN,
-    SMOOTHSTEP, SQRT, STEP, STORE_ATTR, SUB, TAN,
+    LOG, MAD, MAX, MIN, MIX, MOV, MUL, NEG, NOP, NORMALIZE, POW, RANDOM, RSQRT, SAMPLE_WIND, SELECT,
+    SIN, SMOOTHSTEP, SQRT, STEP, STORE_ATTR, SUB, TAN,
 } = VM_OP;
 const KIND_REG = VM_KIND.REG;
 const KIND_IMM = VM_KIND.IMM;
@@ -109,6 +109,25 @@ const INSTRUCTION_WORDS = PARTICLE_VM_INSTRUCTION_WORDS;
 const MAX_INSTRUCTIONS = PARTICLE_VM_MAX_INSTRUCTIONS;
 const MAX_WIDTH = VM_MAX_WIDTH;
 
+/**
+ * How a CPU host answers `SAMPLE_WIND`: the wind at a world position, metres per second, written into
+ * `out[0]`, `out[1]` and `out[2]`.
+ *
+ * The opcode reads a resource the host binds, and on the GPU that is the scene's published wind field
+ * (`./chunk_particle_vm_wind_field.js`). A CPU host has no field to read; it answers what it can — a
+ * far field it was handed, typically — and a host that answers nothing reads still air. Called once
+ * per executed `SAMPLE_WIND`, with `out` a scratch of the executor's own that holds zeros on entry, so
+ * a sampler that writes nothing answers zero. It must not allocate: the editor's preview runs it for
+ * every live particle every frame.
+ *
+ * @callback ParticleVMWindSampler
+ * @param {Float32Array} out where the three lanes go
+ * @param {number} x world position
+ * @param {number} y
+ * @param {number} z
+ * @returns {void}
+ */
+
 /** Scratch for reading a literal's bits as the `f32` they are. */
 const LITERAL_F32 = new Float32Array(1);
 
@@ -147,6 +166,8 @@ const LITERAL_U32 = new Uint32Array(LITERAL_F32.buffer);
  * @param {Uint32Array} params.record particle record words (mutated in place); attributes are f32 bits
  * @param {number[][]} [params.builtins] builtin values indexed by {@link VM_BUILTIN} id, each a 4-array
  * @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({
@@ -156,6 +177,7 @@ export function execute_particle_vm({
     record,
     builtins = [],
     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);
@@ -477,6 +499,17 @@ export function execute_particle_vm({
                 for (let i = 0; i < w; i++) d[i] = draw_unit();
                 break;
 
+            // A read of what the host binds, at the position the first source names; `CROSS`'s
+            // shape, so a fourth lane, if asked for, is zero. The result goes through `d`, an
+            // `f32` scratch, so a host answering in f64 is rounded as the register file would.
+            case SAMPLE_WIND:
+                d[0] = 0;
+                d[1] = 0;
+                d[2] = 0;
+                if (sample_wind !== null) sample_wind(d, a[0], a[1], a[2]);
+                d[3] = 0;
+                break;
+
             default:
                 throw new Error(`ParticleVMReference: unhandled opcode ${op} at pc ${pc}`);
         }