@woosh/meep-engine 3.15.0 → 3.17.0

package/editor/view/particles/effect/ParticleNodeParametersView.d.ts

@@ -0,0 +1,22 @@
+export class ParticleNodeParametersView extends View {
+    /**
+     * @param {object} options
+     * @param {import("../../../particles/effect/ParticleEffectDocument.js").ParticleEffectDocument} options.effect
+     *        the effect document being edited; read for the attribute list, and watched for changes to it
+     * @param {NodeInstance} options.node
+     * @param {function(string, *)} options.commit called with a parameter name and its new value
+     */
+    constructor({ effect, node, commit }: {
+        effect: import("../../../particles/effect/ParticleEffectDocument.js").ParticleEffectDocument;
+        node: NodeInstance;
+        commit: (arg0: string, arg1: any) => any;
+    });
+    el: HTMLDivElement;
+    /**
+     * @type {NodeInstance}
+     */
+    node: NodeInstance;
+    #private;
+}
+import View from "../../../../src/view/View.js";
+//# sourceMappingURL=ParticleNodeParametersView.d.ts.map

package/editor/view/particles/effect/ParticleNodeParametersView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleNodeParametersView.d.ts","sourceRoot":"","sources":["../../../../../editor/view/particles/effect/ParticleNodeParametersView.js"],"names":[],"mappings":"AAqCA;IAOI;;;;;;OAMG;IACH;QALyG,MAAM,EAApG,OAAO,qDAAqD,EAAE,sBAAsB;QAE9D,IAAI;QACG,MAAM,SAA1B,MAAM;OA6BzB;IAxBG,mBAAuC;IAIvC;;OAEG;IACH,mBAAgB;;CA0cvB;iBAlgBgB,8BAA8B"}

package/editor/view/particles/effect/ParticleNodeParametersView.js

