@woosh/meep-engine 3.16.0 → 3.17.1

package/README.md

@@ -8,11 +8,11 @@
 npm install @woosh/meep-engine
 ```
 
-**Start here:** [`samples/engine/README.md`](samples/engine/README.md) — the first thirty minutes,
-with the Vite stanza you need, why your scene should be authored in metres, photometric reference
-values, and how input reaches the engine. The worked example beside it,
-[`samples/engine/first-scene`](samples/engine/first-scene), boots the engine, lights a scene and
-reads the keyboard in about eighty lines.
+**Start here:** the package ships a guide to the first thirty minutes at
+`samples/engine/README.md` - the Vite stanza you need, why your scene should be authored in
+metres, photometric reference values, and how input reaches the engine. The worked example beside
+it, `samples/engine/first-scene`, boots the engine, lights a scene and reads the keyboard in about
+eighty lines.
 
 **Proprietary and source-available.** You get all ~6,200 fine-grained ES modules, unobfuscated,
 under a licence that lets you ship. Need a lerp function? Import the module that holds it and pay
@@ -32,10 +32,9 @@ on paper and still not have them working together - and every plugin is another
 tune, per scene and per device.
 
 **Shadows, ambient occlusion, indirect lighting, auto-exposure, anti-aliasing and transparency are
-all on by default, and there is nothing to configure to get a correct-looking frame.** No quality
-tiers to author, no per-device profiles, no exposure value to pick, no shadow cascade splits to
-hand-tune. You put a scene together, it looks right, and it holds its frame rate across a wide
-range of hardware without you doing anything about it.
+all on by default, with nothing to configure.** No quality tiers to author, no per-device profiles,
+no exposure value to pick, no shadow cascade splits to hand-tune. You put a scene together and it
+holds its frame rate across a wide range of hardware without you doing anything about it.
 
 In development since 2013, shipped in a commercial Steam release, and held to **~15,000 tests** -
 determinism, adversarial and shader-emulation suites among them.
@@ -74,39 +73,6 @@ occlusion culling, the frame graph - they are in **the renderer contract**, whic
 package at `src/shade/RENDERER_CONTRACT.md`. It also covers how to put a model on the screen and
 how to add your own work to the frame.
 
-## How the features interact
-
-What a feature list cannot tell you is whether the features work together once they are in the same
-scene. This can.
-
-| | Lit by scene lights | Shadows | Stable when it moves | Indirect light |
-|---|---|---|---|---|
-| Static meshes | ✅ | casts + receives | ✅ | ✅ |
-| **Skinned characters** | ✅ | casts + receives | ✅ **per-vertex** | ✅ |
-| Terrain | ✅ | casts + receives | ✅ | ✅ |
-| Decals | ✅ | receives | ✅ follows the surface | ✅ |
-| Transparent surfaces | ✅ | receives | ❌ | ✅ |
-| Volumetric fog | ✅ | shadowed by them | ✅ | n/a |
-| Water, particles, trails, overlays | ❌ | ❌ | ❌ | ❌ |
-
-Those top six are not six systems that were each taught about lighting. They read the same lighting,
-the same shadows and the same motion data, because there is only one of each. Three consequences:
-
-* **Animated characters are not a special case.** A skinned character goes down the same path as a
-  static one: same culling, same shadows, same lighting. It also produces motion data per vertex
-  rather than per object, so a swinging arm resolves cleanly under anti-aliasing instead of
-  smearing - which is the usual failure of bolt-on temporal AA.
-* **A decal is lit like the surface it lands on.** Decals modify the surface itself rather than
-  painting over the finished image, so a scorch mark is lit, shadowed and bounced exactly like the
-  wall under it, and ambient occlusion and reflections see it too.
-* **Ordering is declared, not accidental.** Systems state what they must come after, by name, and
-  the renderer resolves the order. Decals declare that they follow terrain, so scorch marks land on
-  textured ground - rather than depending on which system happened to register first.
-
-Water, particles, trails and screen overlays are drawn after lighting, so they are not lit or
-shadowed and contribute no motion data. They read the scene's depth, so they are correctly hidden
-behind things in front of them.
-
 ## Scaling across hardware
 
 **One build covers a wide hardware range, and you don't author the tiers.** When frames start
@@ -165,36 +131,6 @@ skinned objects sample as they move through it. It bakes in-engine, from a live
 so the precompute is a call you make rather than a tool you leave the engine for. Opaque and
 transparent surfaces both use it, so turning it on does not leave them lit differently.
 
-## WebGPU only
-
-WebGPU is not a better WebGL - it is a different machine. Compute shaders, storage buffers and
-indirect draw are what let visibility be decided on the GPU and a whole scene be submitted in a
-couple of draw calls. None of that has an equivalent in WebGL, so supporting both would mean either
-a second renderer to maintain or holding this one down to what the older API can express. meep
-targets WebGPU, and everything above follows from that.
-
-The floor is fixed and checked before anything is created: WebGPU plus a small set of capabilities
-that mainstream desktop GPUs have had for years. Hardware that does not clear it gets a clear
-failure message written to be shown to a person, rather than a degraded picture. The exact features
-and limits are in §2 of `src/shade/RENDERER_CONTRACT.md`.
-
-To see what a given browser and GPU actually report, open
-**[webgpu.report](https://webgpu.report/)** on the machine in question - it lists the adapter's
-features and limits, which is what the floor is checked against.
-
-## Numbers
-
-There is no published benchmark for the renderer yet. What the pipeline does differently is
-checkable in the source without running anything - draw count independent of object count, one
-lighting pass independent of light count, material cost independent of overdraw - and the tools to
-measure the rest ship with it.
-
-The renderer records `.sgpt` GPU profile captures - per-pass timings, and at higher capture levels
-the frame-graph structure, dispatch and draw counts. Assign a
-`GPUProfileSession({ level: GPUProfileLevel.WORKLOAD })` to `renderer.profile_session`, call
-`start()`, run frames, and `stop()` returns an `ArrayBuffer` to write out. The recorder and the
-format specification (`src/shade/device/timing/profile/SGPT_FORMAT.md`) both ship in this package.
-
 ---
 
 ## Everything else

package/editor/particles/effect/ParticleEffectDocument.d.ts

@@ -28,8 +28,14 @@ export type PARTICLE_EFFECT_SOURCE = string;
  * ## Optimizing
  *
  * {@link optimize} runs the compiled program through
- * {@link ../../../src/shade/renderer/particles/optimizer/optimize_particle_program.js the optimizer}
- * before anybody gets it. It is a property of the effect rather than of a view because it changes
+ * {@link ../../../src/shade/renderer/particles/optimizer/dag/optimize_particle_program_vector.js the graph optimizer}
+ * before anybody gets it.
+ *
+ * There are two optimizers and they take the same arguments, so which one an editor runs is a choice
+ * rather than a rewrite. It is this one because it is both better and very much faster: on `curl4`
+ * the pass pipeline needs 3,690 ms against this one's 276, and comes out with 2,828 instructions
+ * against 2,826. A second-and-a-half of that difference is the pipeline running itself twice to
+ * decide about lane peeling. At 3.7 seconds an edit the setting could not be on at all. It is a property of the effect rather than of a view because it changes
  * what runs — the preview, the reference simulation and anything else downstream of {@link compile}
  * all get the optimized program — and a switch that changed what runs while living in one panel
  * would be invisible from the other three.
@@ -130,8 +136,17 @@ export class ParticleEffectDocument {
     /**
      * Whether {@link compile} hands back the optimized program.
      *
-     * Off by default, and off for every effect saved before it existed, because it is a thing an
-     * author turns on to see what it does rather than something done to their effect behind them.
+     * ON by default. It was off while it was new — a thing an author turned on to see what it did —
+     * and what changes that is not confidence but the promise being checkable: a program's meaning
+     * is its final record, its kill flag and its RNG state, and the optimizer is held to leaving all
+     * three identical to the bit over every environment the differential harness runs. An author who
+     * cannot observe the difference should not have to ask for it.
+     *
+     * The one rewrite that is not bit-exact — folding `x * 0`, which gives up the sign of that zero
+     * — is argued where it lives and is on there, not here. A tick-box in the editor is not the
+     * place to quietly widen what the optimizer may do; see {@link #optimized}.
+     *
+     * Turning it OFF still works and is what an author debugging a lowering wants, so the box stays.
      *
      * @type {boolean}
      */
@@ -331,11 +346,11 @@ export class ParticleEffectDocument {
      * 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}} effect what {@link compile} produced,
+     * @param {{layout: ParticleLayout, program: object}} compiled what {@link compile} produced,
      *   packaged the way `create_particle_effect` does
      * @returns {object}
      */
-    emitterConfig(effect: {
+    emitterConfig({ layout, program }: {
         layout: ParticleLayout;
         program: object;
     }): object;

package/editor/particles/effect/ParticleEffectDocument.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleEffectDocument.d.ts","sourceRoot":"","sources":["../../../../editor/particles/effect/ParticleEffectDocument.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"ParticleEffectDocument.d.ts","sourceRoot":"","sources":["../../../../editor/particles/effect/ParticleEffectDocument.js"],"names":[],"mappings":"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"}

package/editor/particles/effect/ParticleEffectDocument.js

@@ -29,7 +29,7 @@ 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 { optimize_compiled_particle_program } from "../../../src/shade/renderer/particles/optimizer/optimize_particle_program.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";
 
 /**
@@ -58,8 +58,14 @@ import { EMITTER_RENDER_CHANNELS } from "../../../src/shade/renderer/particles/r
  * ## Optimizing
  *
  * {@link optimize} runs the compiled program through
- * {@link ../../../src/shade/renderer/particles/optimizer/optimize_particle_program.js the optimizer}
- * before anybody gets it. It is a property of the effect rather than of a view because it changes
+ * {@link ../../../src/shade/renderer/particles/optimizer/dag/optimize_particle_program_vector.js the graph optimizer}
+ * before anybody gets it.
+ *
+ * There are two optimizers and they take the same arguments, so which one an editor runs is a choice
+ * rather than a rewrite. It is this one because it is both better and very much faster: on `curl4`
+ * the pass pipeline needs 3,690 ms against this one's 276, and comes out with 2,828 instructions
+ * against 2,826. A second-and-a-half of that difference is the pipeline running itself twice to
+ * decide about lane peeling. At 3.7 seconds an edit the setting could not be on at all. It is a property of the effect rather than of a view because it changes
  * what runs — the preview, the reference simulation and anything else downstream of {@link compile}
  * all get the optimized program — and a switch that changed what runs while living in one panel
  * would be invisible from the other three.
@@ -169,7 +175,8 @@ export class ParticleEffectDocument {
         cull: false,
         bounds_center: [0, 1, 0],
         bounds_radius: 3,
-        atlas_region: [0, 0, 1, 1],
+        /** 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: {
@@ -195,12 +202,21 @@ export class ParticleEffectDocument {
     /**
      * Whether {@link compile} hands back the optimized program.
      *
-     * Off by default, and off for every effect saved before it existed, because it is a thing an
-     * author turns on to see what it does rather than something done to their effect behind them.
+     * ON by default. It was off while it was new — a thing an author turned on to see what it did —
+     * and what changes that is not confidence but the promise being checkable: a program's meaning
+     * is its final record, its kill flag and its RNG state, and the optimizer is held to leaving all
+     * three identical to the bit over every environment the differential harness runs. An author who
+     * cannot observe the difference should not have to ask for it.
+     *
+     * The one rewrite that is not bit-exact — folding `x * 0`, which gives up the sign of that zero
+     * — is argued where it lives and is on there, not here. A tick-box in the editor is not the
+     * place to quietly widen what the optimizer may do; see {@link #optimized}.
+     *
+     * Turning it OFF still works and is what an author debugging a lowering wants, so the box stays.
      *
      * @type {boolean}
      */
-    optimize = false;
+    optimize = true;
 
     /**
      * Bumped on every {@link touch}. A view that caches something derived from the document can
@@ -250,7 +266,7 @@ export class ParticleEffectDocument {
      * A change to a document is seen by three panels and each of them asks what it compiles to, so
      * without this one edit is three compiles. That was affordable when an effect was forty
      * instructions; a graph with a `curl3` group in it lowers to about four thousand, which is 78ms
-     * to compile and another 570ms to optimize on this machine — three times over, on every
+     * to compile and another 214ms to optimize on this machine — three times over, on every
      * keystroke.
      *
      * The key is the {@link version} and the two settings that decide what a compile does, rather
@@ -554,7 +570,7 @@ export class ParticleEffectDocument {
         }
 
         try {
-            return { program: optimize_compiled_particle_program(program), unoptimized: program };
+            return { program: optimize_particle_program_vector(program), unoptimized: program };
         } catch (e) {
             diagnostics.push({
                 scope: "effect",
@@ -849,23 +865,24 @@ export class ParticleEffectDocument {
      * 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}} effect what {@link compile} produced,
+     * @param {{layout: ParticleLayout, program: object}} compiled what {@link compile} produced,
      *   packaged the way `create_particle_effect` does
      * @returns {object}
      */
-    emitterConfig(effect) {
+    emitterConfig({ layout, program }) {
         const render = {};
 
         for (const channel of EMITTER_RENDER_CHANNELS) {
             const attribute = this.emitter.render[channel];
 
-            if (attribute !== undefined && effect.layout.has(attribute)) {
+            if (attribute !== undefined && layout.has(attribute)) {
                 render[channel] = attribute;
             }
         }
 
         return {
-            effect,
+            layout,
+            program,
             name: this.name,
             spawn_rate: this.emitter.spawn_rate,
             flags: {
@@ -880,7 +897,7 @@ export class ParticleEffectDocument {
                 center: this.emitter.bounds_center,
                 radius: this.emitter.bounds_radius,
             },
-            atlas_region: this.emitter.atlas_region,
+            texture: this.emitter.texture,
             flipbook: this.emitter.flipbook,
             render,
         };
@@ -978,9 +995,13 @@ export class ParticleEffectDocument {
             : PARTICLE_EFFECT_SOURCE.GRAPH;
         this.assembly = json.assembly ?? "";
 
-        // absent reads as off, so an effect saved before the optimizer existed opens as the program
-        // its author last saw
-        this.optimize = json.optimize === true;
+        // Absent reads as ON, which is the default this document is constructed with. An effect
+        // saved before the setting existed therefore opens optimized — which is a change to what
+        // runs for that author, and the reason it is safe is the reason the default moved: the
+        // optimizer leaves the record, the kill flag and the RNG state identical to the bit. What is
+        // stored is a departure from the default in either direction, so an author who turned it off
+        // still gets it off.
+        this.optimize = json.optimize !== false;
 
         this.touch();
 

package/editor/view/node-graph/NodeGraphClipboard.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Take a copy of some of a graph.
+ *
+ * The wires that come along are the ones the fragment holds whole — both ends among the copied
+ * nodes. A wire with one end outside cannot be brought back: the node it reached is not part of
+ * what was copied, and a paste elsewhere in the graph, or in another graph entirely, has nothing to
+ * attach it to.
+ *
+ * @param {object} params
+ * @param {NodeGraph} params.graph
+ * @param {NodeGraphVisualData} [params.visual] where the nodes are; without it, everything is at the
+ *        origin and a paste arranges nothing
+ * @param {Iterable<number>} params.nodes ids to copy; ones that are not in the graph are skipped
+ * @param {function(NodeInstance):boolean} [params.copyable] whether a node may be had a second of.
+ *        Everything, by default. A host with node types that exist once per graph — a group body's
+ *        two boundary blocks — says so here, and they are left out rather than the whole copy being
+ *        refused.
+ * @returns {NodeGraphFragment|null} `null` when nothing was copied, so that a copy of nothing can be
+ *          told from a copy of something and left to leave the clipboard alone
+ */
+export function node_graph_fragment_from_nodes({ graph, visual, nodes, copyable }: {
+    graph: NodeGraph;
+    visual?: NodeGraphVisualData;
+    nodes: Iterable<number>;
+    copyable?: (arg0: NodeInstance) => boolean;
+}): NodeGraphFragment | null;
+/**
+ * The middle of a fragment, in the graph space it was copied from.
+ *
+ * What a paste puts where the author is looking, so that what lands is centred on the view rather
+ * than hanging off one corner of it.
+ *
+ * @param {NodeGraphFragment} fragment
+ * @returns {{x: number, y: number}}
+ */
+export function node_graph_fragment_centre(fragment: NodeGraphFragment): {
+    x: number;
+    y: number;
+};
+/**
+ * Nodes lifted out of a graph, waiting to be put back into one.
+ *
+ * ## Why a fragment rather than a graph
+ *
+ * What is copied cannot be node ids: ids are pooled, so the ones a fragment was cut from are handed
+ * to unrelated nodes the moment the originals are deleted, and a paste that named them would wire
+ * itself to whatever happened to be holding them. A fragment therefore refers to its own nodes by
+ * **index**, and is a thing in its own right rather than a view onto the graph it came from.
+ *
+ * Nor can it be a live {@link NodeInstance}: the instance would keep pointing at the graph it is in,
+ * and its parameters would be shared with it — an author editing the original after copying it would
+ * be editing what they had copied. Parameters are cloned on the way in for the same reason a group
+ * clones its body on the way out.
+ *
+ * A {@link NodeDescription}, on the other hand, *is* carried by reference. A description is a type,
+ * shared by every instance of it, and there is nothing to copy; it is also the one part of a node
+ * that cannot be written down — a particle node's description carries the closure that is the whole
+ * of what the node does. Which is why this clipboard is an object in the page rather than text on
+ * the system one: what it holds is only meaningful to a canvas that shares its node library.
+ *
+ * ## Who holds one
+ *
+ * A host with several canvases over one document — the particle editor's two phases, and the body of
+ * every group opened inside them — builds one of these and gives it to all of them, so a copy in one
+ * pastes in the next. A canvas built without one gets its own, and copies to itself.
+ */
+/**
+ * One node in a fragment.
+ *
+ * @typedef {object} NodeGraphFragmentNode
+ * @property {NodeDescription} description the type, by reference
+ * @property {object} parameters a deep copy, shared with nothing
+ * @property {number} x graph-space position it was copied from
+ * @property {number} y graph-space position it was copied from
+ */
+/**
+ * One wire in a fragment, between two of its own nodes.
+ *
+ * @typedef {object} NodeGraphFragmentConnection
+ * @property {number} from index into the fragment's nodes
+ * @property {number} fromPort port id on that node's description
+ * @property {number} to index into the fragment's nodes
+ * @property {number} toPort port id on that node's description
+ */
+/**
+ * @typedef {object} NodeGraphFragment
+ * @property {NodeGraphFragmentNode[]} nodes never empty — a fragment with no nodes is `null`
+ * @property {NodeGraphFragmentConnection[]} connections
+ */
+/**
+ * How far each repeat paste of the same content steps, in graph-space units.
+ *
+ * Enough to see the copy is a second thing rather than a redraw of the first, and small enough that
+ * it lands next to what it came from rather than somewhere else entirely.
+ *
+ * @type {number}
+ */
+export const NODE_GRAPH_PASTE_STEP: number;
+/**
+ * What was copied, and how many times it has been put down since.
+ */
+export class NodeGraphClipboard {
+    /**
+     * How many times what is held has been pasted already.
+     *
+     * A paste lands in the middle of what the author is looking at, so a second one would land
+     * exactly on top of the first and read as nothing having happened. The count is what steps it
+     * aside; see {@link NODE_GRAPH_PASTE_STEP}.
+     *
+     * @returns {number}
+     */
+    get pastes(): number;
+    /**
+     * @returns {boolean}
+     */
+    isEmpty(): boolean;
+    /**
+     * @returns {NodeGraphFragment|null}
+     */
+    read(): NodeGraphFragment | null;
+    /**
+     * Replace what is held. New content starts its paste count over, because the first paste of
+     * something new belongs where the author is looking rather than however far the last thing had
+     * walked.
+     *
+     * @param {NodeGraphFragment} fragment
+     */
+    write(fragment: NodeGraphFragment): void;
+    /**
+     * Record that what is held has been put down. Called by whoever is pasting it, once the paste is
+     * going ahead — a paste a canvas refused must not move the next one aside.
+     */
+    notePaste(): void;
+    clear(): void;
+    #private;
+}
+/**
+ * One node in a fragment.
+ */
+export type NodeGraphFragmentNode = {
+    /**
+     * the type, by reference
+     */
+    description: NodeDescription;
+    /**
+     * a deep copy, shared with nothing
+     */
+    parameters: object;
+    /**
+     * graph-space position it was copied from
+     */
+    x: number;
+    /**
+     * graph-space position it was copied from
+     */
+    y: number;
+};
+/**
+ * One wire in a fragment, between two of its own nodes.
+ */
+export type NodeGraphFragmentConnection = {
+    /**
+     * index into the fragment's nodes
+     */
+    from: number;
+    /**
+     * port id on that node's description
+     */
+    fromPort: number;
+    /**
+     * index into the fragment's nodes
+     */
+    to: number;
+    /**
+     * port id on that node's description
+     */
+    toPort: number;
+};
+export type NodeGraphFragment = {
+    /**
+     * never empty — a fragment with no nodes is `null`
+     */
+    nodes: NodeGraphFragmentNode[];
+    connections: NodeGraphFragmentConnection[];
+};
+//# sourceMappingURL=NodeGraphClipboard.d.ts.map

package/editor/view/node-graph/NodeGraphClipboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeGraphClipboard.d.ts","sourceRoot":"","sources":["../../../../editor/view/node-graph/NodeGraphClipboard.js"],"names":[],"mappings":"AAmIA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAX6B,KAAK;IACM,MAAM;IAEV,KAAK,EAA9B,SAAS,MAAM,CAAC;IACwB,QAAQ,2BAAzB,OAAO;IAI5B,iBAAiB,GAAC,IAAI,CA2DlC;AAED;;;;;;;;GAQG;AACH,qDAHW,iBAAiB;OACX,MAAM;OAAK,MAAM;EAcjC;AAtOD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;;;GAQG;AAEH;;;;;;;;GAQG;AAEH;;;;GAIG;AAEH;;;;;;;GAOG;AACH,oCAFU,MAAM,CAEwB;AAExC;;GAEG;AACH;IAWI;;;;;;;;OAQG;IACH,qBAEC;IAED;;OAEG;IACH,WAFa,OAAO,CAInB;IAED;;OAEG;IACH,QAFa,iBAAiB,GAAC,IAAI,CAIlC;IAED;;;;;;OAMG;IACH,gBAFW,iBAAiB,QAK3B;IAED;;;OAGG;IACH,kBAEC;IAED,cAGC;;CACJ;;;;;;;;;;;;gBAhGa,MAAM;;;;OACN,MAAM;;;;OACN,MAAM;;;;;;;;;UAON,MAAM;;;;cACN,MAAM;;;;QACN,MAAM;;;;YACN,MAAM;;;;;;WAKN,qBAAqB,EAAE;iBACvB,2BAA2B,EAAE"}