@woosh/meep-engine 3.58.0 → 3.59.0

package/editor/particles/effect/ParticleEffectDocument.js

@@ -26,17 +26,26 @@ import {
 } from "../../../src/shade/renderer/particles/isa/particle_assembly.js";
 import { PARTICLE_TYPE_COLOR } from "../../../src/shade/renderer/particles/graph/ParticleValueType.js";
 import { ParticleLayout } from "../../../src/shade/renderer/particles/layout/ParticleLayout.js";
+import {
+    PARTICLE_VM_INSTRUCTION_WORDS,
+    VM_BUILTIN_FIELD_INDEX_MASK,
+    VM_OP,
+    VM_OP_MASK,
+    VM_WIDTH_MASK,
+    VM_WIDTH_SHIFT,
+    vm_builtin_is_emitter_field,
+} from "../../../src/shade/renderer/particles/isa/ParticleVMISA.js";
 import { optimize_particle_program_vector } from "../../../src/shade/renderer/particles/optimizer/dag/optimize_particle_program_vector.js";
 import { EMITTER_RENDER_CHANNELS } from "../../../src/shade/renderer/particles/runtime/ParticleEmitter.js";
 
 /**
  * One particle effect being edited: the thing both layers of the editor point at.
  *
- * An effect is four things — the per-particle attribute schema, an INIT graph, an UPDATE graph, and
- * the emitter settings that say how the result is drawn. The graph editor edits the middle two, the
- * code editor edits what they compile to, the emitter inspector edits the last, and the preview
- * watches all of it. Putting them in one object with one change signal is what lets those be four
- * independent views rather than four copies of the same state.
+ * An effect is its field declarations — particle, emitter and global — an INIT graph, an UPDATE
+ * graph, and the emitter settings that say how the result is drawn. The graph editor edits the
+ * graphs, the code editor edits what they compile to, the emitter inspector edits the fields and the
+ * settings, and the preview watches all of it. Putting them in one object with one change signal is
+ * what lets those be four independent views rather than four copies of the same state.
  *
  * ## Which layer is in charge
  *
@@ -87,8 +96,16 @@ export const PARTICLE_EFFECT_SOURCE = Object.freeze({
  * @typedef {object} ParticleEffectCompilation
  * @property {import("../../../src/shade/renderer/particles/isa/ParticleProgram.js").ParticleProgram|null} program
  *   null when anything went wrong
- * @property {ParticleLayout|null} layout the attribute schema the program was compiled against;
- *   null when the declarations themselves are not a valid layout
+ * @property {ParticleLayout|null} layout the particle field schema the program was compiled
+ *   against; null when the declarations themselves are not a valid layout
+ * @property {ParticleLayout|null} emitter_layout the emitter field schema the program was compiled
+ *   against; null for an effect that declares no emitter fields, or whose declarations are invalid
+ * @property {Uint32Array} emitter_fields the declared values of those fields, as f32 bit patterns
+ *   laid out by `emitter_layout` — what every emitter of the effect starts from
+ * @property {ParticleLayout|null} global_layout the global fields the effect imports; null for one
+ *   that imports none
+ * @property {Uint32Array} global_fields their preview values, as f32 bit patterns laid out by
+ *   `global_layout` — what the editor's preview reads; a scene sets its own
  * @property {import("../../../src/shade/renderer/particles/isa/ParticleProgram.js").ParticleProgram|null} unoptimized
  *   what `program` was built from, before the optimizer. The same object as `program` when
  *   {@link ParticleEffectDocument#optimize} is off, so a caller wanting the comparison can always
@@ -98,6 +115,87 @@ export const PARTICLE_EFFECT_SOURCE = Object.freeze({
  *   `line` is a 1-based assembly line or 0
  */
 
