@woosh/meep-engine 3.17.1 → 3.18.0

package/editor/tools/engine/ToolEngine.d.ts

@@ -6,6 +6,20 @@ declare class ToolEngine {
     isRunning: boolean;
     shutdownCallbacks: any[];
     pointer: any;
+    /**
+     * Fired with the tool when a gesture starts (primary-button press accepted by a tool).
+     * @type {Signal}
+     */
+    onGestureStart: Signal;
+    /**
+     * Fired with the tool when its gesture ends (the paired release), after `tool.stop()`.
+     * @type {Signal}
+     */
+    onGestureEnd: Signal;
+    /**
+     * @returns {boolean}
+     */
+    get gesture_active(): boolean;
     activate(toolName: any): void;
     initialize(): void;
     /**
@@ -15,8 +29,24 @@ declare class ToolEngine {
      */
     startup(engine: Engine, editor: Editor): void;
     editor: Editor;
+    /**
+     * End the gesture in progress, if any: `tool.stop()`, then the flag and the signal whatever
+     * stop did. The paired release calls it; so does {@link shutdown}, since a tool torn down
+     * mid-gesture must still get its stop, and a host that closes a record per gesture (the
+     * scene editor's project session) must hear the end.
+     */
+    /**
+     * Hand a gesture to a tool: the flag goes up, the signal fires, the tool starts. The pointer's
+     * primary press calls it; so may a host that drives a tool without a pointer (a scripted
+     * stroke, a spec). A gesture already in progress ends first.
+     * @param {Tool} tool
+     */
+    start_gesture(tool: Tool): void;
+    end_gesture(): void;
     shutdown(): void;
+    #private;
 }
 import List from '../../../src/core/collection/list/List.js';
 import ObservedValue from '../../../src/core/model/ObservedValue.js';
+import Signal from '../../../src/core/events/signal/Signal.js';
 //# sourceMappingURL=ToolEngine.d.ts.map

package/editor/tools/engine/ToolEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ToolEngine.d.ts","sourceRoot":"","sources":["../../../../editor/tools/engine/ToolEngine.js"],"names":[],"mappings":";AAWA;IACI,iBAAmB;IACnB,sBAAiC;IACjC,YAAc;IACd,mBAAkB;IAClB,yBAAuB;IACvB,aAAe;IAUf,8BAOC;IAED,mBA8BC;IAED;;;;OAIG;IACH,8CA4FC;IA1FG,eAAoB;IA4FxB,iBAgBC;CACJ;iBAxLgB,2CAA2C;0BAClC,0CAA0C"}
+{"version":3,"file":"ToolEngine.d.ts","sourceRoot":"","sources":["../../../../editor/tools/engine/ToolEngine.js"],"names":[],"mappings":";AAYA;IACI,iBAAmB;IACnB,sBAAiC;IACjC,YAAc;IACd,mBAAkB;IAClB,yBAAuB;IACvB,aAAe;IA2Bf;;;OAGG;IACH,gBAFU,MAAM,CAEc;IAE9B;;;OAGG;IACH,cAFU,MAAM,CAEY;IAE5B;;OAEG;IACH,8BAEC;IAED,8BAOC;IAED,mBA8BC;IAED;;;;OAIG;IACH,8CA2EC;IAzEG,eAAoB;IA2ExB;;;;;OAKG;IACH;;;;;OAKG;IACH,gCAUC;IAED,oBAeC;IAED,iBAwBC;;CACJ;iBA7PgB,2CAA2C;0BAElC,0CAA0C;mBADjD,2CAA2C"}

package/editor/tools/engine/ToolEngine.js

