@woosh/meep-engine 3.16.0 → 3.17.0

package/src/shade/renderer/particles/graph/groups/particle_groups_noise.js

@@ -1,517 +1,524 @@
-import { ParticleGroupBuilder } from "../ParticleGroupBuilder.js";
-import { PARTICLE_TYPE_F32, PARTICLE_TYPE_VEC3, PARTICLE_TYPE_VEC4 } from "../ParticleValueType.js";
-
-/**
- * Simplex noise, and the curl fields built out of it.
- *
- * These are the big ones. `simplex3` is around a hundred and thirty instructions and `curl4` is
- * something over two thousand, because a curl needs twelve noise samples and there is no loop to put
- * them in. Nothing here is cheap and nothing here pretends to be; what they are is *correct*, and
- * available as one node instead of as a page of arithmetic an author has to get right themselves.
- *
- * ## Where the algorithm comes from
- *
- * Simplex noise is Ken Perlin's, and the formulation is Stefan Gustavson and Ashima Arts' well-known
- * GLSL one — the same skew, the same permutation polynomial and the same gradient table, so a field
- * produced here matches one produced by that shader lane for lane. It is transcribed rather than
- * reinvented: an author who has seen simplex noise in a shader should get the noise they expect, and
- * a hash or a skew of my own would be a different function wearing the same name.
- *
- * ## Why it is written the way it is
- *
- * The shader version keeps four corners in flight at once — four offsets, four gradients, four
- * weights — as `vec4`s across corners. Done that way here it needs upwards of forty-five registers,
- * and the register file is the interpreter's single largest cost (see
- * {@link ../../ParticleConstants.js PARTICLE_VM_REGISTER_SLOTS}). So the corners are summed one at a
- * time instead: each corner's offset, gradient and weight are computed, folded into a running total,
- * and dropped. The result is identical and the high-water mark is far lower, which is the difference
- * between a node that works and a node that reports it has run out of registers.
- *
- * The permutation itself stays a `vec4` — it is one hash of four corners at once and splitting it
- * would quadruple the work rather than move it.
- */
-
-/** Skew factor for the 3-simplex lattice: `1/3`. @type {number} */
-const F3 = 1 / 3;
-
-/** Unskew factor for the 3-simplex lattice: `1/6`. @type {number} */
-const G3 = 1 / 6;
-
-/** Skew factor for the 4-simplex lattice: `(sqrt(5) - 1) / 4`. @type {number} */
-const F4 = 0.309016994374947451;
-
-/** Unskew factor for the 4-simplex lattice: `(5 - sqrt(5)) / 20`. @type {number} */
-const G4 = 0.138196601125011;
-
-/**
- * `x mod 289`, without a modulo opcode: `x - floor(x / 289) * 289`.
- *
- * 289 is 17 squared, and the permutation polynomial below is built so that its results stay inside
- * `[0, 289)` — which is what keeps the whole hash inside the range a float represents exactly.
- *
- * @param {ParticleGroupBuilder} g
- * @param {*} x
- * @returns {*}
- */
-function mod289(g, x) {
-    return g.sub(x, g.mul(g.floor(g.mul(x, g.f(1 / 289))), g.f(289)));
-}
-
-/**
- * The permutation polynomial: `(34x + 1) x mod 289`.
- *
- * A hash chosen so that composing it over the lattice coordinates spreads corners across the
- * gradient table without a lookup — there are no tables in this VM to look one up in.
- *
- * @param {ParticleGroupBuilder} g
- * @param {*} x
- * @returns {*}
- */
-function permute(g, x) {
-    // `(34x + 1)x` written as `34x*x + x`, which is the same number and costs four fewer registers.
-    //
-    // A constant meeting a vector has to be broadcast into as many registers as the vector is wide,
-    // unless the operation is a multiply — a scalar times a vector lowers to SCALE, which reads its
-    // scalar as one lane. Written the obvious way, the `+ 1` is a four-register constant alive at the
-    // busiest moment of the function. Written this way there is no additive constant at all, and the
-    // `34` is a SCALE operand. See the note about the register file at the top of this file.
-    return mod289(g, g.mad(g.mul(x, g.f(34)), x, x));
-}
-
-/**
- * `1/sqrt(r)` to first order about the gradient lengths this actually sees — the standard
- * `1.79284291400159 - 0.85373472095314 r`.
- *
- * The gradients come off a fixed table and their squared lengths land in a narrow band, so a line
- * through that band normalises them well enough that no visible difference survives; an exact
- * reciprocal square root would be a divide and a `sqrt` per corner instead of one instruction.
- *
- * @param {ParticleGroupBuilder} g
- * @param {*} r
- * @returns {*}
- */
-function taylor_inv_sqrt(g, r) {
-    return g.mad(g.f(-0.85373472095314), r, 1.79284291400159);
-}
-
-/**
- * One corner's contribution to a simplex sum: `max(0.6 - |x|^2, 0)^4 * dot(gradient, x)`.
- *
- * The fourth power of a radial falloff that reaches zero at the edge of a corner's influence, which
- * is what makes the sum continuous and its derivative continuous with it.
- *
- * @param {ParticleGroupBuilder} g
- * @param {*} offset the vector from the corner to the point
- * @param {*} gradient the corner's gradient, already normalised
- * @returns {*} a scalar
- */
-function corner_contribution(g, offset, gradient) {
-    const t = g.max(g.sub(g.f(0.6), g.dot(offset, offset)), 0);
-
-    const t2 = g.mul(t, t);
-
-    return g.mul(g.mul(t2, t2), g.dot(gradient, offset));
-}
-
-/**
- * The 3D gradient for one corner, from its hashed index.
- *
- * The table is the 7x7 grid of points on the faces of an octahedron that Gustavson's formulation
- * uses: the index is split into a row and a column, those become two coordinates, the third is
- * whatever is left of the L1 norm, and the sign of that third one flips the first two. Every step is
- * arithmetic, because there is nowhere to put a table.
- *
- * @param {ParticleGroupBuilder} g
- * @param {*} index a hashed corner index, in `[0, 289)`
- * @returns {*} a `vec3` gradient, not yet normalised
- */
-function grad3(g, index) {
-    const N = 1 / 7;
-
-    const ns_x = N * 2;
-    const ns_y = N * 0.5 - 1;
-    const ns_z = N;
-
-    // j = index mod 49, the 7x7 grid
-    const j = g.sub(index, g.mul(g.f(49), g.floor(g.mul(index, g.f(ns_z * ns_z)))));
-
-    const row = g.floor(g.mul(j, g.f(ns_z)));
-    const col = g.floor(g.sub(j, g.mul(g.f(7), row)));
-
-    const gx = g.mad(row, g.f(ns_x), g.f(ns_y));
-    const gy = g.mad(col, g.f(ns_x), g.f(ns_y));
-
-    // what is left of the unit L1 ball is the third coordinate
-    const gz = g.sub(g.sub(1, g.abs(gx)), g.abs(gy));
-
-    // Outside the ball the point belongs to the opposite face: reflect the first two coordinates.
-    // At or below zero, not below — the coordinates land on a seventh and the boundary is reachable
-    // exactly, so which side it falls on is a decision rather than a rounding accident.
-    const outside = g.op("compare", [gz, 0], { op: "le" });
-
-    const flip = g.mul(g.mad(g.floor(gx), 2, 1), outside);
-    const flop = g.mul(g.mad(g.floor(gy), 2, 1), outside);
-
-    return g.vec3(g.sub(gx, flip), g.sub(gy, flop), gz);
-}
-
-/**
- * Simplex noise over three dimensions, in roughly `[-1, 1]`.
- *
- * @param {ParticleGroupBuilder} g
- * @param {*} v a `vec3` position
- * @returns {*} a scalar
- */
-function simplex3(g, v) {
-    // Which cell of the skewed lattice the point is in, and where it sits inside it.
-    const cell = g.floor(g.add(v, g.dot(v, g.f(F3))));
-    const x0 = g.add(g.sub(v, cell), g.dot(cell, g.f(G3)));
-
-    // The simplex a point falls in is decided by the order of its coordinates: the two steps from
-    // the cell's corner to the point's own are the two largest axes, in order.
-    const order = g.step(g.swz(x0, "yzx"), x0);
-    const rest = g.sub(g.f(1), order);
-
-    const step1 = g.min(order, g.swz(rest, "zxy"));
-    const step2 = g.max(order, g.swz(rest, "zxy"));
-
-    const cell289 = mod289(g, cell);
-
-    // One hash of all four corners at once. Each `permute` folds in one lattice axis.
-    const corners = g.vec4(g.f(0), g.z(step1), g.z(step2), g.f(1));
-
-    let hashed = permute(g, g.add(g.z(cell289), corners));
-
-    hashed = permute(g, g.add(g.add(hashed, g.y(cell289)),
-        g.vec4(g.f(0), g.y(step1), g.y(step2), g.f(1))));
-
-    hashed = permute(g, g.add(g.add(hashed, g.x(cell289)),
-        g.vec4(g.f(0), g.x(step1), g.x(step2), g.f(1))));
-
-    // Corner by corner, so that one corner's working set is all that is ever live at once.
-    const offsets = [
-        x0,
-        g.add(g.sub(x0, step1), g.f(G3)),
-        g.add(g.sub(x0, step2), g.f(G3 * 2)),
-        g.sub(x0, g.f(0.5)),
-    ];
-
-    let total = null;
-
-    ["x", "y", "z", "w"].forEach((lane, corner) => {
-        const gradient = grad3(g, g.swz(hashed, lane));
-
-        const normalized = g.scale(gradient, taylor_inv_sqrt(g, g.dot(gradient, gradient)));
-
-        const contribution = corner_contribution(g, offsets[corner], normalized);
-
-        total = total === null ? contribution : g.add(total, contribution);
-    });
-
-    // scales the sum to about [-1, 1]
-    return g.mul(g.f(42), total);
-}
-
-/**
- * The 4D gradient for one corner, from its hashed index.
- *
- * The table this time is the 32 vertices of a hypercube's cell centres, reached the same way: three
- * coordinates from base-7 digits of the index, the fourth from what is left of the L1 norm, and its
- * sign flipping the other three.
- *
- * @param {ParticleGroupBuilder} g
- * @param {*} index
- * @returns {*} a `vec4` gradient, not yet normalised
- */
-function grad4(g, index) {
-    // 1/294, 1/49, 1/7: successive base-7 digits of the index
-    const digits = g.mul(g.f(1 / 294, 1 / 49, 1 / 7), index);
-
-    // written as scale-then-add rather than as multiply-adds, for the register reason in `permute`
-    const xyz = g.sub(g.mul(g.floor(g.mul(g.fract(digits), g.f(7))), g.f(1 / 7)), 1);
-
-    const w = g.sub(g.f(1.5), g.dot(g.abs(xyz), g.f(1)));
-
-    const negative = g.op("compare", [w, 0], { op: "lt" });
-
-    const sign = g.sub(g.mul(g.op("compare", [xyz, g.f(0)], { op: "lt" }), g.f(2)), 1);
-
-    const flipped = g.add(g.mul(sign, negative), xyz);
-
-    return g.vec4(g.x(flipped), g.y(flipped), g.z(flipped), w);
-}
-
-/**
- * Simplex noise over four dimensions, in roughly `[-1, 1]`.
- *
- * The fourth dimension is what a moving noise field is made of: hold three of them at a position and
- * walk the fourth with time, and the field changes rather than sliding past.
- *
- * @param {ParticleGroupBuilder} g
- * @param {*} v a `vec4` position
- * @returns {*} a scalar
- */
-function simplex4(g, v) {
-    const cell = g.floor(g.add(v, g.dot(v, g.f(F4))));
-    const x0 = g.add(g.sub(v, cell), g.dot(cell, g.f(G4)));
-
-    // The rank of each coordinate among the four, by comparing every pair once. A coordinate's rank
-    // is how many of the others it is at least as large as, and the ranks are the order the four
-    // steps from the cell's corner are taken in.
-    const isX = g.step(g.swz(x0, "yzw"), g.swz(x0, "xxx"));
-    const isYZ = g.step(g.swz(x0, "zww"), g.swz(x0, "yyz"));
-
-    const one_minus = ref => g.sub(g.f(1), ref);
-
-    const rank_x = g.add(g.add(g.x(isX), g.y(isX)), g.z(isX));
-    const rank_y = g.add(one_minus(g.x(isX)), g.add(g.x(isYZ), g.y(isYZ)));
-    const rank_z = g.add(one_minus(g.y(isX)), g.add(one_minus(g.x(isYZ)), g.z(isYZ)));
-    const rank_w = g.add(one_minus(g.z(isX)), g.add(one_minus(g.y(isYZ)), one_minus(g.z(isYZ))));
-
-    const rank = g.vec4(rank_x, rank_y, rank_z, rank_w);
-
-    // A rank is a whole number in 0..3, and the three steps from the cell's corner are the
-    // coordinates whose rank has been passed: the first step takes rank 3, the second 3 and 2, the
-    // third all but rank 0. `clamp(rank - k, 0, 1)` says that, and a clamp reads both of its bounds
-    // at once — so both constants are broadcast to four lanes and live at the same moment. Knowing
-    // the range removes one bound from two of the three.
-    const step_taken = (value, first, last) => {
-        const floored = first ? value : g.max(value, g.f(0));
-
-        return last ? floored : g.min(floored, g.f(1));
-    };
-
-    // The permutation needs one lane of each of the three steps at a time, so it takes them off the
-    // ranks directly rather than off three assembled vectors. Those vectors are twelve registers,
-    // and holding them through the permutation — the busiest part of the function — is what put this
-    // over the register file. Built this way the ranks are all that has to survive it, and the
-    // vectors are assembled afterwards for the corner offsets, by which point the hash is done.
-    const steps_of = axis => {
-        const r = g.swz(rank, axis);
-
-        return g.vec4(
-            step_taken(g.sub(r, g.f(2)), false, true),
-            step_taken(g.sub(r, g.f(1)), false, false),
-            step_taken(r, true, false),
-            g.f(1)
-        );
-    };
-
-    const cell289 = mod289(g, cell);
-
-    // The corner at the cell's own origin hashes on its own; the other four hash together.
-    let origin = permute(g, g.w(cell289));
-
-    origin = permute(g, g.add(origin, g.z(cell289)));
-    origin = permute(g, g.add(origin, g.y(cell289)));
-    origin = permute(g, g.add(origin, g.x(cell289)));
-
-    let hashed = permute(g, g.add(g.w(cell289), steps_of("w")));
-
-    hashed = permute(g, g.add(g.add(hashed, g.z(cell289)), steps_of("z")));
-    hashed = permute(g, g.add(g.add(hashed, g.y(cell289)), steps_of("y")));
-    hashed = permute(g, g.add(g.add(hashed, g.x(cell289)), steps_of("x")));
-
-    const step3 = step_taken(rank, true, false);
-    const step2 = step_taken(g.sub(rank, g.f(1)), false, false);
-    const step1 = step_taken(g.sub(rank, g.f(2)), false, true);
-
-    const offsets = [
-        x0,
-        g.add(g.sub(x0, step1), g.f(G4)),
-        g.add(g.sub(x0, step2), g.f(G4 * 2)),
-        g.add(g.sub(x0, step3), g.f(G4 * 3)),
-        g.add(x0, g.f(G4 * 4 - 1)),
-    ];
-
-    const indices = [origin, g.x(hashed), g.y(hashed), g.z(hashed), g.w(hashed)];
-
-    let total = null;
-
-    for (let corner = 0; corner < 5; corner++) {
-        const gradient = grad4(g, indices[corner]);
-
-        const normalized = g.scale(gradient, taylor_inv_sqrt(g, g.dot(gradient, gradient)));
-
-        const contribution = corner_contribution(g, offsets[corner], normalized);
-
-        total = total === null ? contribution : g.add(total, contribution);
-    }
-
-    return g.mul(g.f(49), total);
-}
-
-/**
- * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
- */
-export const PARTICLE_GROUP_SIMPLEX_3 = (() => {
-    const g = new ParticleGroupBuilder({
-        name: "simplex3",
-        label: "Simplex Noise 3D",
-        icon: "M12 3l8 4.5v9L12 21l-8-4.5v-9z M12 3v18 M4 7.5l16 9 M20 7.5l-16 9",
-        help: "simplex noise at a point in space, about [-1, 1]",
-        inputs: [{ name: "p", type: PARTICLE_TYPE_VEC3 }],
-        outputs: [{ name: "out", type: PARTICLE_TYPE_F32 }],
-    });
-
-    g.out("out", simplex3(g, g.in.p));
-
-    return g.build();
-})();
-
-/**
- * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
- */
-export const PARTICLE_GROUP_SIMPLEX_4 = (() => {
-    const g = new ParticleGroupBuilder({
-        name: "simplex4",
-        label: "Simplex Noise 4D",
-        icon: "M12 3l8 4.5v9L12 21l-8-4.5v-9z M12 3v18 M4 7.5l16 9 M20 7.5l-16 9 M4 7.5l16 0",
-        help: "simplex noise at a point in space and time, about [-1, 1]",
-        inputs: [{ name: "p", type: PARTICLE_TYPE_VEC4 }],
-        outputs: [{ name: "out", type: PARTICLE_TYPE_F32 }],
-    });
-
-    g.out("out", simplex4(g, g.in.p));
-
-    return g.build();
-})();
-
-/**
- * How far apart the samples taken either side of a point are, when differencing the potential.
- *
- * Small enough that the difference is a derivative and large enough that it is not two samples of
- * the same value: simplex noise varies over a unit cell, and a tenth of one is a reasonable step in
- * single precision.
- *
- * @type {number}
- */
-const CURL_EPSILON = 0.1;
-
-/**
- * Offsets that turn one noise field into three independent ones.
- *
- * A curl needs a vector potential, and there is one noise function. Sampling it at three points far
- * enough apart that the values are uncorrelated is the standard way to get three fields out of it —
- * the numbers are arbitrary and only have to be large and unalike.
- *
- * @type {number[][]}
- */
-const CURL_FIELD_OFFSETS = [
-    [0, 0, 0],
-    [31.416, 47.853, 12.793],
-    [83.147, 19.264, 65.037],
-];
-
-/**
- * The curl of a noise field, as a vector.
- *
- * A curl is divergence-free — nothing anywhere is a source or a sink — which is what makes it look
- * like a fluid rather than like noise. Particles advected by one swirl and never pile up, and that
- * is the whole reason to spend this many instructions on it.
- *
- * ## What it costs
- *
- * Twelve noise samples. The curl of a three-component potential needs six partial derivatives, each
- * a difference of two samples, and no two of them are of the same field at the same place. There is
- * no loop to put them in and no way to share them, so the group is twelve copies of the noise and
- * the arithmetic between them — well over a thousand instructions, and worth knowing before it is
- * put in an UPDATE graph that runs on every particle every frame.
- *
- * @param {ParticleGroupBuilder} g
- * @param {function(ParticleGroupBuilder, number, number, number, number): *} sample
- *        the potential's `field`th component at `p + (dx, dy, dz)`, as a scalar
- * @returns {*} a `vec3`
- */
-function curl_of(g, sample) {
-    const e = CURL_EPSILON;
-
-    /**
-     * The centred difference of one field along one axis, *not* divided by the step — every one of
-     * the six is over the same step, so the division comes out of the sum at the end as a single
-     * scale rather than six multiplies.
-     *
-     * @param {number} field
-     * @param {number} axis 0, 1 or 2
-     * @returns {*}
-     */
-    const difference = (field, axis) => {
-        const step = [0, 0, 0];
-
-        step[axis] = e;
-
-        const ahead = sample(g, field, step[0], step[1], step[2]);
-        const behind = sample(g, field, -step[0], -step[1], -step[2]);
-
-        return g.sub(ahead, behind);
-    };
-
-    const curl = g.vec3(
-        g.sub(difference(2, 1), difference(1, 2)),
-        g.sub(difference(0, 2), difference(2, 0)),
-        g.sub(difference(1, 0), difference(0, 1))
-    );
-
-    return g.scale(curl, g.f(1 / (2 * e)));
-}
-
-/**
- * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
- */
-export const PARTICLE_GROUP_CURL_3 = (() => {
-    const g = new ParticleGroupBuilder({
-        name: "curl3",
-        label: "Curl Noise 3D",
-        icon: "M6 15c0-5 5-8 8-5s0 8-3 6-1-6 3-6",
-        help: "a divergence-free swirl field — twelve noise samples, so not cheap",
-        inputs: [{ name: "p", type: PARTICLE_TYPE_VEC3 }],
-        outputs: [{ name: "out", type: PARTICLE_TYPE_VEC3 }],
-    });
-
-    g.out("out", curl_of(g, (builder, field, dx, dy, dz) => {
-        const offset = CURL_FIELD_OFFSETS[field];
-
-        const at = builder.add(builder.in.p, builder.f(offset[0] + dx, offset[1] + dy, offset[2] + dz));
-
-        return builder.call(PARTICLE_GROUP_SIMPLEX_3, { p: at }).out;
-    }));
-
-    return g.build();
-})();
-
-/**
- * The same field, with a fourth coordinate to move it through.
- *
- * Advance `w` with time and the swirl evolves in place instead of drifting past — which is what
- * separates smoke from a conveyor belt of smoke.
- *
- * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
- */
-export const PARTICLE_GROUP_CURL_4 = (() => {
-    const g = new ParticleGroupBuilder({
-        name: "curl4",
-        label: "Curl Noise 4D",
-        icon: "M6 15c0-5 5-8 8-5s0 8-3 6-1-6 3-6 M18 5v4 M16 7h4",
-        help: "a curl field that evolves along w — twelve 4D noise samples, so expensive",
-        inputs: [
-            { name: "p", type: PARTICLE_TYPE_VEC3 },
-            { name: "w", type: PARTICLE_TYPE_F32 },
-        ],
-        outputs: [{ name: "out", type: PARTICLE_TYPE_VEC3 }],
-    });
-
-    g.out("out", curl_of(g, (builder, field, dx, dy, dz) => {
-        const offset = CURL_FIELD_OFFSETS[field];
-
-        const at = builder.vec4(
-            builder.add(builder.x(builder.in.p), builder.f(offset[0] + dx)),
-            builder.add(builder.y(builder.in.p), builder.f(offset[1] + dy)),
-            builder.add(builder.z(builder.in.p), builder.f(offset[2] + dz)),
-            builder.in.w
-        );
-
-        return builder.call(PARTICLE_GROUP_SIMPLEX_4, { p: at }).out;
-    }));
-
-    return g.build();
-})();
+import { ParticleGroupBuilder } from "../ParticleGroupBuilder.js";
+import { PARTICLE_TYPE_F32, PARTICLE_TYPE_VEC3, PARTICLE_TYPE_VEC4 } from "../ParticleValueType.js";
+
+/**
+ * Simplex noise, and the curl fields built out of it.
+ *
+ * These are the big ones. `simplex3` is around a hundred and thirty instructions and `curl4` is
+ * something over two thousand, because a curl needs twelve noise samples and there is no loop to put
+ * them in. Nothing here is cheap and nothing here pretends to be; what they are is *correct*, and
+ * available as one node instead of as a page of arithmetic an author has to get right themselves.
+ *
+ * ## Where the algorithm comes from
+ *
+ * Simplex noise is Ken Perlin's, and the formulation is Stefan Gustavson and Ashima Arts' well-known
+ * GLSL one — the same skew, the same permutation polynomial and the same gradient table. It is
+ * transcribed rather than reinvented: an author who has seen simplex noise in a shader should get
+ * the noise they expect, and a hash or a skew of my own would be a different function wearing the
+ * same name.
+ *
+ * One thing is deliberately *not* transcribed. The GLSL normalises each corner's gradient with
+ * `taylorInvSqrt` — a straight line through the band the gradient table's squared lengths fall in,
+ * because a reciprocal square root was worth avoiding where that shader was written. This VM has
+ * `NORMALIZE` as one instruction, and it is exact. So the gradients here are normalised properly,
+ * which is four instructions fewer per corner and a field that differs from the GLSL's by that
+ * approximation's error — a fraction of a percent, in the direction of the noise the formulation
+ * describes rather than away from it. Everything that decides the *shape* of the field, which is to
+ * say which simplex a point falls in and which gradient each corner is handed, is transcribed
+ * exactly.
+ *
+ * ## Why it is written the way it is
+ *
+ * The shader version keeps four corners in flight at once — four offsets, four gradients, four
+ * weights — as `vec4`s across corners. Done that way here it needs upwards of forty-five registers,
+ * and the fast interpreter's register file is its single largest cost (see
+ * {@link ../../ParticleConstants.js PARTICLE_VM_FAST_REGISTER_SLOTS}). So the corners are summed one
+ * at a time instead: each corner's offset, gradient and weight are computed, folded into a running
+ * total, and dropped. The result is identical and the high-water mark is far lower, which is the
+ * difference between a node that runs on the fast interpreter and one that drags the whole system
+ * onto the wide one.
+ *
+ * The permutation itself stays a `vec4` — it is one hash of four corners at once and splitting it
+ * would quadruple the work rather than move it.
+ */
+
+/** Skew factor for the 3-simplex lattice: `1/3`. @type {number} */
+const F3 = 1 / 3;
+
+/** Unskew factor for the 3-simplex lattice: `1/6`. @type {number} */
+const G3 = 1 / 6;
+
+/** Skew factor for the 4-simplex lattice: `(sqrt(5) - 1) / 4`. @type {number} */
+const F4 = 0.309016994374947451;
+
+/** Unskew factor for the 4-simplex lattice: `(5 - sqrt(5)) / 20`. @type {number} */
+const G4 = 0.138196601125011;
+
+/**
+ * `x mod 289`, without a modulo opcode: `x - floor(x / 289) * 289`.
+ *
+ * 289 is 17 squared, and the permutation polynomial below is built so that its results stay inside
+ * `[0, 289)` — which is what keeps the whole hash inside the range a float represents exactly.
+ *
+ * A multiply-add would spell the tail of this in one instruction rather than two, and it is not used:
+ * a `MAD` holds three operands at once where the multiply and the subtract hold two each, and the
+ * third is a four-lane literal. Measured, that is four instructions off `simplex3` and four registers
+ * onto it — the wrong side of the trade, for the reason the note at the top of this file gives.
+ *
+ * @param {ParticleGroupBuilder} g
+ * @param {*} x
+ * @returns {*}
+ */
+function mod289(g, x) {
+    return g.sub(x, g.mul(g.floor(g.mul(x, g.f(1 / 289))), g.f(289)));
+}
+
+/**
+ * The permutation polynomial: `(34x + 1) x mod 289`.
+ *
+ * A hash chosen so that composing it over the lattice coordinates spreads corners across the
+ * gradient table without a lookup — there are no tables in this VM to look one up in.
+ *
+ * @param {ParticleGroupBuilder} g
+ * @param {*} x
+ * @returns {*}
+ */
+function permute(g, x) {
+    // `(34x + 1)x` written as `34x*x + x`, which is the same number and costs four fewer registers.
+    //
+    // A constant meeting a vector has to be broadcast into as many registers as the vector is wide,
+    // unless the operation is a multiply — a scalar times a vector lowers to SCALE, which reads its
+    // scalar as one lane. Written the obvious way, the `+ 1` is a four-register constant alive at the
+    // busiest moment of the function. Written this way there is no additive constant at all, and the
+    // `34` is a SCALE operand. See the note about the register file at the top of this file.
+    return mod289(g, g.mad(g.mul(x, g.f(34)), x, x));
+}
+
+/**
+ * One corner's contribution to a simplex sum: `max(0.6 - |x|^2, 0)^4 * dot(gradient, x)`.
+ *
+ * The fourth power of a radial falloff that reaches zero at the edge of a corner's influence, which
+ * is what makes the sum continuous and its derivative continuous with it.
+ *
+ * @param {ParticleGroupBuilder} g
+ * @param {*} offset the vector from the corner to the point
+ * @param {*} gradient the corner's gradient, already normalised
+ * @returns {*} a scalar
+ */
+function corner_contribution(g, offset, gradient) {
+    // `saturate` rather than `max(_, 0)`: the falloff is 0.6 less a squared length, so it can never
+    // reach the upper bound and the two are the same function. One instruction with its bounds in
+    // the instruction word, against a literal zero in a register and a `MAX` to compare it with.
+    const t = g.saturate(g.sub(g.f(0.6), g.dot(offset, offset)));
+
+    const t2 = g.mul(t, t);
+
+    return g.mul(g.mul(t2, t2), g.dot(gradient, offset));
+}
+
+/**
+ * The 3D gradient for one corner, from its hashed index.
+ *
+ * The table is the 7x7 grid of points on the faces of an octahedron that Gustavson's formulation
+ * uses: the index is split into a row and a column, those become two coordinates, the third is
+ * whatever is left of the L1 norm, and the sign of that third one flips the first two. Every step is
+ * arithmetic, because there is nowhere to put a table.
+ *
+ * @param {ParticleGroupBuilder} g
+ * @param {*} index a hashed corner index, in `[0, 289)`
+ * @returns {*} a `vec3` gradient, not yet normalised
+ */
+function grad3(g, index) {
+    const N = 1 / 7;
+
+    const ns_x = N * 2;
+    const ns_y = N * 0.5 - 1;
+    const ns_z = N;
+
+    // j = index mod 49, the 7x7 grid
+    const j = g.sub(index, g.mul(g.f(49), g.floor(g.mul(index, g.f(ns_z * ns_z)))));
+
+    const row = g.floor(g.mul(j, g.f(ns_z)));
+    const col = g.floor(g.sub(j, g.mul(g.f(7), row)));
+
+    const gx = g.mad(row, g.f(ns_x), g.f(ns_y));
+    const gy = g.mad(col, g.f(ns_x), g.f(ns_y));
+
+    // what is left of the unit L1 ball is the third coordinate
+    const gz = g.sub(g.sub(1, g.abs(gx)), g.abs(gy));
+
+    // Outside the ball the point belongs to the opposite face: reflect the first two coordinates.
+    // At or below zero, not below — the coordinates land on a seventh and the boundary is reachable
+    // exactly, so which side it falls on is a decision rather than a rounding accident.
+    // Negated once and shared, so that each reflection is a single multiply-add — `c - k*outside`
+    // written as `k*(-outside) + c`. Both halves want it, which is what pays for the negate.
+    const inside = g.neg(g.op("compare", [gz, 0], { op: "le" }));
+
+    return g.vec3(
+        g.mad(g.mad(g.floor(gx), 2, 1), inside, gx),
+        g.mad(g.mad(g.floor(gy), 2, 1), inside, gy),
+        gz
+    );
+}
+
+/**
+ * Simplex noise over three dimensions, in roughly `[-1, 1]`.
+ *
+ * @param {ParticleGroupBuilder} g
+ * @param {*} v a `vec3` position
+ * @returns {*} a scalar
+ */
+function simplex3(g, v) {
+    // Which cell of the skewed lattice the point is in, and where it sits inside it.
+    const cell = g.floor(g.add(v, g.dot(v, g.f(F3))));
+    const x0 = g.add(g.sub(v, cell), g.dot(cell, g.f(G3)));
+
+    // The simplex a point falls in is decided by the order of its coordinates: the two steps from
+    // the cell's corner to the point's own are the two largest axes, in order.
+    const order = g.step(g.swz(x0, "yzx"), x0);
+    const rest = g.sub(g.f(1), order);
+
+    const step1 = g.min(order, g.swz(rest, "zxy"));
+    const step2 = g.max(order, g.swz(rest, "zxy"));
+
+    const cell289 = mod289(g, cell);
+
+    // One hash of all four corners at once. Each `permute` folds in one lattice axis.
+    const corners = g.vec4(g.f(0), g.z(step1), g.z(step2), g.f(1));
+
+    let hashed = permute(g, g.add(g.z(cell289), corners));
+
+    hashed = permute(g, g.add(g.add(hashed, g.y(cell289)),
+        g.vec4(g.f(0), g.y(step1), g.y(step2), g.f(1))));
+
+    hashed = permute(g, g.add(g.add(hashed, g.x(cell289)),
+        g.vec4(g.f(0), g.x(step1), g.x(step2), g.f(1))));
+
+    // Corner by corner, so that one corner's working set is all that is ever live at once.
+    const offsets = [
+        x0,
+        g.add(g.sub(x0, step1), g.f(G3)),
+        g.add(g.sub(x0, step2), g.f(G3 * 2)),
+        g.sub(x0, g.f(0.5)),
+    ];
+
+    let total = null;
+
+    ["x", "y", "z", "w"].forEach((lane, corner) => {
+        const gradient = grad3(g, g.swz(hashed, lane));
+
+        const contribution = corner_contribution(g, offsets[corner], g.normalize(gradient));
+
+        total = total === null ? contribution : g.add(total, contribution);
+    });
+
+    // scales the sum to about [-1, 1]
+    return g.mul(g.f(42), total);
+}
+
+/**
+ * The 4D gradient for one corner, from its hashed index.
+ *
+ * The table this time is the 32 vertices of a hypercube's cell centres, reached the same way: three
+ * coordinates from base-7 digits of the index, the fourth from what is left of the L1 norm, and its
+ * sign flipping the other three.
+ *
+ * @param {ParticleGroupBuilder} g
+ * @param {*} index
+ * @returns {*} a `vec4` gradient, not yet normalised
+ */
+function grad4(g, index) {
+    // 1/294, 1/49, 1/7: successive base-7 digits of the index
+    const digits = g.mul(g.f(1 / 294, 1 / 49, 1 / 7), index);
+
+    const xyz = g.mad(g.floor(g.mul(g.fract(digits), g.f(7))), g.f(1 / 7), g.f(-1));
+
+    const w = g.sub(g.f(1.5), g.dot(g.abs(xyz), g.f(1)));
+
+    const negative = g.op("compare", [w, 0], { op: "lt" });
+
+    // `2c - 1` over a comparison's 0-or-1: -1 where the coordinate is negative, +1 where it is not
+    const sign = g.mad(g.op("compare", [xyz, g.f(0)], { op: "lt" }), g.f(2), g.f(-1));
+
+    const flipped = g.mad(sign, negative, xyz);
+
+    return g.vec4(g.x(flipped), g.y(flipped), g.z(flipped), w);
+}
+
+/**
+ * Simplex noise over four dimensions, in roughly `[-1, 1]`.
+ *
+ * The fourth dimension is what a moving noise field is made of: hold three of them at a position and
+ * walk the fourth with time, and the field changes rather than sliding past.
+ *
+ * @param {ParticleGroupBuilder} g
+ * @param {*} v a `vec4` position
+ * @returns {*} a scalar
+ */
+function simplex4(g, v) {
+    const cell = g.floor(g.add(v, g.dot(v, g.f(F4))));
+    const x0 = g.add(g.sub(v, cell), g.dot(cell, g.f(G4)));
+
+    // The rank of each coordinate among the four, by comparing every pair once. A coordinate's rank
+    // is how many of the others it is at least as large as, and the ranks are the order the four
+    // steps from the cell's corner are taken in.
+    const isX = g.step(g.swz(x0, "yzw"), g.swz(x0, "xxx"));
+    const isYZ = g.step(g.swz(x0, "zww"), g.swz(x0, "yyz"));
+
+    const one_minus = ref => g.sub(g.f(1), ref);
+
+    // Three comparison results summed, which is a dot product against ones — one instruction and one
+    // literal, rather than two adds and three lanes picked out one at a time. The others mix a
+    // comparison with its complement and have nothing so tidy to become.
+    const rank_x = g.dot(isX, g.f(1));
+    const rank_y = g.add(one_minus(g.x(isX)), g.add(g.x(isYZ), g.y(isYZ)));
+    const rank_z = g.add(one_minus(g.y(isX)), g.add(one_minus(g.x(isYZ)), g.z(isYZ)));
+    const rank_w = g.add(one_minus(g.z(isX)), g.add(one_minus(g.y(isYZ)), one_minus(g.z(isYZ))));
+
+    const rank = g.vec4(rank_x, rank_y, rank_z, rank_w);
+
+    // A rank is a whole number in 0..3, and the three steps from the cell's corner are the
+    // coordinates whose rank has been passed: the first step takes rank 3, the second 3 and 2, the
+    // third all but rank 0. `saturate(rank - k)` is all three of those. `rank - k` never leaves
+    // `[-3, 3]`, so clamping to `[0, 1]` is the same function as the one-sided `max` or `min` each of
+    // them would otherwise need — and it is one instruction that holds its bounds in the instruction
+    // word. This was `min` and `max` precisely to keep two broadcast literals from being alive at the
+    // same moment; `saturate` has no literals to be alive, so the reason is gone along with the cost.
+    const step_taken = value => g.saturate(value);
+
+    // The permutation needs one lane of each of the three steps at a time, so it takes them off the
+    // ranks directly rather than off three assembled vectors. Those vectors are twelve registers,
+    // and holding them through the permutation — the busiest part of the function — is what put this
+    // over the register file. Built this way the ranks are all that has to survive it, and the
+    // vectors are assembled afterwards for the corner offsets, by which point the hash is done.
+    const steps_of = axis => {
+        const r = g.swz(rank, axis);
+
+        return g.vec4(
+            step_taken(g.sub(r, g.f(2))),
+            step_taken(g.sub(r, g.f(1))),
+            step_taken(r),
+            g.f(1)
+        );
+    };
+
+    const cell289 = mod289(g, cell);
+
+    // The corner at the cell's own origin hashes on its own; the other four hash together.
+    let origin = permute(g, g.w(cell289));
+
+    origin = permute(g, g.add(origin, g.z(cell289)));
+    origin = permute(g, g.add(origin, g.y(cell289)));
+    origin = permute(g, g.add(origin, g.x(cell289)));
+
+    let hashed = permute(g, g.add(g.w(cell289), steps_of("w")));
+
+    hashed = permute(g, g.add(g.add(hashed, g.z(cell289)), steps_of("z")));
+    hashed = permute(g, g.add(g.add(hashed, g.y(cell289)), steps_of("y")));
+    hashed = permute(g, g.add(g.add(hashed, g.x(cell289)), steps_of("x")));
+
+    const step3 = step_taken(rank);
+    const step2 = step_taken(g.sub(rank, g.f(1)));
+    const step1 = step_taken(g.sub(rank, g.f(2)));
+
+    // Each of these is one value read once, so only one of them is ever live however they are
+    // written down — the order the compiler emits in comes from the graph rather than from the order
+    // they were built in. See the note about corners at the top of this file for the part that *is*
+    // a register decision.
+    const offsets = [
+        x0,
+        g.add(g.sub(x0, step1), g.f(G4)),
+        g.add(g.sub(x0, step2), g.f(G4 * 2)),
+        g.add(g.sub(x0, step3), g.f(G4 * 3)),
+        g.add(x0, g.f(G4 * 4 - 1)),
+    ];
+
+    const indices = [origin, g.x(hashed), g.y(hashed), g.z(hashed), g.w(hashed)];
+
+    let total = null;
+
+    for (let corner = 0; corner < 5; corner++) {
+        const gradient = grad4(g, indices[corner]);
+
+        const contribution = corner_contribution(g, offsets[corner], g.normalize(gradient));
+
+        total = total === null ? contribution : g.add(total, contribution);
+    }
+
+    return g.mul(g.f(49), total);
+}
+
+/**
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_SIMPLEX_3 = (() => {
+    const g = new ParticleGroupBuilder({
+        name: "simplex3",
+        label: "Simplex Noise 3D",
+        icon: "M12 3l8 4.5v9L12 21l-8-4.5v-9z M12 3v18 M4 7.5l16 9 M20 7.5l-16 9",
+        help: "simplex noise at a point in space, about [-1, 1]",
+        inputs: [{ name: "p", type: PARTICLE_TYPE_VEC3 }],
+        outputs: [{ name: "out", type: PARTICLE_TYPE_F32 }],
+    });
+
+    g.out("out", simplex3(g, g.in.p));
+
+    return g.build();
+})();
+
+/**
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_SIMPLEX_4 = (() => {
+    const g = new ParticleGroupBuilder({
+        name: "simplex4",
+        label: "Simplex Noise 4D",
+        icon: "M12 3l8 4.5v9L12 21l-8-4.5v-9z M12 3v18 M4 7.5l16 9 M20 7.5l-16 9 M4 7.5l16 0",
+        help: "simplex noise at a point in space and time, about [-1, 1]",
+        inputs: [{ name: "p", type: PARTICLE_TYPE_VEC4 }],
+        outputs: [{ name: "out", type: PARTICLE_TYPE_F32 }],
+    });
+
+    g.out("out", simplex4(g, g.in.p));
+
+    return g.build();
+})();
+
+/**
+ * How far apart the samples taken either side of a point are, when differencing the potential.
+ *
+ * Small enough that the difference is a derivative and large enough that it is not two samples of
+ * the same value: simplex noise varies over a unit cell, and a tenth of one is a reasonable step in
+ * single precision.
+ *
+ * @type {number}
+ */
+const CURL_EPSILON = 0.1;
+
+/**
+ * Offsets that turn one noise field into three independent ones.
+ *
+ * A curl needs a vector potential, and there is one noise function. Sampling it at three points far
+ * enough apart that the values are uncorrelated is the standard way to get three fields out of it —
+ * the numbers are arbitrary and only have to be large and unalike.
+ *
+ * @type {number[][]}
+ */
+const CURL_FIELD_OFFSETS = [
+    [0, 0, 0],
+    [31.416, 47.853, 12.793],
+    [83.147, 19.264, 65.037],
+];
+
+/**
+ * The curl of a noise field, as a vector.
+ *
+ * A curl is divergence-free — nothing anywhere is a source or a sink — which is what makes it look
+ * like a fluid rather than like noise. Particles advected by one swirl and never pile up, and that
+ * is the whole reason to spend this many instructions on it.
+ *
+ * ## What it costs
+ *
+ * Twelve noise samples. The curl of a three-component potential needs six partial derivatives, each
+ * a difference of two samples, and no two of them are of the same field at the same place. There is
+ * no loop to put them in and no way to share them, so the group is twelve copies of the noise and
+ * the arithmetic between them — well over a thousand instructions, and worth knowing before it is
+ * put in an UPDATE graph that runs on every particle every frame.
+ *
+ * @param {ParticleGroupBuilder} g
+ * @param {function(ParticleGroupBuilder, number, number, number, number): *} sample
+ *        the potential's `field`th component at `p + (dx, dy, dz)`, as a scalar
+ * @returns {*} a `vec3`
+ */
+function curl_of(g, sample) {
+    const e = CURL_EPSILON;
+
+    /**
+     * The centred difference of one field along one axis, *not* divided by the step — every one of
+     * the six is over the same step, so the division comes out of the sum at the end as a single
+     * scale rather than six multiplies.
+     *
+     * @param {number} field
+     * @param {number} axis 0, 1 or 2
+     * @returns {*}
+     */
+    const difference = (field, axis) => {
+        const step = [0, 0, 0];
+
+        step[axis] = e;
+
+        const ahead = sample(g, field, step[0], step[1], step[2]);
+        const behind = sample(g, field, -step[0], -step[1], -step[2]);
+
+        return g.sub(ahead, behind);
+    };
+
+    const curl = g.vec3(
+        g.sub(difference(2, 1), difference(1, 2)),
+        g.sub(difference(0, 2), difference(2, 0)),
+        g.sub(difference(1, 0), difference(0, 1))
+    );
+
+    return g.scale(curl, g.f(1 / (2 * e)));
+}
+
+/**
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_CURL_3 = (() => {
+    const g = new ParticleGroupBuilder({
+        name: "curl3",
+        label: "Curl Noise 3D",
+        icon: "M6 15c0-5 5-8 8-5s0 8-3 6-1-6 3-6",
+        help: "a divergence-free swirl field — twelve noise samples, so not cheap",
+        inputs: [{ name: "p", type: PARTICLE_TYPE_VEC3 }],
+        outputs: [{ name: "out", type: PARTICLE_TYPE_VEC3 }],
+    });
+
+    g.out("out", curl_of(g, (builder, field, dx, dy, dz) => {
+        const offset = CURL_FIELD_OFFSETS[field];
+
+        const at = builder.add(builder.in.p, builder.f(offset[0] + dx, offset[1] + dy, offset[2] + dz));
+
+        return builder.call(PARTICLE_GROUP_SIMPLEX_3, { p: at }).out;
+    }));
+
+    return g.build();
+})();
+
+/**
+ * The same field, with a fourth coordinate to move it through.
+ *
+ * Advance `w` with time and the swirl evolves in place instead of drifting past — which is what
+ * separates smoke from a conveyor belt of smoke.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_CURL_4 = (() => {
+    const g = new ParticleGroupBuilder({
+        name: "curl4",
+        label: "Curl Noise 4D",
+        icon: "M6 15c0-5 5-8 8-5s0 8-3 6-1-6 3-6 M18 5v4 M16 7h4",
+        help: "a curl field that evolves along w — twelve 4D noise samples, so expensive",
+        inputs: [
+            { name: "p", type: PARTICLE_TYPE_VEC3 },
+            { name: "w", type: PARTICLE_TYPE_F32 },
+        ],
+        outputs: [{ name: "out", type: PARTICLE_TYPE_VEC3 }],
+    });
+
+    g.out("out", curl_of(g, (builder, field, dx, dy, dz) => {
+        const offset = CURL_FIELD_OFFSETS[field];
+
+        const at = builder.vec4(
+            builder.add(builder.x(builder.in.p), builder.f(offset[0] + dx)),
+            builder.add(builder.y(builder.in.p), builder.f(offset[1] + dy)),
+            builder.add(builder.z(builder.in.p), builder.f(offset[2] + dz)),
+            builder.in.w
+        );
+
+        return builder.call(PARTICLE_GROUP_SIMPLEX_4, { p: at }).out;
+    }));
+
+    return g.build();
+})();