+/**
+ * The empty schema a graph is checked against when the effect declares no emitter fields, or imports
+ * no global ones.
+ * @type {ParticleLayout}
+ */
+const NO_EMITTER_FIELDS = ParticleLayout.emitter([]);
+
+/**
+ * What is wrong with an assembled program's field reads against the effect's declarations.
+ *
+ * @param {import("../../../src/shade/renderer/particles/isa/ParticleProgram.js").ParticleProgram|null} program
+ * @param {ParticleLayout|null} emitter_layout
+ * @param {ParticleLayout|null} global_layout
+ * @returns {string[]}
+ */
+function assembly_field_problems(program, emitter_layout, global_layout) {
+    if (program === null) {
+        return [];
+    }
+
+    const problems = [];
+
+    for (const entry of program.global_imports) {
+        if (global_layout === null || !global_layout.has(entry.name)) {
+            problems.push(`The program imports the global field '${entry.name}', which the effect does not import.`);
+        } else if (global_layout.componentsOf(entry.name) !== entry.components) {
+            problems.push(
+                `The program imports '${entry.name}' with ${entry.components} components and the effect `
+                + `declares it with ${global_layout.componentsOf(entry.name)}.`
+            );
+        }
+    }
+
+    const block_words = emitter_layout === null ? 0 : emitter_layout.word_count;
+
+    for (const words of [program.init, program.update]) {
+        for (let k = 0; k < words.length; k += PARTICLE_VM_INSTRUCTION_WORDS) {
+            if ((words[k] & VM_OP_MASK) !== VM_OP.LOAD_BUILTIN || !vm_builtin_is_emitter_field(words[k + 1])) {
+                continue;
+            }
+
+            const offset = words[k + 1] & VM_BUILTIN_FIELD_INDEX_MASK;
+            const width = (words[k] >>> VM_WIDTH_SHIFT) & VM_WIDTH_MASK;
+
+            if (offset + width > block_words) {
+                problems.push(
+                    `A read of emitter_field:${offset} at ${width} lanes runs past the ${block_words} words `
+                    + `the effect's emitter fields take.`
+                );
+            }
+        }
+    }
+
+    return problems;
+}
+
+/**
+ * Declared field values, laid out by `layout` as f32 bit patterns.
+ *
+ * @param {ParticleLayout|null} layout
+ * @param {Array<{name: string, value: number[]}>} declarations
+ * @returns {Uint32Array}
+ */
+function field_values(layout, declarations) {
+    if (layout === null) {
+        return new Uint32Array(0);
+    }
+
+    const values = new Float32Array(layout.word_count);
+
+    for (const declaration of declarations) {
+        const field = layout.get(declaration.name);
+
+        for (let i = 0; i < field.components; i++) {
+            values[field.offset + i] = declaration.value?.[i] ?? 0;
+        }
+    }
+
+    return new Uint32Array(values.buffer);
+}
+
 export class ParticleEffectDocument {
 
     /**
@@ -106,7 +204,7 @@ export class ParticleEffectDocument {
     name = "effect";
 
     /**
-     * The per-particle attribute declarations, in the order they are packed into a record.
+     * The particle field declarations, in the order they are packed into a record.
      *
      * `type` is optional and says what the words are for rather than how many there are — see
      * {@link ../../../src/shade/renderer/particles/layout/ParticleLayout.js ParticleLayout}. It is
@@ -114,7 +212,7 @@ export class ParticleEffectDocument {
      *
      * @type {Array<{name: string, components: number, type?: string}>}
      */
-    attributes = [
+    particle_fields = [
         { name: "position", components: 3 },
         { name: "velocity", components: 3 },
         { name: "age", components: 1 },
@@ -123,6 +221,28 @@ export class ParticleEffectDocument {
         { name: "color", components: 4, type: PARTICLE_TYPE_COLOR.name },
     ];
 
+    /**
+     * The emitter field declarations, in the order they are packed into an emitter's block, each
+     * with the value an emitter of this effect starts from.
+     *
+     * An emitter field is to the emitter what a particle field is to the particle: a member the
+     * effect declares and every instance carries for itself. The program reads it; gameplay writes
+     * it, per entity, on the component.
+     *
+     * @type {Array<{name: string, components: number, type?: string, value: number[]}>}
+     */
+    emitter_fields = [];
+
+    /**
+     * The global fields the effect imports — members of the scene, shared by every effect that reads
+     * them by name — each with the value the editor's preview gives it. A scene sets the real values;
+     * the program carries only the names and widths, and is linked to the scene's layout when it is
+     * placed.
+     *
+     * @type {Array<{name: string, components: number, type?: string, value: number[]}>}
+     */
+    global_fields = [];
+
     /**
      * The node groups this document carries of its own — the ones an author made in it.
      *
@@ -174,7 +294,7 @@ export class ParticleEffectDocument {
         /** image to draw with, by URL; null draws against the default atlas, a white texel */
         texture: null,
         flipbook: [1, 1],
-        /** render channel -> attribute name; a channel absent here is not bound */
+        /** render channel -> particle field name; a channel absent here is not bound */
         render: {
             position: "position",
             size: "size",
@@ -285,6 +405,20 @@ export class ParticleEffectDocument {
      */
     #lowering = null;
 
+    /**
+     * The last {@link #emitterLayout}, against the version it was built for.
+     *
+     * @type {{version: number, layout: ParticleLayout|null}|null}
+     */
+    #emitter_layout = null;
+
+    /**
+     * The last {@link #globalLayout}, against the version it was built for.
+     *
+     * @type {{version: number, layout: ParticleLayout|null}|null}
+     */
+    #global_layout = null;
+
     constructor() {
         // A graph edited through the editor's action timeline never passes through this object, so
         // without this the document would be the last to hear about a change to its own contents —
@@ -330,7 +464,7 @@ export class ParticleEffectDocument {
     }
 
     /**
-     * Announce a change. Every edit path — a graph action, an attribute added, a parameter set,
+     * Announce a change. Every edit path — a graph action, a particle field added, a parameter set,
      * assembly typed — ends here, and every view that shows the effect is downstream of it.
      *
      * Inside a {@link batch} the announcement is held until the batch ends, and however many changes
@@ -463,16 +597,72 @@ export class ParticleEffectDocument {
     }
 
     /**
-     * The attribute schema as the compiler and the runtime want it.
+     * The particle field schema as the compiler and the runtime want it.
      *
-     * Rebuilt on demand rather than held, because {@link attributes} is what an author edits and a
-     * cached layout would be one edit behind. Building one is a walk over a handful of declarations.
+     * Rebuilt on demand rather than held, because {@link particle_fields} is what an author edits
+     * and a cached layout would be one edit behind. Building one is a walk over a handful of
+     * declarations.
      *
      * @returns {ParticleLayout}
      * @throws if the declarations are not a valid layout (duplicate name, too many words)
      */
     buildLayout() {
-        return new ParticleLayout(this.attributes);
+        return new ParticleLayout(this.particle_fields);
+    }
+
+    /**
+     * The emitter field schema, built fresh from the declarations; `null` for an effect that
+     * declares none.
+     *
+     * @returns {ParticleLayout|null}
+     * @throws if the declarations are not a valid layout (a duplicate name)
+     */
+    buildEmitterLayout() {
+        if (this.emitter_fields.length === 0) {
+            return null;
+        }
+
+        return ParticleLayout.emitter(this.emitter_fields.map(({ name, components, type }) => (
+            type === undefined ? { name, components } : { name, components, type }
+        )));
+    }
+
+    /**
+     * The global fields the effect imports, laid out for the preview; `null` for an effect that
+     * imports none. Only the names, widths and tags reach the program — the offsets here are the
+     * preview's, never a scene's.
+     *
+     * @returns {ParticleLayout|null}
+     * @throws if the declarations are not a valid layout (a duplicate name)
+     */
+    buildGlobalLayout() {
+        if (this.global_fields.length === 0) {
+            return null;
+        }
+
+        return ParticleLayout.emitter(this.global_fields.map(({ name, components, type }) => (
+            type === undefined ? { name, components } : { name, components, type }
+        )));
+    }
+
+    /**
+     * The declared values of the emitter fields, laid out by `layout` as f32 bit patterns.
+     *
+     * @param {ParticleLayout|null} layout what {@link buildEmitterLayout} built
+     * @returns {Uint32Array}
+     */
+    emitterFieldValues(layout) {
+        return field_values(layout, this.emitter_fields);
+    }
+
+    /**
+     * The preview values of the global fields, laid out by `layout` as f32 bit patterns.
+     *
+     * @param {ParticleLayout|null} layout what {@link buildGlobalLayout} built
+     * @returns {Uint32Array}
+     */
+    globalFieldValues(layout) {
+        return field_values(layout, this.global_fields);
     }
 
     /**
@@ -510,18 +700,30 @@ export class ParticleEffectDocument {
         const diagnostics = [];
 
         let layout;
+        let emitter_layout;
+        let global_layout;
 
         try {
             layout = this.#layout();
+            emitter_layout = this.#emitterLayout();
+            global_layout = this.#globalLayout();
         } catch (e) {
             return {
                 program: null,
                 unoptimized: null,
                 layout: null,
+                emitter_layout: null,
+                emitter_fields: new Uint32Array(0),
+                global_layout: null,
+                global_fields: new Uint32Array(0),
                 diagnostics: [{ scope: "effect", node: -1, line: 0, message: e.message, severity: PARTICLE_GRAPH_ERROR }],
             };
         }
 
+        const emitter_fields = this.emitterFieldValues(emitter_layout);
+        const global_fields = this.globalFieldValues(global_layout);
+        const fields = { layout, emitter_layout, emitter_fields, global_layout, global_fields };
+
         if (this.source === PARTICLE_EFFECT_SOURCE.ASSEMBLY) {
             const { program, diagnostics: assembly_diagnostics } = parse_particle_assembly(this.assembly);
 
@@ -535,14 +737,25 @@ export class ParticleEffectDocument {
                 });
             }
 
-            return { ...this.#optimized(program, diagnostics), layout, diagnostics };
+            // What the validator checks a graph for, text is checked for here: an import the effect
+            // does not declare, or declares at another width, and an emitter field read past the
+            // block, which reads a neighbouring emitter's fields.
+            for (const message of assembly_field_problems(program, emitter_layout, global_layout)) {
+                diagnostics.push({ scope: "assembly", node: -1, line: 0, message, severity: PARTICLE_GRAPH_ERROR });
+            }
+
+            if (diagnostics.length > 0) {
+                return { program: null, unoptimized: null, ...fields, diagnostics };
+            }
+
+            return { ...this.#optimized(program, diagnostics), ...fields, diagnostics };
         }
 
         const lowering = this.#lowerGraphs(layout);
 
         diagnostics.push(...lowering.diagnostics);
 
-        return { ...this.#optimized(lowering.program, diagnostics), layout, diagnostics };
+        return { ...this.#optimized(lowering.program, diagnostics), ...fields, diagnostics };
     }
 
     /**
@@ -604,6 +817,43 @@ export class ParticleEffectDocument {
         return layout;
     }
 
+    /**
+     * The emitter field schema, built once per {@link version} for the same reason {@link #layout}
+     * is.
+     *
+     * @returns {ParticleLayout|null}
+     * @throws as {@link buildEmitterLayout}
+     */
+    #emitterLayout() {
+        if (this.#emitter_layout !== null && this.#emitter_layout.version === this.version) {
+            return this.#emitter_layout.layout;
+        }
+
+        const layout = this.buildEmitterLayout();
+
+        this.#emitter_layout = { version: this.version, layout };
+
+        return layout;
+    }
+
+    /**
+     * The global field imports, built once per {@link version}.
+     *
+     * @returns {ParticleLayout|null}
+     * @throws as {@link buildGlobalLayout}
+     */
+    #globalLayout() {
+        if (this.#global_layout !== null && this.#global_layout.version === this.version) {
+            return this.#global_layout.layout;
+        }
+
+        const layout = this.buildGlobalLayout();
+
+        this.#global_layout = { version: this.version, layout };
+
+        return layout;
+    }
+
     /**
      * Check the graphs and, if they hold up, lower them.
      *
@@ -640,11 +890,33 @@ export class ParticleEffectDocument {
     #lowerGraphsUncached(layout) {
         const diagnostics = [];
 
+        let emitter_layout;
+        let global_layout;
+
+        try {
+            emitter_layout = this.#emitterLayout();
+            global_layout = this.#globalLayout();
+        } catch (e) {
+            return {
+                program: null,
+                diagnostics: [{ scope: "effect", node: -1, line: 0, message: e.message, severity: PARTICLE_GRAPH_ERROR }],
+            };
+        }
+
         for (const scope of Object.values(PARTICLE_GRAPH_PHASE)) {
             // The validator is told which phase it is looking at: some of what is wrong with a
             // graph depends on which of the two it is, and deciding that is its business rather
             // than this document's.
-            for (const diagnostic of validate_particle_graph(this[scope], { layout, phase: scope })) {
+            // An effect that declares no emitter fields is checked against the empty schema, not
+            // left unchecked: a node reading one is wrong either way.
+            const checked = {
+                layout,
+                emitter_layout: emitter_layout ?? NO_EMITTER_FIELDS,
+                global_layout: global_layout ?? NO_EMITTER_FIELDS,
+                phase: scope,
+            };
+
+            for (const diagnostic of validate_particle_graph(this[scope], checked)) {
                 diagnostics.push({
                     scope,
                     node: diagnostic.node,
@@ -661,7 +933,13 @@ export class ParticleEffectDocument {
 
         try {
             return {
-                program: compile_particle_effect({ init: this.init, update: this.update, layout }),
+                program: compile_particle_effect({
+                    init: this.init,
+                    update: this.update,
+                    layout,
+                    emitter_layout: emitter_layout ?? undefined,
+                    global_layout: global_layout ?? undefined,
+                }),
                 diagnostics,
             };
         } catch (e) {
@@ -686,8 +964,8 @@ export class ParticleEffectDocument {
      * the preview shows, not whether a dangling input in front of the author is worth saying — so
      * this is separate from {@link compile}, which reports on the thing that runs.
      *
-     * @param {ParticleLayout} [layout] the schema to check attribute references against; built from
-     *   the document when not supplied, and skipped when it cannot be built
+     * @param {ParticleLayout} [layout] the schema to check particle field references against; built
+     *   from the document when not supplied, and skipped when it cannot be built
      * @returns {ParticleEffectCompilation['diagnostics']}
      */
     graphDiagnostics(layout) {
@@ -805,43 +1083,165 @@ export class ParticleEffectDocument {
     }
 
     /**
-     * Add an attribute to the per-particle record.
+     * Add a particle field to the per-particle record.
      *
      * @param {string} name
      * @param {number} components 1..4
-     * @param {string} [type] what the words are for, see {@link attributes}; omitted, they are
+     * @param {string} [type] what the words are for, see {@link particle_fields}; omitted, they are
      *   whatever `components` of them means and nothing more
      * @throws if the name is taken or the record has no room left
      */
-    addAttribute(name, components, type = undefined) {
-        const candidate = this.attributes.concat([{ name, components, type }]);
+    addParticleField(name, components, type = undefined) {
+        const candidate = this.particle_fields.concat([{ name, components, type }]);
 
         // built rather than assumed: ParticleLayout is where the record's capacity and the
         // duplicate-name rule live, and a layout that throws must not become the document's
         new ParticleLayout(candidate);
 
-        this.attributes = candidate;
+        this.particle_fields = candidate;
+
+        this.touch();
+    }
+
+    /**
+     * Declare an emitter field: a member every emitter of this effect carries for itself, starting
+     * from `value`.
+     *
+     * @param {string} name
+     * @param {number} components 1..4
+     * @param {string} [type] what the words are for, as for a particle field
+     * @param {number[]} [value] what an emitter starts with; zero where left out
+     * @throws if the name is taken
+     */
+    addEmitterField(name, components, type = undefined, value = []) {
+        const candidate = this.emitter_fields.concat([{ name, components, type, value: Array.from(value) }]);
+
+        // built rather than assumed, as for a particle field: the duplicate-name rule lives there
+        ParticleLayout.emitter(candidate);
+
+        this.emitter_fields = candidate;
+
+        this.touch();
+    }
+
+    /**
+     * Change the value an emitter of this effect starts with.
+     *
+     * @param {string} name
+     * @param {number[]} value
+     * @returns {boolean} false when there is no such emitter field
+     */
+    setEmitterFieldValue(name, value) {
+        const declaration = this.emitter_fields.find(field => field.name === name);
+
+        if (declaration === undefined) {
+            return false;
+        }
+
+        declaration.value = Array.from(value);
 
         this.touch();
+
+        return true;
+    }
+
+    /**
+     * Remove an emitter field. Nodes naming it are left alone and reported, as for a particle field.
+     *
+     * @param {string} name
+     * @returns {boolean} false when there was no such emitter field
+     */
+    removeEmitterField(name) {
+        const remaining = this.emitter_fields.filter(field => field.name !== name);
+
+        if (remaining.length === this.emitter_fields.length) {
+            return false;
+        }
+
+        this.emitter_fields = remaining;
+
+        this.touch();
+
+        return true;
+    }
+
+    /**
+     * Import a global field: a static member of whatever scene the effect runs in, read by name.
+     *
+     * @param {string} name
+     * @param {number} components 1..4
+     * @param {string} [type] what the words are for
+     * @param {number[]} [value] what the editor's preview gives it; zero where left out
+     * @throws if the name is taken
+     */
+    addGlobalField(name, components, type = undefined, value = []) {
+        const candidate = this.global_fields.concat([{ name, components, type, value: Array.from(value) }]);
+
+        ParticleLayout.emitter(candidate);
+
+        this.global_fields = candidate;
+
+        this.touch();
+    }
+
+    /**
+     * Change the value the editor's preview gives a global field.
+     *
+     * @param {string} name
+     * @param {number[]} value
+     * @returns {boolean} false when the effect imports no such global field
+     */
+    setGlobalFieldValue(name, value) {
+        const declaration = this.global_fields.find(field => field.name === name);
+
+        if (declaration === undefined) {
+            return false;
+        }
+
+        declaration.value = Array.from(value);
+
+        this.touch();
+
+        return true;
+    }
+
+    /**
+     * Stop importing a global field. Nodes naming it are left alone and reported.
+     *
+     * @param {string} name
+     * @returns {boolean} false when there was no such import
+     */
+    removeGlobalField(name) {
+        const remaining = this.global_fields.filter(field => field.name !== name);
+
+        if (remaining.length === this.global_fields.length) {
+            return false;
+        }
+
+        this.global_fields = remaining;
+
+        this.touch();
+
+        return true;
     }
 
     /**
-     * Remove an attribute, and unbind any render channel that pointed at it.
+     * Remove a particle field, and unbind any render channel that pointed at it.
      *
      * Nodes naming it are left alone: they become invalid, which the validator reports against the
      * node, and that is a better outcome than silently rewriting an author's graph.
      *
      * @param {string} name
-     * @returns {boolean} false when there was no such attribute
+     * @returns {boolean} false when there was no such particle field
      */
-    removeAttribute(name) {
-        const remaining = this.attributes.filter(attribute => attribute.name !== name);
+    removeParticleField(name) {
+        const remaining = this.particle_fields.filter(particle_field => particle_field.name !== name);
 
-        if (remaining.length === this.attributes.length) {
+        if (remaining.length === this.particle_fields.length) {
             return false;
         }
 
-        this.attributes = remaining;
+        this.particle_fields = remaining;
 
         for (const channel of EMITTER_RENDER_CHANNELS) {
             if (this.emitter.render[channel] === name) {
@@ -857,28 +1257,30 @@ export class ParticleEffectDocument {
     /**
      * The emitter settings as {@link ParticleEmitter.from} takes them, with the compiled effect.
      *
-     * Render channels naming an attribute the layout no longer has are dropped rather than passed
-     * on, because `bind_render` throws on one — and an effect that fails to build over a stale
-     * binding is a worse thing to hand an author than one that draws without a colour.
+     * Render channels naming a particle field the layout no longer has are dropped rather than
+     * passed on, because `bind_render` throws on one — and an effect that fails to build over a
+     * stale binding is a worse thing to hand an author than one that draws without a colour.
      *
-     * @param {{layout: ParticleLayout, program: object}} compiled what {@link compile} produced,
-     *   packaged the way `create_particle_effect` does
+     * @param {{layout: ParticleLayout, program: object, emitter_layout?: ParticleLayout|null, emitter_fields?: Uint32Array}} compiled
+     *   what {@link compile} produced, packaged the way `create_particle_effect` does
      * @returns {object}
      */
-    emitterConfig({ layout, program }) {
+    emitterConfig({ layout, program, emitter_layout = null, emitter_fields = new Uint32Array(0) }) {
         const render = {};
 
         for (const channel of EMITTER_RENDER_CHANNELS) {
-            const attribute = this.emitter.render[channel];
+            const particle_field = this.emitter.render[channel];
 
-            if (attribute !== undefined && layout.has(attribute)) {
-                render[channel] = attribute;
+            if (particle_field !== undefined && layout.has(particle_field)) {
+                render[channel] = particle_field;
             }
         }
 
         return {
             layout,
             program,
+            emitter_layout,
+            emitter_fields,
             name: this.name,
             spawn_rate: this.emitter.spawn_rate,
             prewarm: this.emitter.prewarm,
@@ -915,7 +1317,9 @@ export class ParticleEffectDocument {
     toJSON() {
         return {
             name: this.name,
-            attributes: this.attributes.map(attribute => ({ ...attribute })),
+            particle_fields: this.particle_fields.map(particle_field => ({ ...particle_field })),
+            emitter_fields: this.emitter_fields.map(field => ({ ...field, value: Array.from(field.value) })),
+            global_fields: this.global_fields.map(field => ({ ...field, value: Array.from(field.value) })),
             groups: this.groups.map(serialize_particle_group),
             init: serialize_particle_graph({ graph: this.init, visual: this.init_visual }),
             update: serialize_particle_graph({ graph: this.update, visual: this.update_visual }),
@@ -946,7 +1350,10 @@ export class ParticleEffectDocument {
      */
     #load(json, visualRegistry) {
         this.name = json.name ?? "effect";
-        this.attributes = (json.attributes ?? []).map(attribute => ({ ...attribute }));
+        // older documents carry the particle fields as `attributes`
+        this.particle_fields = (json.particle_fields ?? json.attributes ?? []).map(particle_field => ({ ...particle_field }));
+        this.emitter_fields = (json.emitter_fields ?? []).map(field => ({ ...field, value: Array.from(field.value ?? []) }));
+        this.global_fields = (json.global_fields ?? []).map(field => ({ ...field, value: Array.from(field.value ?? []) }));
 
         // `NodeGraph.reset` drops its nodes without announcing them, so the watch list is cleared
         // here rather than being left holding a graph that no longer exists