@@ -1,188 +1,257 @@
-import List from '../../../src/core/collection/list/List.js';
-import ObservedValue from '../../../src/core/model/ObservedValue.js';
-import { decodeMouseEventButtons } from "../../../src/engine/input/devices/mouse/decodeMouseEventButtons.js";
-import { PointerDevice } from '../../../src/engine/input/devices/PointerDevice.js';
-import GridPaintTool from "../GridPaintTool.js";
-import { TerrainHeightPaintTool } from "../paint/TerrainHeightPaintTool.js";
-import { TerrainTexturePaintTool } from "../paint/TerrainTexturePaintTool.js";
-
-import SelectionTool from '../SelectionTool.js';
-import { TransformToolV2 } from "../TransformToolV2.js";
-
-class ToolEngine {
-    tools = new List();
-    active = new ObservedValue(null);
-    engine = null;
-    isRunning = false;
-    shutdownCallbacks = [];
-    pointer = null;
-
-    /**
-     *
-     * @constructor
-     * @property {List.<Tool>} tools
-     * @property {ObservedValue.<Tool>} active
-     */
-    constructor() {}
-
-    activate(toolName) {
-        const self = this;
-        this.tools.visitFirstMatch(function (tool) {
-            return tool.name === toolName;
-        }, function (tool) {
-            self.active.set(tool);
-        });
-    }
-
-    initialize() {
-
-        this.active.onChanged.add((newTool, oldTool) => {
-            if (oldTool !== null && typeof oldTool === "object") {
-                oldTool.finalize();
-            }
-
-            if (newTool !== null && typeof newTool === "object") {
-                newTool.editor = this.editor;
-                newTool.engine = this.engine;
-
-                newTool.initialize();
-            }
-        });
-
-        const terrainPaintToolRaise = new TerrainHeightPaintTool();
-        terrainPaintToolRaise.name = "terrain-height";
-
-        const terrainTexturePaintTool = new TerrainTexturePaintTool();
-        terrainTexturePaintTool.name = "terrain-texture";
-
-        const tools = this.tools;
-        tools
-            .add(new SelectionTool())
-            .add(new GridPaintTool())
-            .add(terrainPaintToolRaise)
-            .add(terrainTexturePaintTool)
-        ;
-
-        tools.add(new TransformToolV2());
-    }
-
-    /**
-     *
-     * @param {Engine} engine
-     * @param {Editor} editor
-     */
-    startup(engine, editor) {
-        this.engine = engine;
-        this.editor = editor;
-        this.isRunning = true;
-
-        const self = this;
-
-        // tools tick with the engine, not on a private animation loop
-        function update(delta) {
-            const tool = self.active.get();
-
-            if (tool !== null) {
-                tool.update(delta);
-            }
-        }
-
-        engine.ticker.onTick.add(update);
-
-        this.shutdownCallbacks.push(function () {
-            engine.ticker.onTick.remove(update);
-        });
-
-        const graphics = engine.graphics;
-
-        if (graphics === null || graphics.domElement === undefined || graphics.domElement === null) {
-            // headless engine: no viewport to receive pointer input
-            return;
-        }
-
-        const pointer = this.pointer = new PointerDevice(graphics.domElement);
-
-        /**
-         * The tool a gesture was handed to by the last accepted press, null between gestures.
-         * `stop()` finishes work `start()` began — a marquee, a brush stroke — so it must
-         * only ever run against the press it pairs with. Camera navigation shares this
-         * viewport and presses the other buttons constantly.
-         * @type {Tool|null}
-         */
-        let gesture_tool = null;
-
-        //hook up interaction controls
-        function pointerDown(position, event) {
-            const tool = self.active.get();
-            if (tool !== null) {
-                tool.modifiers.shift = event.shiftKey;
-
-                if (typeof event.buttons === "number") {
-                    const decodedButtons = decodeMouseEventButtons(event.buttons);
-
-                    const isPrimaryPressed = decodedButtons[0];
-
-                    if (!isPrimaryPressed) {
-                        //tools own the primary button only; navigation owns the rest
-                        return;
-                    }
-
-                }
-
-                gesture_tool = tool;
-
-                tool.start();
-            }
-        }
-
-        function pointerUp(position, event) {
-            const tool = gesture_tool;
-
-            gesture_tool = null;
-
-            if (tool !== null) {
-                tool.stop();
-            }
-        }
-
-
-        pointer.on.down.add(pointerDown);
-
-        // a release outside the viewport still ends the gesture: dragging a marquee or a brush
-        // stroke past the edge of the canvas and letting go there is ordinary, and the tool
-        // would otherwise stay running until the next release that happened to land inside
-        pointer.on.globalUp.add(pointerUp);
-
-        pointer.start();
-
-
-        function cleanup() {
-            pointer.on.down.remove(pointerDown);
-            pointer.on.globalUp.remove(pointerUp);
-            pointer.stop();
-        }
-
-        this.shutdownCallbacks.push(cleanup);
-    }
-
-    shutdown() {
-        this.isRunning = false;
-        const toolProxy = this.active;
-
-        const tool = toolProxy.getValue();
-
-        if (tool !== null) {
-            toolProxy.set(null);
-        }
-
-        //execute cleanup
-        this.shutdownCallbacks.forEach(function (cb) {
-            cb();
-        });
-
-        this.shutdownCallbacks = [];
-    }
-}
-
-
-export default ToolEngine;
+import List from '../../../src/core/collection/list/List.js';
+import Signal from '../../../src/core/events/signal/Signal.js';
+import ObservedValue from '../../../src/core/model/ObservedValue.js';
+import { decodeMouseEventButtons } from "../../../src/engine/input/devices/mouse/decodeMouseEventButtons.js";
+import { PointerDevice } from '../../../src/engine/input/devices/PointerDevice.js';
+import GridPaintTool from "../GridPaintTool.js";
+import { TerrainHeightPaintTool } from "../paint/TerrainHeightPaintTool.js";
+import { TerrainTexturePaintTool } from "../paint/TerrainTexturePaintTool.js";
+
+import SelectionTool from '../SelectionTool.js';
+import { TransformToolV2 } from "../TransformToolV2.js";
+
+class ToolEngine {
+    tools = new List();
+    active = new ObservedValue(null);
+    engine = null;
+    isRunning = false;
+    shutdownCallbacks = [];
+    pointer = null;
+
+    /**
+     *
+     * @constructor
+     * @property {List.<Tool>} tools
+     * @property {ObservedValue.<Tool>} active
+     */
+    constructor() {}
+
+    /**
+     * True from the press that hands a gesture to a tool until the release that ends it. A host
+     * grouping actions into one undo step per gesture (a brush stroke is one step, however many
+     * dabs) reads this rather than second-guessing the pointer.
+     * @type {boolean}
+     */
+    #gesture_active = false;
+
+    /**
+     * The tool a gesture was handed to by the last accepted press, null between gestures.
+     * `stop()` finishes work `start()` began — a marquee, a brush stroke — so it must only ever
+     * run against the press it pairs with. Camera navigation shares this viewport and presses
+     * the other buttons constantly.
+     * @type {Tool|null}
+     */
+    #gesture_tool = null;
+
+    /**
+     * Fired with the tool when a gesture starts (primary-button press accepted by a tool).
+     * @type {Signal}
+     */
+    onGestureStart = new Signal();
+
+    /**
+     * Fired with the tool when its gesture ends (the paired release), after `tool.stop()`.
+     * @type {Signal}
+     */
+    onGestureEnd = new Signal();
+
+    /**
+     * @returns {boolean}
+     */
+    get gesture_active() {
+        return this.#gesture_active;
+    }
+
+    activate(toolName) {
+        const self = this;
+        this.tools.visitFirstMatch(function (tool) {
+            return tool.name === toolName;
+        }, function (tool) {
+            self.active.set(tool);
+        });
+    }
+
+    initialize() {
+
+        this.active.onChanged.add((newTool, oldTool) => {
+            if (oldTool !== null && typeof oldTool === "object") {
+                oldTool.finalize();
+            }
+
+            if (newTool !== null && typeof newTool === "object") {
+                newTool.editor = this.editor;
+                newTool.engine = this.engine;
+
+                newTool.initialize();
+            }
+        });
+
+        const terrainPaintToolRaise = new TerrainHeightPaintTool();
+        terrainPaintToolRaise.name = "terrain-height";
+
+        const terrainTexturePaintTool = new TerrainTexturePaintTool();
+        terrainTexturePaintTool.name = "terrain-texture";
+
+        const tools = this.tools;
+        tools
+            .add(new SelectionTool())
+            .add(new GridPaintTool())
+            .add(terrainPaintToolRaise)
+            .add(terrainTexturePaintTool)
+        ;
+
+        tools.add(new TransformToolV2());
+    }
+
+    /**
+     *
+     * @param {Engine} engine
+     * @param {Editor} editor
+     */
+    startup(engine, editor) {
+        this.engine = engine;
+        this.editor = editor;
+        this.isRunning = true;
+
+        const self = this;
+
+        // tools tick with the engine, not on a private animation loop
+        function update(delta) {
+            const tool = self.active.get();
+
+            if (tool !== null) {
+                tool.update(delta);
+            }
+        }
+
+        engine.ticker.onTick.add(update);
+
+        this.shutdownCallbacks.push(function () {
+            engine.ticker.onTick.remove(update);
+        });
+
+        const graphics = engine.graphics;
+
+        if (graphics === null || graphics.domElement === undefined || graphics.domElement === null) {
+            // headless engine: no viewport to receive pointer input
+            return;
+        }
+
+        const pointer = this.pointer = new PointerDevice(graphics.domElement);
+
+        //hook up interaction controls
+        function pointerDown(position, event) {
+            const tool = self.active.get();
+            if (tool !== null) {
+                tool.modifiers.shift = event.shiftKey;
+
+                if (typeof event.buttons === "number") {
+                    const decodedButtons = decodeMouseEventButtons(event.buttons);
+
+                    const isPrimaryPressed = decodedButtons[0];
+
+                    if (!isPrimaryPressed) {
+                        //tools own the primary button only; navigation owns the rest
+                        return;
+                    }
+
+                }
+
+                self.start_gesture(tool);
+            }
+        }
+
+        function pointerUp(position, event) {
+            self.end_gesture();
+        }
+
+
+        pointer.on.down.add(pointerDown);
+
+        // a release outside the viewport still ends the gesture: dragging a marquee or a brush
+        // stroke past the edge of the canvas and letting go there is ordinary, and the tool
+        // would otherwise stay running until the next release that happened to land inside
+        pointer.on.globalUp.add(pointerUp);
+
+        pointer.start();
+
+
+        function cleanup() {
+            pointer.on.down.remove(pointerDown);
+            pointer.on.globalUp.remove(pointerUp);
+            pointer.stop();
+        }
+
+        this.shutdownCallbacks.push(cleanup);
+    }
+
+    /**
+     * End the gesture in progress, if any: `tool.stop()`, then the flag and the signal whatever
+     * stop did. The paired release calls it; so does {@link shutdown}, since a tool torn down
+     * mid-gesture must still get its stop, and a host that closes a record per gesture (the
+     * scene editor's project session) must hear the end.
+     */
+    /**
+     * Hand a gesture to a tool: the flag goes up, the signal fires, the tool starts. The pointer's
+     * primary press calls it; so may a host that drives a tool without a pointer (a scripted
+     * stroke, a spec). A gesture already in progress ends first.
+     * @param {Tool} tool
+     */
+    start_gesture(tool) {
+        if (this.#gesture_tool !== null) {
+            this.end_gesture();
+        }
+
+        this.#gesture_tool = tool;
+        this.#gesture_active = true;
+        this.onGestureStart.send1(tool);
+
+        tool.start();
+    }
+
+    end_gesture() {
+        const tool = this.#gesture_tool;
+
+        this.#gesture_tool = null;
+
+        if (tool === null) {
+            return;
+        }
+
+        try {
+            tool.stop();
+        } finally {
+            this.#gesture_active = false;
+            this.onGestureEnd.send1(tool);
+        }
+    }
+
+    shutdown() {
+        // before the tool is deactivated: its stop hook may still commit through the editor. A
+        // hook that throws has still ended its gesture; the teardown goes on
+        try {
+            this.end_gesture();
+        } catch (e) {
+            console.error(`ToolEngine.shutdown: the gesture's stop hook failed: ${e.message}`);
+        }
+
+        this.isRunning = false;
+        const toolProxy = this.active;
+
+        const tool = toolProxy.getValue();
+
+        if (tool !== null) {
+            toolProxy.set(null);
+        }
+
+        //execute cleanup
+        this.shutdownCallbacks.forEach(function (cb) {
+            cb();
+        });
+
+        this.shutdownCallbacks = [];
+    }
+}
+
+
+export default ToolEngine;