@@ -0,0 +1,553 @@
+import { clamp01 } from "../../../../src/core/math/clamp01.js";
+import { hex_to_rgb } from "../../../../src/core/color/hex/hex_to_rgb.js";
+import { rgb_to_hex } from "../../../../src/core/color/hex/rgb_to_hex.js";
+import LabelView from "../../../../src/view/common/LabelView.js";
+import EmptyView from "../../../../src/view/elements/EmptyView.js";
+import View from "../../../../src/view/View.js";
+import {
+    PARTICLE_PARAMETER_KIND,
+    PARTICLE_WIDTH_OPTIONS,
+    particle_node_parameters,
+} from "../../../../src/shade/renderer/particles/graph/particle_node_parameters.js";
+import { ParticleCurveEditorView } from "./ParticleCurveEditorView.js";
+import { ParticleGradientEditorView } from "./ParticleGradientEditorView.js";
+
+/**
+ * The controls for one particle node's static parameters, drawn inside the node.
+ *
+ * This is what the node-graph base's `parameterViewFactory` seam exists for. A particle node's
+ * parameters are name-keyed and hold vectors, ISA enum members, swizzle patterns and references to
+ * the effect's own attributes — none of which the generic number/string/boolean mechanism can
+ * describe. The schema in `particle_node_parameters.js` says what each one is; this turns that into
+ * a control, and commits through the callback the base supplies, so every edit lands on the
+ * editor's action timeline exactly as a built-in control's would.
+ *
+ * Two things flow the other way, and both matter:
+ *
+ * - a parameter changed on the node — an undo, most of all — is written back into the control,
+ * - the effect's attribute list changing rebuilds the attribute pickers, so a node's choices are
+ *   the attributes the effect has now rather than the ones it had when the node was drawn.
+ *
+ * A swizzle is spelled the way the assembly spells it (`xyzw`), so the two layers of the editor
+ * name the same thing the same way.
+ */
+
+/** Lane selector characters, in selector order. @type {string} */
+const SWIZZLE_LANES = "xyzw";
+
+export class ParticleNodeParametersView extends View {
+    /**
+     * Per-parameter writers that push a model value into the control, keyed by parameter name.
+     * @type {Map<string, function(*):void>}
+     */
+    #writers = new Map();
+
+    /**
+     * @param {object} options
+     * @param {import("../../../particles/effect/ParticleEffectDocument.js").ParticleEffectDocument} options.effect
+     *        the effect document being edited; read for the attribute list, and watched for changes to it
+     * @param {NodeInstance} options.node
+     * @param {function(string, *)} options.commit called with a parameter name and its new value
+     */
+    constructor({ effect, node, commit }) {
+        super();
+
+        this.el = document.createElement('div');
+
+        this.addClass('ui-particle-node-parameters');
+
+        /**
+         * @type {NodeInstance}
+         */
+        this.node = node;
+
+        const parameters = particle_node_parameters(node.description.name);
+
+        for (const parameter of parameters) {
+            this.addChild(this.#buildRow(effect, parameter, commit));
+        }
+
+        // an edit made anywhere else — an undo, the code layer, a script — is still an edit to this
+        // node, and the control has to show it
+        this.bindSignal(node.on.parameterChanged, (name, value) => {
+            const writer = this.#writers.get(String(name));
+
+            if (writer !== undefined) {
+                writer(value);
+            }
+        });
+    }
+
+    /**
+     * @param {import("../../../particles/effect/ParticleEffectDocument.js").ParticleEffectDocument} effect
+     * @param {import("../../../../src/shade/renderer/particles/graph/particle_node_parameters.js").ParticleNodeParameter} parameter
+     * @param {function(string, *)} commit
+     * @returns {View}
+     */
+    #buildRow(effect, parameter, commit) {
+        const row = new EmptyView({ classList: ['parameter-row', `kind-${parameter.kind}`] });
+
+        row.addChild(new LabelView(parameter.name, { classList: ['name'] }));
+
+        if (typeof parameter.description === "string") {
+            row.el.setAttribute('title', parameter.description);
+        }
+
+        const node = this.node;
+        const value = () => node.getParameterValue(parameter.name);
+        const write = next => commit(parameter.name, next);
+
+        let control;
+
+        switch (parameter.kind) {
+            case PARTICLE_PARAMETER_KIND.VECTOR:
+                control = this.#buildVectorControl(parameter, value, write);
+                break;
+
+            case PARTICLE_PARAMETER_KIND.COLOR:
+                control = this.#buildColorControl(parameter, value, write);
+                break;
+
+            case PARTICLE_PARAMETER_KIND.SWIZZLE:
+                control = this.#buildSwizzleControl(parameter, value, write);
+                break;
+
+            case PARTICLE_PARAMETER_KIND.ENUM:
+                control = this.#buildSelectControl(
+                    parameter,
+                    () => Object.entries(parameter.options).map(([label, option]) => ({ label, value: option })),
+                    value,
+                    write
+                );
+                break;
+
+            case PARTICLE_PARAMETER_KIND.ATTRIBUTE:
+                control = this.#buildSelectControl(
+                    parameter,
+                    () => effect.attributes.map(attribute => ({
+                        label: `${attribute.name} (${attribute.components})`,
+                        value: attribute.name,
+                    })),
+                    value,
+                    write
+                );
+
+                // the effect's attributes are the choices, so they are re-read when they change
+                row.bindSignal(effect.on.changed, () => control.refresh());
+                break;
+
+            case PARTICLE_PARAMETER_KIND.INTEGER:
+                control = this.#buildIntegerControl(parameter, value, write);
+                break;
+
+            case PARTICLE_PARAMETER_KIND.CURVE:
+                control = editor_control(new ParticleCurveEditorView({ read: value, write }));
+                break;
+
+            case PARTICLE_PARAMETER_KIND.GRADIENT:
+                control = editor_control(
+                    new ParticleGradientEditorView({ read: value, write, alpha: parameter.alpha !== false })
+                );
+                break;
+
+            default:
+                throw new Error(
+                    `Particle parameter '${parameter.name}' has kind '${parameter.kind}', which has no control.`
+                );
+        }
+
+        this.#writers.set(parameter.name, control.write);
+
+        row.addChild(control.view);
+
+        return row;
+    }
+
+    /**
+     * A width picker and one number field per lane. How many numbers the literal holds is its type
+     * — one is a scalar, three a `vec3` — so the picker is the type control: widening pads with
+     * zeros, narrowing drops the lanes past the new width.
+     *
+     * Committed on `change` — when the field is left or Enter is pressed — so a half-typed number
+     * is never a value, and the timeline gets one entry per edit rather than one per keystroke.
+     *
+     * @param {object} parameter
+     * @param {function():number[]} read
+     * @param {function(number[])} write
+     * @returns {{view: View, write: function(*):void, refresh: function():void}}
+     */
+    #buildVectorControl(parameter, read, write) {
+        const view = new EmptyView({ classList: ['vector'] });
+
+        const width = document.createElement('select');
+
+        width.classList.add('ui-particle-parameter-select', 'width');
+
+        for (const [label, components] of Object.entries(PARTICLE_WIDTH_OPTIONS)) {
+            const option = document.createElement('option');
+
+            option.value = String(components);
+            option.textContent = label;
+
+            width.appendChild(option);
+        }
+
+        view.el.appendChild(width);
+
+        const lanes = new EmptyView({ classList: ['lanes'] });
+
+        view.addChild(lanes);
+
+        /** @type {HTMLInputElement[]} */
+        const fields = [];
+
+        const current = () => {
+            const value = read();
+
+            return Array.isArray(value) && value.length > 0 ? value : [0];
+        };
+
+        /**
+         * One field per lane of the value, rebuilt only when the lane count changes so an edit in
+         * one lane does not throw away the focus in another.
+         * @param {number} count
+         */
+        const ensure_fields = count => {
+            while (fields.length > count) {
+                fields.pop().remove();
+            }
+
+            while (fields.length < count) {
+                const lane = fields.length;
+                const field = create_input('number');
+
+                field.classList.add('lane');
+                field.setAttribute('step', 'any');
+
+                field.addEventListener('change', () => {
+                    const next = current().slice();
+                    const parsed = Number.parseFloat(field.value);
+
+                    next[lane] = Number.isFinite(parsed) ? parsed : 0;
+
+                    write(next);
+                });
+
+                fields.push(field);
+
+                lanes.el.appendChild(field);
+            }
+        };
+
+        width.addEventListener('change', () => {
+            const components = Number.parseInt(width.value, 10);
+            const value = current();
+            const next = [];
+
+            for (let lane = 0; lane < components; lane++) {
+                next.push(value[lane] ?? 0);
+            }
+
+            write(next);
+        });
+
+        const push = value => {
+            const components = Array.isArray(value) && value.length > 0 ? value : [0];
+
+            ensure_fields(components.length);
+
+            width.value = String(components.length);
+
+            fields.forEach((field, lane) => {
+                field.value = String(components[lane] ?? 0);
+            });
+        };
+
+        push(read());
+
+        return { view, write: push, refresh: () => push(read()) };
+    }
+
+    /**
+     * A swatch and an alpha field — the whole reason a colour is a type of its own rather than four
+     * numbers that happen to be four.
+     *
+     * The two halves are edited apart on purpose. A swatch works in bytes, so committing what it
+     * holds would quantise the value: an author who typed `0.55` and then nudged the alpha would
+     * find their red had become `0.549`. Each control therefore replaces only its own lanes and
+     * takes the rest from the model, so editing one never disturbs the other.
+     *
+     * A channel above 1 — an emissive colour meant to bloom — shows as clipped, and picking from
+     * the swatch replaces it with what the swatch can express. That is the honest reading of a
+     * control that only has 0..255 to offer; anything brighter is edited as numbers, in the code
+     * layer or through a `const`, which is what that node is for.
+     *
+     * @param {object} parameter
+     * @param {function():number[]} read
+     * @param {function(number[])} write
+     * @returns {{view: View, write: function(*):void, refresh: function():void}}
+     */
+    #buildColorControl(parameter, read, write) {
+        const view = new EmptyView({ classList: ['color'] });
+
+        const swatch = create_input('color');
+        const alpha = create_input('number');
+
+        swatch.classList.add('swatch');
+
+        alpha.classList.add('alpha');
+        alpha.setAttribute('min', '0');
+        alpha.setAttribute('max', '1');
+        alpha.setAttribute('step', 'any');
+
+        view.el.appendChild(swatch);
+        view.el.appendChild(alpha);
+
+        /**
+         * The value as four numbers, whatever the parameter actually holds. A malformed colour is
+         * the validator's to report; here it is shown as the nearest colour there is, and the next
+         * edit writes four numbers back and repairs it.
+         *
+         * @returns {number[]}
+         */
+        const current = () => {
+            const value = read();
+
+            const colour = Array.isArray(value) ? value : [];
+
+            return [colour[0] ?? 0, colour[1] ?? 0, colour[2] ?? 0, colour[3] ?? 1];
+        };
+
+        swatch.addEventListener('change', () => {
+            const rgb = hex_to_rgb(swatch.value);
+
+            write([rgb.r / 255, rgb.g / 255, rgb.b / 255, current()[3]]);
+        });
+
+        alpha.addEventListener('change', () => {
+            const parsed = Number.parseFloat(alpha.value);
+
+            if (!Number.isFinite(parsed)) {
+                // nothing to commit, and the field snaps back to what the colour actually is
+                push();
+                return;
+            }
+
+            const colour = current();
+
+            write([colour[0], colour[1], colour[2], clamp01(parsed)]);
+        });
+
+        const push = () => {
+            const colour = current();
+
+            swatch.value = `#${rgb_to_hex(
+                Math.round(clamp01(colour[0]) * 255),
+                Math.round(clamp01(colour[1]) * 255),
+                Math.round(clamp01(colour[2]) * 255)
+            )}`;
+
+            alpha.value = String(colour[3]);
+        };
+
+        push();
+
+        return { view, write: push, refresh: push };
+    }
+
+    /**
+     * A lane pattern of one to four letters out of `xyzw`; its length is the result's width, so
+     * `xy` is how a `vec2` is picked out of a wider value. Anything else is refused and the field
+     * snaps back — a swizzle has no partially-valid state worth committing.
+     *
+     * @param {object} parameter
+     * @param {function():number[]} read
+     * @param {function(number[])} write
+     * @returns {{view: View, write: function(*):void, refresh: function():void}}
+     */
+    #buildSwizzleControl(parameter, read, write) {
+        const field = create_input('text');
+
+        field.classList.add('swizzle');
+        field.setAttribute('maxlength', String(SWIZZLE_LANES.length));
+        field.setAttribute('spellcheck', 'false');
+
+        const push = value => {
+            const pattern = Array.isArray(value) && value.length > 0 ? value : [0, 1, 2, 3];
+
+            field.value = pattern.map(lane => SWIZZLE_LANES.charAt(lane) || "x").join("");
+        };
+
+        field.addEventListener('change', () => {
+            const text = field.value.trim().toLowerCase();
+
+            const lanes = Array.from(text).map(character => SWIZZLE_LANES.indexOf(character));
+
+            if (lanes.length < 1 || lanes.length > SWIZZLE_LANES.length || lanes.some(lane => lane === -1)) {
+                push(read());
+                return;
+            }
+
+            write(lanes);
+        });
+
+        push(read());
+
+        return {
+            view: new EmptyView({ el: field }),
+            write: push,
+            refresh: () => push(read())
+        };
+    }
+
+    /**
+     * A picker over a set of options the caller can re-read, so a list that depends on the rest of
+     * the document stays current.
+     *
+     * @param {object} parameter
+     * @param {function():Array<{label: string, value: *}>} options
+     * @param {function():*} read
+     * @param {function(*)} write
+     * @returns {{view: View, write: function(*):void, refresh: function():void}}
+     */
+    #buildSelectControl(parameter, options, read, write) {
+        const select = document.createElement('select');
+
+        select.classList.add('ui-particle-parameter-select');
+
+        /** @type {Array<{label: string, value: *}>} */
+        let entries = [];
+
+        const push = value => {
+            const index = entries.findIndex(entry => entry.value === value);
+
+            // A stand-in from a previous write is a report of one particular value, not a choice,
+            // so it goes when the value does. One change reaches this twice — as the document's
+            // change and as the node's own parameter signal — and appending each time piles them up.
+            for (const stale of Array.from(select.querySelectorAll('option.missing'))) {
+                stale.remove();
+            }
+
+            if (index === -1) {
+                // A value with no option — an attribute that has been deleted, or a file from a
+                // build with more enum members. Shown as itself rather than silently snapped to
+                // something else, because snapping would edit the author's effect behind their back.
+                const orphan = document.createElement('option');
+
+                orphan.value = "__orphan__";
+                orphan.textContent = `${value} (missing)`;
+                orphan.classList.add('missing');
+
+                select.appendChild(orphan);
+                select.value = "__orphan__";
+
+                return;
+            }
+
+            select.value = String(index);
+        };
+
+        const refresh = () => {
+            entries = options();
+
+            select.replaceChildren();
+
+            entries.forEach((entry, index) => {
+                const option = document.createElement('option');
+
+                option.value = String(index);
+                option.textContent = entry.label;
+
+                select.appendChild(option);
+            });
+
+            push(read());
+        };
+
+        select.addEventListener('change', () => {
+            const entry = entries[Number.parseInt(select.value, 10)];
+
+            if (entry !== undefined) {
+                write(entry.value);
+            }
+        });
+
+        refresh();
+
+        return {
+            view: new EmptyView({ el: select }),
+            write: push,
+            refresh
+        };
+    }
+
+    /**
+     * @param {object} parameter
+     * @param {function():number} read
+     * @param {function(number)} write
+     * @returns {{view: View, write: function(*):void, refresh: function():void}}
+     */
+    #buildIntegerControl(parameter, read, write) {
+        const field = create_input('number');
+
+        field.classList.add('integer');
+        field.setAttribute('min', '0');
+        field.setAttribute('step', '1');
+
+        const push = value => {
+            field.value = String(value ?? 0);
+        };
+
+        field.addEventListener('change', () => {
+            const parsed = Number.parseInt(field.value, 10);
+
+            if (!Number.isInteger(parsed) || parsed < 0) {
+                push(read());
+                return;
+            }
+
+            write(parsed);
+        });
+
+        push(read());
+
+        return {
+            view: new EmptyView({ el: field }),
+            write: push,
+            refresh: () => push(read())
+        };
+    }
+}
+
+/**
+ * A control that is a view of its own, in the shape the rest of this file uses.
+ *
+ * The two ramp editors are not built out of `<input>`s the way the rest are — a gradient is a canvas
+ * with a lane of stops under it — so they arrive already made, and all that is left is to say how a
+ * value written from outside reaches them. That is by re-reading rather than by being handed the
+ * value: both hold a working copy that a drag is written into, and re-reading is what throws that
+ * copy away in favour of what the node now says. The node's parameter is already set by the time its
+ * signal arrives, so there is nothing stale to read.
+ *
+ * @param {{refresh: function():void}} editor
+ * @returns {{view: View, write: function(*):void, refresh: function():void}}
+ */
+function editor_control(editor) {
+    return {
+        view: editor,
+        write: () => editor.refresh(),
+        refresh: () => editor.refresh(),
+    };
+}
+
+/**
+ * @param {string} type
+ * @returns {HTMLInputElement}
+ */
+function create_input(type) {
+    const field = document.createElement('input');
+
+    field.setAttribute('type', type);
+
+    return field;
+}

