@woosh/meep-engine 3.18.0 → 3.19.0

package/src/core/model/node-graph/visual/layout/layout_assign_coordinates.js

@@ -347,11 +347,13 @@ function align(graph, layer_count, order, rank, layer_start, neighbours, marked,
  * Push the blocks of one pass as far towards the top as the boxes below them allow, and read off a
  * coordinate for every box.
  *
- * Blocks are placed by longest path through the constraints between neighbours in a column, which
- * is what makes the arrangement as tight as the ordering permits. Blocks that turn out not to
- * constrain each other at all form separate classes, and a class is then shifted up until it meets
- * whatever is above it — without that, a block hanging off the bottom of the drawing pins every
- * class that follows it down there too.
+ * First place blocks relative to the sink of their class, then solve the separation constraints
+ * between classes. A class above another must carry that neighbour's final shift: treating a
+ * relative shift as absolute can move the lower class into the upper one. These constraints form
+ * a DAG, so a topological pass propagates every shift before the classes depending on it are placed.
+ * Both stages take linear time and preserve the port offsets within each block.
+ *
+ * @see https://arxiv.org/abs/2008.01252 — Brandes, Walter, Zink, correction to shift accumulation
  *
  * @param {LayoutBoxGraph} graph
  * @param {Int32Array} order
@@ -428,13 +430,7 @@ function compact(graph, order, rank, layer_start, block, options) {
                     if (place[u] + need > place[v]) {
                         place[v] = place[u] + need;
                     }
-                } else {
-                    const slack = place[v] - place[u] - need;
-
-                    if (slack < shift[sink[u]]) {
-                        shift[sink[u]] = slack;
-                    }
-                }
+                }
             }
 
             w = next[w];