package/editor/view/ecs/EntityList.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EntityList.d.ts","sourceRoot":"","sources":["../../../../editor/view/ecs/EntityList.js"],"names":[],"mappings":";AA4DA;IAGI;;;;OAIG;IACH,4CAmJC;IA1JD,mBAAmC;IAgB3B,OAAY;IAQhB,eAAoB;IAuGpB;;;;;;MAUC;IAmBL,eAEC;CAsCJ;iBAzPgB,2BAA2B"}
+{"version":3,"file":"EntityList.d.ts","sourceRoot":"","sources":["../../../../editor/view/ecs/EntityList.js"],"names":[],"mappings":";AA6DA;IAGI;;;;OAIG;IACH,4CAmJC;IA1JD,mBAAmC;IAgB3B,OAAY;IAQhB,eAAoB;IAuGpB;;;;;;MAUC;IAmBL,eAEC;CAsCJ;iBA1PgB,2BAA2B"}

package/editor/view/ecs/EntityList.js

@@ -8,6 +8,7 @@ import ButtonView from '../../../src/view/elements/button/ButtonView.js';
 import EmptyView from "../../../src/view/elements/EmptyView.js";
 import View from "../../../src/view/View.js";
 
+import EntityCreateAction from '../../actions/concrete/EntityCreateAction.js';
 import SelectionAddAction from '../../actions/concrete/SelectionAddAction.js';
 import SelectionRemoveAction from '../../actions/concrete/SelectionRemoveAction.js';
 