package/editor/view/particles/effect/ParticlePreviewView.d.ts

@@ -0,0 +1,52 @@
+export class ParticlePreviewView extends View {
+    /**
+     * @param {object} options
+     * @param {import("../../../particles/effect/ParticleEffectDocument.js").ParticleEffectDocument} options.effect
+     * @param {number} [options.capacity] most particles the preview will hold at once
+     */
+    constructor({ effect, capacity }: {
+        effect: import("../../../particles/effect/ParticleEffectDocument.js").ParticleEffectDocument;
+        capacity?: number;
+    });
+    el: HTMLDivElement;
+    /**
+     * @type {import("../../../particles/effect/ParticleEffectDocument.js").ParticleEffectDocument}
+     */
+    effect: import("../../../particles/effect/ParticleEffectDocument.js").ParticleEffectDocument;
+    /**
+     * @type {ParticleReferenceSimulation}
+     */
+    simulation: ParticleReferenceSimulation;
+    /**
+     * Whether the simulation is advancing. Paused, the picture stays and the camera still works.
+     * @type {boolean}
+     */
+    running: boolean;
+    /**
+     * Give the simulation the document's current program, if it compiles.
+     *
+     * A document that does not compile leaves the simulation running whatever it had — see the class
+     * comment. `#stale` is what the overlay says so.
+     */
+    syncEffect(): void;
+    /**
+     * Drop every particle and start the effect over.
+     */
+    restart(): void;
+    /**
+     * Advance and draw one frame. Public so a headless caller — a test, a screenshot script — can
+     * drive the preview without a frame loop.
+     *
+     * @param {number} dt seconds
+     */
+    step(dt: number): void;
+    /**
+     * Paint the current state.
+     */
+    draw(): void;
+    layout(): void;
+    #private;
+}
+import View from "../../../../src/view/View.js";
+import { ParticleReferenceSimulation } from "../../../particles/effect/ParticleReferenceSimulation.js";
+//# sourceMappingURL=ParticlePreviewView.d.ts.map

package/editor/view/particles/effect/ParticlePreviewView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParticlePreviewView.d.ts","sourceRoot":"","sources":["../../../../../editor/view/particles/effect/ParticlePreviewView.js"],"names":[],"mappings":"AAoCA;IAyDI;;;;OAIG;IACH;QAHyG,MAAM,EAApG,OAAO,qDAAqD,EAAE,sBAAsB;QACnE,QAAQ,GAAzB,MAAM;OA0ChB;IArCG,mBAAuC;IAIvC;;OAEG;IACH,QAFU,OAAO,qDAAqD,EAAE,sBAAsB,CAE1E;IAEpB;;OAEG;IACH,YAFU,2BAA2B,CAEwD;IAE7F;;;OAGG;IACH,SAFU,OAAO,CAEE;IAqBvB;;;;;OAKG;IACH,mBAiBC;IAED;;OAEG;IACH,gBAEC;IA6BD;;;;;OAKG;IACH,SAFW,MAAM,QAWhB;IAED;;OAEG;IACH,aAwBC;IAqPD,eAiBC;;CACJ;iBAzfgB,8BAA8B;4CACH,0DAA0D"}