@@ -450,15 +446,62 @@ function compact(graph, order, rank, layer_start, block, options) {
     const y = new Float64Array(box_count);
 
     for (let box = 0; box < box_count; box++) {
-        const r = root[box];
-
-        y[box] = place[r] + offset[box];
-
-        const carried = shift[sink[r]];
-
-        if (carried < Infinity) {
-            y[box] += carried;
-        }
+        const r = root[box];
+
+        y[box] = place[r] + offset[box];
+    }
+
+    // Record every boundary between classes, directed from the lower class to the upper one.
+    // Use the position of the lower box in `order` as the edge index; its predecessor is `at - 1`.
+    // Parallel boundaries matter: different box heights and ports can make either one tighter.
+    const first_boundary = new Int32Array(box_count).fill(-1);
+    const next_boundary = new Int32Array(box_count);
+    const pending = new Int32Array(box_count);
+
+    for (let layer = 0; layer + 1 < layer_start.length; layer++) {
+        for (let at = layer_start[layer] + 1; at < layer_start[layer + 1]; at++) {
+            const upper = sink[root[order[at - 1]]];
+            const lower = sink[root[order[at]]];
+
+            if (upper !== lower) {
+                next_boundary[at] = first_boundary[lower];
+                first_boundary[lower] = at;
+                pending[upper]++;
+            }
+        }
+    }
+
+    const ready = new Int32Array(box_count);
+    let end = 0;
+
+    for (let box = 0; box < box_count; box++) {
+        if (root[box] === box && sink[box] === box && pending[box] === 0) {
+            shift[box] = 0;
+            ready[end++] = box;
+        }
+    }
+
+    for (let cursor = 0; cursor < end; cursor++) {
+        const lower = ready[cursor];
+
+        for (let at = first_boundary[lower]; at !== -1; at = next_boundary[at]) {
+            const above = order[at - 1];
+            const below = order[at];
+            const upper = sink[root[above]];
+
+            // y[above] + shift[upper] + separation <= y[below] + shift[lower]
+            const limit = shift[lower] + y[below] - y[above] - separation(above, below);
+
+            shift[upper] = Math.min(shift[upper], limit);
+
+            if (--pending[upper] === 0) {
+                ready[end++] = upper;
+            }
+        }
+    }
+
+    for (let box = 0; box < box_count; box++) {
+        y[box] += shift[sink[root[box]]];
     }
 
     return y;
@@ -471,7 +514,9 @@ function compact(graph, order, rank, layer_start, block, options) {
  * top edge, the ones biased towards the bottom by their bottom edge — against whichever of them
  * came out shortest. Only then can they be compared box by box, and each box takes the average of
  * the middle two of its four candidates: an average of all four is pulled about by whichever single
- * pass went furthest astray, and the middle two are the ones the passes agree on.
+ * pass went furthest astray, and the middle two are the ones the passes agree on.
+ * Each candidate must already satisfy every separation constraint. Taking the same order
+ * statistics for both ends of an inequality preserves it; balancing cannot repair an invalid pass.
  *
  * @param {LayoutBoxGraph} graph mutated: `box_y` is written
  * @param {Float64Array[]} candidates

package/src/engine/asset/loaders/image/ImageDecoderWorker.js

@@ -1,32 +1,17 @@
 import { PNGReader } from "../../../../format/image/png/PNGReader.js";
 
-async function decode_png(png_bytes) {
-    return new Promise((resolve, reject) => {
-
-        const reader = new PNGReader(png_bytes);
-
-        // console.time('decode');
-        // console.profile('decode');
-
-        const png = reader.parse();
-
-        const uint_channels = png.getUint8Data();
-
-        const width = png.getWidth();
-        const height = png.getHeight();
-
-        // console.timeEnd('decode');
-        // console.profileEnd('decode');
-
-        resolve({
-            data: uint_channels.data.buffer,
-            width,
-            height,
-            itemSize: uint_channels.itemSize,
-            bitDepth: png.getBitDepth()
-        });
-    });
-}
+async function decode_png(png_bytes) {
+    const png = await new PNGReader(png_bytes).parse();
+    const uint_channels = png.getUint8Data();
+
+    return {
+        data: uint_channels.data.buffer,
+        width: png.getWidth(),
+        height: png.getHeight(),
+        itemSize: uint_channels.itemSize,
+        bitDepth: png.getBitDepth()
+    };
+}
 
 /**
  *

package/src/engine/asset/loaders/image/prototypePNG.js

@@ -16,22 +16,23 @@ const array_loader = new ArrayBufferLoader();
 // const path = 'data/textures/utility/vt/uv_map_reference/5-21-14.png';
 const path = 'data/textures/utility/vt/uv_map_reference/6-39-33.png';
 
-array_loader.load(new AssetRequestScope(), path, (asset) => {
+array_loader.load(new AssetRequestScope(), path, (asset) => {
 
     const array = asset.create();
 
     const reader = new PNGReader(array);
 
-    const png = reader.parse();
+    reader.parse().then(png => {
 
-    console.log(png);
+        console.log(png);
 
-    const uint8Data = png.getUint8Data();
+        const uint8Data = png.getUint8Data();
 
-    const sampler = new Sampler2D(uint8Data.data, uint8Data.itemSize, png.getWidth(), png.getHeight());
+        const sampler = new Sampler2D(uint8Data.data, uint8Data.itemSize, png.getWidth(), png.getHeight());
 
-    const canvas = sampler2D2Canvas(sampler, 1, 0);
+        const canvas = sampler2D2Canvas(sampler, 1, 0);
 
-    document.body.appendChild(canvas);
+        document.body.appendChild(canvas);
+    }).catch(error => console.error('Failed to decode PNG', error));
 
 });

package/src/engine/ecs/storage/populateEngineSerializationRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"populateEngineSerializationRegistry.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/storage/populateEngineSerializationRegistry.js"],"names":[],"mappings":"AAmLA;;;;;;;;GAQG;AACH,iGA2GC"}
+{"version":3,"file":"populateEngineSerializationRegistry.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/storage/populateEngineSerializationRegistry.js"],"names":[],"mappings":"AAsLA;;;;;;;;GAQG;AACH,iGA4GC"}

package/src/engine/ecs/storage/populateEngineSerializationRegistry.js

@@ -45,6 +45,9 @@ import {
 } from "../../graphics3/VolumetricLightMapSerializationAdapter.js";
 import { Transform } from "../transform/Transform.js";
 import { Transform64SerializationAdapter } from "../transform/Transform64SerializationAdapter.js";
+import {
+    ParticleEffectSerializationAdapter
+} from "../../graphics/ecs/particles/ParticleEffectSerializationAdapter.js";
 import { TransformSerializationAdapter } from "../transform/TransformSerializationAdapter.js";
 import { TransformSerializationUpgrader_0_1 } from "../transform/TransformSerializationUpgrader_0_1.js";
 import {
@@ -206,6 +209,7 @@ export function populateEngineSerializationRegistry(registry) {
         new PathSerializationAdapter(),
         new TagSerializationAdapter(),
         new ParticleEmitterSerializationAdapter(),
+        new ParticleEffectSerializationAdapter(),
         new SoundEmitterSerializationAdapter(),
         new SoundControllerSerializationAdapter(),
         new SoundListenerSerializationAdapter(),

package/src/engine/graphics/ecs/particles/ParticleEffect.d.ts

@@ -0,0 +1,266 @@
+/**
+ * What an entity emits. Paired with a {@link ../../../ecs/transform/Transform64.js Transform64},
+ * which says where, this is the whole of an emitter in the ECS:
+ *
+ * ```js
+ * new Entity()
+ *     .add(new Transform64())
+ *     .add(ParticleEffect.from({ ...create_particle_effect({ layout, init, update }), spawn_rate: 400 }))
+ *     .build(dataset);
+ * ```
+ *
+ * {@link ../../../graphics3/GPUParticleEmitterSystem.js GPUParticleEmitterSystem} is what turns the
+ * pair into particles: it gives the entity a
+ * {@link ../../../../shade/renderer/particles/runtime/ParticleEmitter.js ParticleEmitter} node in
+ * the scene it owns, keeps that node where the transform says, packs {@link texture} into the
+ * scene's sprite atlas, and follows every field below. Nothing here reaches a device by itself, and
+ * an entity carrying one of these with no such system in the profile simply emits nothing.
+ *
+ * ## It is a description, and only a description
+ *
+ * Everything on it means the same thing with no renderer present: the attribute {@link layout} and
+ * the compiled {@link program} that make up an effect, the {@link texture} to draw with, the rate,
+ * the pre-warm, the blend / projection / feature {@link flags}, the render-attribute bindings and
+ * the flipbook grid. That is deliberate, and it is what makes the component the unit an editor
+ * inspects, a prefab carries and a system diffs.
+ *
+ * What is **not** here: the scene node the system built, the emitter's row in the GPU emitter table,
+ * the generation of that row, where the program was placed in the program heap, and where the
+ * texture landed in the atlas. All of that belongs to whoever registered the emitter — see
+ * {@link ../../../../shade/renderer/particles/runtime/GPUParticleEmitterContext.js} — and none of it
+ * survives a device restart, which is exactly why it is not on a component that does.
+ *
+ * There are no bounds here either. An emitter's particles are moved by arbitrary bytecode, so the
+ * box is **measured** from the live particles by a GPU pass at the end of every frame rather than
+ * authored; the one authored part of it is whether this effect opts into culling at all
+ * (`cull` in {@link flags}).
+ *
+ * ## Sharing
+ *
+ * {@link layout} and {@link program} are immutable once compiled and are meant to be shared: fifty
+ * campfires hold fifty components pointing at one compiled effect, which is what puts them on one id
+ * in the program heap and therefore in one simulation bucket. {@link copy} shares them rather than
+ * duplicating them for that reason.
+ *
+ * ## Changing one
+ *
+ * Assign to the fields. The system compares what it holds against what it last wrote to the scene
+ * node, once per frame per entity, so there is no flag to set and no signal to fire — a component
+ * whose fields have not moved costs a run of comparisons and no upload. That is a deliberate trade
+ * against the observable-per-field shape the older components use: an effect has fifteen fields,
+ * gameplay writes them in bursts, and a row is restaged whole either way.
+ *
+ * ## Saving one
+ *
+ * {@link ./ParticleEffectSerializationAdapter.js} writes all of it, the compiled program included.
+ * The VM's instruction set is a durable format by design — fixed-width opcodes and a constant pool —
+ * so a level carries the bytecode the way it carries a mesh's indices, and a shipped build needs
+ * neither the graph the effect was compiled from nor a compiler at runtime. Authoring belongs to an
+ * editor.
+ *
+ * Two things are consequently wire format: the opcode numbers, and the **order** of the attributes
+ * in {@link layout}, because the offsets in the render bindings are assigned from that order.
+ */
+export class ParticleEffect {
+    /**
+     * Build a component from a plain description. Every field is optional — a component with no
+     * effect is a placeholder waiting for one — so an effect goes in by spreading what
+     * {@link ../../../../shade/renderer/particles/runtime/create_particle_effect.js create_particle_effect}
+     * returns: `ParticleEffect.from({ ...effect, spawn_rate: 100 })`.
+     *
+     * @param {object} [config]
+     * @param {import("../../../../shade/renderer/particles/layout/ParticleLayout.js").ParticleLayout} [config.layout]
+     * @param {import("../../../../shade/renderer/particles/isa/ParticleProgram.js").ParticleProgram} [config.program]
+     * @param {string|null} [config.texture] image URL to draw with
+     * @param {number} [config.seed]
+     * @param {number} [config.spawn_rate] particles/second
+     * @param {boolean} [config.emitting]
+     * @param {number} [config.prewarm] seconds of emission to run forward before the first frame
+     * @param {object} [config.flags] passed to `make_emitter_flags`
+     * @param {Object<string,string>} [config.render] render channel -> attribute name
+     * @param {ArrayLike<number>} [config.flipbook] `[columns, rows]`
+     * @returns {ParticleEffect}
+     */
+    static from(config?: {
+        layout?: import("../../../../shade/renderer/particles/layout/ParticleLayout.js").ParticleLayout;
+        program?: import("../../../../shade/renderer/particles/isa/ParticleProgram.js").ParticleProgram;
+        texture?: string | null;
+        seed?: number;
+        spawn_rate?: number;
+        emitting?: boolean;
+        prewarm?: number;
+        flags?: object;
+        render?: {
+            [x: string]: string;
+        };
+        flipbook?: ArrayLike<number>;
+    }): ParticleEffect;
+    /**
+     * The per-particle attribute schema: which named attributes a particle of this effect has, how
+     * wide each is, and what word of the record it sits at.
+     *
+     * `null` until an effect is assigned. An entity whose component has none is linked and idle
+     * rather than an error — an effect that is still compiling or still loading is ordinary — and it
+     * starts emitting on the frame after both this and {@link program} are set.
+     *
+     * @type {import("../../../../shade/renderer/particles/layout/ParticleLayout.js").ParticleLayout|null}
+     */
+    layout: import("../../../../shade/renderer/particles/layout/ParticleLayout.js").ParticleLayout | null;
+    /**
+     * The compiled INIT/UPDATE bytecode run for every particle. Replace the immutable program to
+     * edit the effect; do not mutate its bytecode in place.
+     *
+     * @type {import("../../../../shade/renderer/particles/isa/ParticleProgram.js").ParticleProgram|null}
+     */
+    program: import("../../../../shade/renderer/particles/isa/ParticleProgram.js").ParticleProgram | null;
+    /**
+     * Image to draw the particles with, by URL, or `null` to draw against a single white texel — so
+     * an untextured effect is a flat quad of its own colour.
+     *
+     * The system loads this through `AssetManager` and packs it into the sprite atlas its scene
+     * shares, one patch per distinct URL however many entities name it. Where it lands is the
+     * system's answer and changes on every repack, without this component changing.
+     *
+     * @type {string|null}
+     */
+    texture: string | null;
+    /**
+     * Base RNG seed.
+     *
+     * Two entities running one program produce identical particles from identical seeds. `0` reads
+     * as "unset", and the emitter then takes its registration's generation instead, which no other
+     * live emitter shares — so leaving this alone is what makes fifty campfires burn differently.
+     *
+     * @type {number}
+     */
+    seed: number;
+    /**
+     * Continuous emission rate, particles per second. Integrated on the GPU; the CPU never counts
+     * particles.
+     *
+     * @type {number}
+     */
+    spawn_rate: number;
+    /**
+     * Whether the effect is currently emitting.
+     *
+     * Turning it off holds {@link spawn_rate} at zero without the caller having to remember what the
+     * rate was — which is the whole reason it exists, because "put the torch out and light it again"
+     * otherwise means every caller keeping a shadow copy of the number. Particles already alive are
+     * **not** killed: a fire that stops emitting burns down, which is what stopping a fire looks
+     * like. Kill them from the effect's own UPDATE program if an effect wants to vanish.
+     *
+     * @type {boolean}
+     */
+    emitting: boolean;
+    /**
+     * Seconds this effect is run forward before it is first shown, `0` for none.
+     *
+     * A continuous effect starts empty and grows into its steady state over one particle lifetime,
+     * in front of whoever is watching. Setting this to about the effect's particle lifetime means
+     * the population on the first visible frame is the one the emitter would have had by then —
+     * spawned, aged and thinned by its own program over that long.
+     *
+     * It is paid once, on the frame the emitter is registered, by a pipeline of its own that
+     * simulates a private population and moves the result into the scene. Longer costs a longer loop
+     * on that one frame and nothing after it.
+     *
+     * @type {number}
+     */
+    prewarm: number;
+    /**
+     * Packed feature / blend / projection bits — see
+     * {@link ../../../../shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js make_emitter_flags}.
+     *
+     * @type {number}
+     */
+    flags: number;
+    /**
+     * Flipbook grid: columns, rows, over whatever region {@link texture} was packed into. `[1, 1]`
+     * is a single frame.
+     *
+     * @type {Float32Array}
+     */
+    flipbook: Float32Array;
+    /** @type {number} record word offset of world position, or {@link EMITTER_ATTRIBUTE_ABSENT} */
+    render_position: number;
+    /** @type {number} record word offset of size */
+    render_size: number;
+    /** @type {number} record word offset of rgba colour */
+    render_color: number;
+    /** @type {number} record word offset of roll angle, radians */
+    render_rotation: number;
+    /** @type {number} record word offset of flipbook frame index */
+    render_frame: number;
+    /** @type {number} record word offset of velocity, read by the STRETCHED projection */
+    render_velocity: number;
+    /**
+     * The rate the emitter actually runs at: {@link spawn_rate} while {@link emitting}, and zero
+     * otherwise. What the system writes to the GPU record.
+     *
+     * @returns {number}
+     */
+    get effective_spawn_rate(): number;
+    /**
+     * Bind render channels to per-particle attributes of this effect, by attribute name.
+     *
+     * Channels left out of `channels` keep whatever they had; a channel that was never bound stays
+     * at {@link EMITTER_ATTRIBUTE_ABSENT}, which the passes read as "this effect has no such
+     * attribute" — the render pass substitutes a default and the sort pass treats the particle as
+     * being at the origin.
+     *
+     * Word offsets are stored rather than names because that is what the render and sort passes
+     * index a particle record with; resolving here is the only place a name is involved, which is
+     * also why this needs {@link layout} to have been set first.
+     *
+     * @param {Object<string,string>} channels channel name (see `EMITTER_RENDER_CHANNELS`) ->
+     *        attribute name in this effect's layout
+     * @returns {ParticleEffect} this
+     */
+    bind_render(channels: {
+        [x: string]: string;
+    }): ParticleEffect;
+    /**
+     * Structural equality over everything the component *is*. Two components that compare equal
+     * describe one effect, and one emitter row would serve both.
+     *
+     * The compiled program compares by its own bytecode rather than by object identity, so two
+     * components separately compiled from one graph compare equal.
+     *
+     * @param {ParticleEffect} other
+     * @returns {boolean}
+     */
+    equals(other: ParticleEffect): boolean;
+    /**
+     * Hash over everything {@link equals} compares, in the same terms.
+     *
+     * @returns {number} int32
+     */
+    hash(): number;
+    /**
+     * Make this a copy of `other`: same effect, same settings.
+     *
+     * The layout and the compiled program are **shared** rather than duplicated — both are immutable
+     * once compiled, and sharing them is what puts two entities of one effect on one program id in
+     * the heap, hence in one simulation bucket.
+     *
+     * @param {ParticleEffect} other
+     * @returns {ParticleEffect} this
+     */
+    copy(other: ParticleEffect): ParticleEffect;
+    /**
+     * @returns {ParticleEffect}
+     */
+    clone(): ParticleEffect;
+    /**
+     * Enables a fast type check, without having to import the class separately.
+     *
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isParticleEffect: boolean;
+}
+export namespace ParticleEffect {
+    let typeName: string;
+}
+//# sourceMappingURL=ParticleEffect.d.ts.map

package/src/engine/graphics/ecs/particles/ParticleEffect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleEffect.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/particles/ParticleEffect.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH;IAoRI;;;;;;;;;;;;;;;;;;OAkBG;IACH;QAZ2G,MAAM,GAAtG,OAAO,+DAA+D,EAAE,cAAc;QACS,OAAO,GAAtG,OAAO,6DAA6D,EAAE,eAAe;QAChE,OAAO,GAA5B,MAAM,GAAC,IAAI;QACK,IAAI,GAApB,MAAM;QACU,UAAU,GAA1B,MAAM;QACW,QAAQ,GAAzB,OAAO;QACS,OAAO,GAAvB,MAAM;QACU,KAAK,GAArB,MAAM;QACyB,MAAM;gBAA9B,MAAM,GAAC,MAAM;;QACO,QAAQ,GAAnC,UAAU,MAAM,CAAC;QACf,cAAc,CA8C1B;IAjVD;;;;;;;;;OASG;IACH,QAFU,OAAO,+DAA+D,EAAE,cAAc,GAAC,IAAI,CAEvF;IAEd;;;;;OAKG;IACH,SAFU,OAAO,6DAA6D,EAAE,eAAe,GAAC,IAAI,CAErF;IAEf;;;;;;;;;OASG;IACH,SAFU,MAAM,GAAC,IAAI,CAEN;IAEf;;;;;;;;OAQG;IACH,MAFU,MAAM,CAEP;IAET;;;;;OAKG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;;;;OAUG;IACH,UAFU,OAAO,CAED;IAEhB;;;;;;;;;;;;;OAaG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;;;OAKG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;OAKG;IACH,UAFU,YAAY,CAEc;IAEpC,+FAA+F;IAC/F,iBADW,MAAM,CAC0B;IAC3C,gDAAgD;IAChD,aADW,MAAM,CACsB;IACvC,uDAAuD;IACvD,cADW,MAAM,CACuB;IACxC,+DAA+D;IAC/D,iBADW,MAAM,CAC0B;IAC3C,gEAAgE;IAChE,cADW,MAAM,CACuB;IACxC,sFAAsF;IACtF,iBADW,MAAM,CAC0B;IAE3C;;;;;OAKG;IACH,mCAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH;YAJkB,MAAM,GAAC,MAAM;QAElB,cAAc,CAuC1B;IAED;;;;;;;;;OASG;IACH,cAHW,cAAc,GACZ,OAAO,CAsBnB;IAED;;;;OAIG;IACH,QAFa,MAAM,CAuBlB;IAED;;;;;;;;;OASG;IACH,YAHW,cAAc,GACZ,cAAc,CAuB1B;IAED;;OAEG;IACH,SAFa,cAAc,CAI1B;IAkGL;;;;;OAKG;IACH,2BAFU,OAAO,CAEwB;CAtCxC;;kBA4BS,MAAM"}