@@ -133,11 +134,11 @@ class EntityListView extends View {
         const actionAdd = {
             name: "Add",
             action: function () {
-                const dataset = editor.engine.entityManager.dataset;
-
-                if (dataset !== null) {
-                    dataset.createEntity();
-                }
+                // through an action: undoable, and a host that leases entity ids assigns one before
+                // apply (a direct createEntity would take the lowest free id and bypass both)
+                const actions = editor.actions;
+                actions.mark('add entity');
+                actions.do(new EntityCreateAction());
             }
         };
 

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

@@ -1 +1 @@
-{"version":3,"file":"ParticleEmitterInspectorView.d.ts","sourceRoot":"","sources":["../../../../../editor/view/particles/effect/ParticleEmitterInspectorView.js"],"names":[],"mappings":"AA+DA;IAkDI;;;OAGG;IACH;QAFyG,MAAM,EAApG,OAAO,qDAAqD,EAAE,sBAAsB;OAqC9F;IAhCG,mBAAuC;IAIvC;;OAEG;IACH,QAFU,OAAO,qDAAqD,EAAE,sBAAsB,CAE1E;IA2BxB;;;;;;OAMG;IACH,gBAiBC;;CAmZJ;iBA3jBgB,8BAA8B"}
+{"version":3,"file":"ParticleEmitterInspectorView.d.ts","sourceRoot":"","sources":["../../../../../editor/view/particles/effect/ParticleEmitterInspectorView.js"],"names":[],"mappings":"AAyEA;IAkDI;;;OAGG;IACH;QAFyG,MAAM,EAApG,OAAO,qDAAqD,EAAE,sBAAsB;OAqC9F;IAhCG,mBAAuC;IAIvC;;OAEG;IACH,QAFU,OAAO,qDAAqD,EAAE,sBAAsB,CAE1E;IA2BxB;;;;;;OAMG;IACH,gBAiBC;;CAiZJ;iBAnkBgB,8BAA8B"}

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

@@ -12,8 +12,12 @@ import View from "../../../../src/view/View.js";
 
 /**
  * Everything about an effect that is not its simulation: how fast it emits, how its particles are
- * blended and oriented, which per-particle attribute drives which render channel, its bounds sphere,
- * and the attribute schema those channels can name.
+ * blended and oriented, which per-particle attribute drives which render channel, and the attribute
+ * schema those channels can name.
+ *
+ * There is nothing here for bounds. An emitter has none to declare — the box the culling and
+ * occupancy passes use is measured from the live particles on the GPU — so the one bounds-related
+ * control an author gets is the `cull` toggle.
  *
  * It belongs to neither editing layer, and both need it — a program that writes `position` does
  * nothing visible until something says that `position` is what the renderer should place the quad
@@ -41,12 +45,13 @@ const NUMERIC_FIELDS = [
         help: "Particles per second. Integrated on the GPU — the CPU never counts particles.",
     },
     {
-        key: "bounds_radius",
-        label: "bounds radius",
+        key: "prewarm",
+        label: "pre-warm",
         min: 0,
         step: 0.1,
-        help: "Radius of the emitter's bounding sphere. Under AVBOIT it marks the depth slices the "
-            + "effect may occlude in, so an effect that outruns it occludes at the wrong depth.",
+        help: "Seconds the effect is run forward before it is first shown, so a continuous one arrives "
+            + "at its steady population instead of growing into it. About the particle lifetime is "
+            + "enough; longer only costs a longer warm-up on the frame the effect appears. 0 is off.",
     },
 ];
 
@@ -58,7 +63,12 @@ const FLAG_FIELDS = [
     { key: "lighting", label: "lighting", help: "Forward-shade the billboards with scene lighting." },
     { key: "soft_depth", label: "soft depth", help: "Fade against scene depth instead of cutting into it." },
     { key: "sort", label: "sort", help: "Depth-sort this emitter's particles." },
-    { key: "cull", label: "cull", help: "Sleep the simulation when the emitter is out of view." },
+    {
+        key: "cull",
+        label: "cull",
+        help: "Sleep the simulation when the emitter is out of view. The box tested is measured from "
+            + "the live particles on the GPU, so there is nothing here to size by hand.",
+    },
 ];
 
 export class ParticleEmitterInspectorView extends View {
@@ -212,8 +222,6 @@ export class ParticleEmitterInspectorView extends View {
             section.addChild(this.#numericRow(field));
         }
 
-        section.addChild(this.#vectorRow("bounds centre", "bounds_center", 3));
-
         return section;
     }
 

package/package.json

@@ -6,7 +6,7 @@
   "description": "Advanced 3D game engine",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "3.17.1",
+  "version": "3.18.0",
   "exports": {
     "./build/*": "./build/*",
     "./src/*": "./src/*",

package/src/CODEC_LAYOUT_VERIFICATION.md

@@ -162,8 +162,7 @@ grep -rln "binary/lz4\|binary/zstd" --include=*.js . | grep -v "^./core/binary/"
 # shade/renderer/geometry/virtual/format/frame/vgeo_*.js    (zstd, three files)
 # shade/renderer/loader/usd/usd_lz4.js                      (lz4)
 grep -rn "binary/meshopt" --include=*.js . | grep -v "^./core/binary/meshopt/" | grep -v spec
-# shade/renderer/loader/gltf/ext/meshopt/MeshoptBufferViewExtension.js   (three imports)
-# engine/asset/loaders/gltf_test_fixtures.js                             (test-only encoder)
+# format/scene/gltf/ext/meshopt/MeshoptBufferViewExtension.js            (three imports)
 ```
 
 zstd is shared between KTX2 and the virtual-geometry frame format; lz4 is USD-only today; meshopt is