@woosh/meep-engine 2.169.4 → 2.170.0

package/editor/tools/engine/Tool.js

@@ -5,36 +5,38 @@ import { ToolState } from "./ToolState.js";
 class Tool {
     #state = ToolState.Initial;
 
+    name = null;
+    mode = new ObservedValue();
+    settings = {};
+    modifiers = {
+        shift: false,
+        alternative: false
+    };
+
+    /**
+     *
+     * @type {Engine|null}
+     */
+    engine = null;
+
+    /**
+     *
+     * @type {Editor|null}
+     */
+    editor = null;
+
+    /**
+     *
+     * @type {ObservedString}
+     */
+    icon = new ObservedString("");
+
     /**
      *
      * @constructor
      * @property {ObservedValue.<String>} mode
      */
-    constructor() {
-        this.name = null;
-        this.mode = new ObservedValue();
-        this.settings = {};
-        this.modifiers = {
-            shift: false,
-            alternative: false
-        };
-        /**
-         *
-         * @type {Engine|null}
-         */
-        this.engine = null;
-        /**
-         *
-         * @type {Editor|null}
-         */
-        this.editor = null;
-
-        /**
-         *
-         * @type {ObservedString}
-         */
-        this.icon = new ObservedString("");
-    }
+    constructor() {}
 
     /**
      *
@@ -44,6 +46,17 @@ class Tool {
 
     }
 
+    /**
+     * Optional bespoke section rendered below the reflected settings rows, for controls a
+     * plain value row cannot express (e.g. a layer swatch picker).
+     *
+     * @param {Editor} editor
+     * @returns {View|null} null when the tool has no custom section
+     */
+    buildCustomSettingsView(editor) {
+        return null;
+    }
+
     /**
      *
      * @returns {ToolState|number}
@@ -78,19 +91,50 @@ class Tool {
     }
 
     /**
-     * Start usage of the tool.
+     * Start usage of the tool. Called by {@link ToolEngine} when a gesture is handed over.
+     * Subclasses put their own work in {@link Tool#handleStart} instead of overriding this,
+     * so the running state cannot be left behind.
+     *
      * @example Start painting with a brush
      */
     start() {
         this.#state = ToolState.Running;
+
+        this.handleStart();
     }
 
     /**
-     * Finish usage of the tool
+     * Finish usage of the tool. As with {@link Tool#start}, subclasses override
+     * {@link Tool#handleStop} rather than this.
+     *
      * @example Finish brush stroke
      */
     stop() {
-        this.#state = ToolState.Ready;
+        try {
+            this.handleStop();
+        } finally {
+            // whatever the hook did — commit an action, throw — the gesture is over. A tool
+            // left Running would poison every gesture after it, and the failure still
+            // propagates: this restores the invariant, it does not swallow anything.
+            this.#state = ToolState.Ready;
+        }
+    }
+
+    /**
+     * Open a gesture. The tool is already {@link ToolState.Running} here, so work kicked off
+     * from this hook — an immediate first brush dab, say — observes the same state a later
+     * {@link Tool#update} would.
+     */
+    handleStart() {
+
+    }
+
+    /**
+     * Close the gesture {@link Tool#handleStart} opened and commit whatever it accumulated.
+     * Still {@link ToolState.Running} here; the tool is Ready once this returns.
+     */
+    handleStop() {
+
     }
 
     handleKeyboardEvent(e) {

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

@@ -1,23 +1,22 @@
-export default ToolEngine;
-declare class ToolEngine {
-    tools: List<any>;
-    active: ObservedValue;
-    engine: any;
-    isRunning: boolean;
-    shutdownCallbacks: any[];
-    pointer: PointerDevice;
-    activate(toolName: any): void;
-    initialize(): void;
-    /**
-     *
-     * @param {Engine} engine
-     * @param {Editor} editor
-     */
-    startup(engine: Engine, editor: Editor): void;
-    editor: Editor;
-    shutdown(): void;
-}
-import List from '../../../src/core/collection/list/List.js';
-import ObservedValue from '../../../src/core/model/ObservedValue.js';
-import { PointerDevice } from '../../../src/engine/input/devices/PointerDevice.js';
+export default ToolEngine;
+declare class ToolEngine {
+    tools: List<any>;
+    active: ObservedValue;
+    engine: any;
+    isRunning: boolean;
+    shutdownCallbacks: any[];
+    pointer: any;
+    activate(toolName: any): void;
+    initialize(): void;
+    /**
+     *
+     * @param {Engine} engine
+     * @param {Editor} editor
+     */
+    startup(engine: Engine, editor: Editor): void;
+    editor: Editor;
+    shutdown(): void;
+}
+import List from '../../../src/core/collection/list/List.js';
+import ObservedValue from '../../../src/core/model/ObservedValue.js';
 //# sourceMappingURL=ToolEngine.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ToolEngine.d.ts","sourceRoot":"","sources":["ToolEngine.js"],"names":[],"mappings":";AAaA;IAQQ,iBAAuB;IACvB,sBAAqC;IACrC,YAAkB;IAClB,mBAAsB;IACtB,yBAA2B;IAC3B,uBAAmB;IAGvB,8BAOC;IAED,mBAgDC;IAED;;;;OAIG;IACH,8CAyEC;IAvEG,eAAoB;IAyExB,iBAgBC;CACJ;iBAzLgB,2CAA2C;0BAClC,0CAA0C;8BAGtC,oDAAoD"}
+{"version":3,"file":"ToolEngine.d.ts","sourceRoot":"","sources":["ToolEngine.js"],"names":[],"mappings":";AAWA;IACI,iBAAmB;IACnB,sBAAiC;IACjC,YAAc;IACd,mBAAkB;IAClB,yBAAuB;IACvB,aAAe;IAUf,8BAOC;IAED,mBA6BC;IAED;;;;OAIG;IACH,8CA4FC;IA1FG,eAAoB;IA4FxB,iBAgBC;CACJ;iBAvLgB,2CAA2C;0BAClC,0CAA0C"}

package/editor/tools/engine/ToolEngine.js

@@ -1,6 +1,5 @@
 import List from '../../../src/core/collection/list/List.js';
 import ObservedValue from '../../../src/core/model/ObservedValue.js';
-import Clock from "../../../src/engine/Clock.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";
@@ -8,24 +7,23 @@ import { TerrainHeightPaintTool } from "../paint/TerrainHeightPaintTool.js";
 import { TerrainTexturePaintTool } from "../paint/TerrainTexturePaintTool.js";
 
 import SelectionTool from '../SelectionTool.js';
-import TopDownCameraControlTool from '../TopDownCameraControlTool.js';
-import { TransformTool } from "../TransformTool.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() {
-        this.tools = new List();
-        this.active = new ObservedValue(null);
-        this.engine = null;
-        this.isRunning = false;
-        this.shutdownCallbacks = [];
-        this.pointer = null;
-    }
+    constructor() {}
 
     activate(toolName) {
         const self = this;
@@ -39,8 +37,6 @@ class ToolEngine {
     initialize() {
 
         this.active.onChanged.add((newTool, oldTool) => {
-            console.log("active tool changed. Old: ", oldTool, ", New :", newTool);
-
             if (oldTool !== null && typeof oldTool === "object") {
                 oldTool.finalize();
             }
@@ -56,33 +52,16 @@ class ToolEngine {
         const terrainPaintToolRaise = new TerrainHeightPaintTool();
         terrainPaintToolRaise.name = "terrain-height";
 
-        const terrainTexturePaintTool0 = new TerrainTexturePaintTool();
-        terrainTexturePaintTool0.name = `terrain-texture-0`;
-        terrainTexturePaintTool0.settings.splatIndex = 0;
-
-        const terrainTexturePaintTool1 = new TerrainTexturePaintTool();
-        terrainTexturePaintTool1.name = `terrain-texture-1`;
-        terrainTexturePaintTool1.settings.splatIndex = 1;
-
-        const terrainTexturePaintTool2 = new TerrainTexturePaintTool();
-        terrainTexturePaintTool2.name = `terrain-texture-2`;
-        terrainTexturePaintTool2.settings.splatIndex = 2;
-
-        const terrainTexturePaintTool3 = new TerrainTexturePaintTool();
-        terrainTexturePaintTool3.name = `terrain-texture-3`;
-        terrainTexturePaintTool3.settings.splatIndex = 3;
+        const terrainTexturePaintTool = new TerrainTexturePaintTool();
+        terrainTexturePaintTool.name = "terrain-texture";
 
         const tools = this.tools;
         tools
             .add(new SelectionTool())
-            .add(new TopDownCameraControlTool())
             .add(new GridPaintTool())
-            .add(new TransformTool())
+            .add(new TransformToolV2())
             .add(terrainPaintToolRaise)
-            .add(terrainTexturePaintTool0)
-            .add(terrainTexturePaintTool1)
-            .add(terrainTexturePaintTool2)
-            .add(terrainTexturePaintTool3)
+            .add(terrainTexturePaintTool)
         ;
     }
 
@@ -95,31 +74,41 @@ class ToolEngine {
         this.engine = engine;
         this.editor = editor;
         this.isRunning = true;
-        const pointer = this.pointer = new PointerDevice(engine.graphics.domElement);
 
         const self = this;
 
-        const clock = new Clock();
-
-        clock.start();
-
-        function update() {
-            if (!self.isRunning) {
-                return;
-            }
-            requestAnimationFrame(update);
-
+        // tools tick with the engine, not on a private animation loop
+        function update(delta) {
             const tool = self.active.get();
 
-            const delta = clock.getDelta();
-
             if (tool !== null) {
                 tool.update(delta);
             }
         }
 
-        //start update loop
-        update();
+        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) {
@@ -133,33 +122,42 @@ class ToolEngine {
                     const isPrimaryPressed = decodedButtons[0];
 
                     if (!isPrimaryPressed) {
-                        //when working with mouse, only activate on primary mouse button
+                        //tools own the primary button only; navigation owns the rest
                         return;
                     }
 
                 }
 
+                gesture_tool = tool;
+
                 tool.start();
             }
         }
 
         function pointerUp(position, event) {
-            const tool = self.active.get();
-            if (tool !== null) {
+            const tool = gesture_tool;
+
+            gesture_tool = null;
 
+            if (tool !== null) {
                 tool.stop();
             }
         }
 
 
         pointer.on.down.add(pointerDown);
-        pointer.on.up.add(pointerUp);
+
+        // 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.up.remove(pointerUp);
+            pointer.on.globalUp.remove(pointerUp);
             pointer.stop();
         }
 

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

@@ -1,7 +1,7 @@
-export type ToolState = number;
-export namespace ToolState {
-    let Initial: number;
-    let Ready: number;
-    let Running: number;
-}
+export type ToolState = number;
+export namespace ToolState {
+    let Initial: number;
+    let Ready: number;
+    let Running: number;
+}
 //# sourceMappingURL=ToolState.d.ts.map

package/editor/tools/paint/TerrainHeightPaintTool.d.ts

@@ -1,18 +1,18 @@
-export class TerrainHeightPaintTool extends TerrainPaintTool {
-    /**
-     *
-     * @type {QuadTreeNode<number>}
-     */
-    transform_index: QuadTreeNode<number>;
-    buildTransformIndex(): void;
-    /**
-     *
-     * @param {PatchTerrainHeightAction} action
-     * @returns {Action[]}
-     */
-    createObjectMoveActions(action: PatchTerrainHeightAction): Action[];
-}
-import { TerrainPaintTool } from "./TerrainPaintTool.js";
-import { QuadTreeNode } from "../../../src/core/geom/2d/quad-tree/QuadTreeNode.js";
-import { PatchTerrainHeightAction } from "../../actions/concrete/PatchTerrainHeightAction.js";
+export class TerrainHeightPaintTool extends TerrainPaintTool {
+    /**
+     *
+     * @type {QuadTreeNode<number>}
+     */
+    transform_index: QuadTreeNode<number>;
+    buildTransformIndex(): void;
+    /**
+     *
+     * @param {PatchTerrainHeightAction} action
+     * @returns {Action[]}
+     */
+    createObjectMoveActions(action: PatchTerrainHeightAction): Action[];
+}
+import { TerrainPaintTool } from "./TerrainPaintTool.js";
+import { QuadTreeNode } from "../../../src/core/geom/2d/quad-tree/QuadTreeNode.js";
+import { PatchTerrainHeightAction } from "../../actions/concrete/PatchTerrainHeightAction.js";
 //# sourceMappingURL=TerrainHeightPaintTool.d.ts.map

package/editor/tools/paint/TerrainHeightPaintTool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TerrainHeightPaintTool.d.ts","sourceRoot":"","sources":["TerrainHeightPaintTool.js"],"names":[],"mappings":"AAuFA;IAQQ;;;OAGG;IACH,iBAFU,aAAa,MAAM,CAAC,CAEW;IAG7C,4BAiDC;IA8DD;;;;OAIG;IACH,gCAHW,wBAAwB,GACtB,QAAQ,CAwEpB;CAQJ;iCA/RgC,uBAAuB;6BAR3B,qDAAqD;yCAKzC,oDAAoD"}
+{"version":3,"file":"TerrainHeightPaintTool.d.ts","sourceRoot":"","sources":["TerrainHeightPaintTool.js"],"names":[],"mappings":"AA8FA;IAQQ;;;OAGG;IACH,iBAFU,aAAa,MAAM,CAAC,CAEW;IAG7C,4BAiDC;IA8CD;;;;OAIG;IACH,gCAHW,wBAAwB,GACtB,QAAQ,CAwEpB;CAaJ;iCA3RgC,uBAAuB;6BAR3B,qDAAqD;yCAKzC,oDAAoD"}

package/editor/tools/paint/TerrainHeightPaintTool.js

@@ -160,9 +160,6 @@ export class TerrainHeightPaintTool extends TerrainPaintTool {
 
     initialize() {
         super.initialize();
-
-        this.buildTransformIndex();
-
     }
 
     finalize() {
@@ -195,11 +192,14 @@ export class TerrainHeightPaintTool extends TerrainPaintTool {
 
         const action = make_mod_action(terrain, scratch_uv_rect, marker, value_delta, limitMin, limitMax);
 
+        // move actions must be computed from pre-patch heights, so the patch action is
+        // enqueued (not yet applied) while they are derived; awaiting the tail lets the
+        // base class's paint-pending gate actually pace the strokes
         this.editor.actions.do(action);
 
         const objectMoveActions = this.createObjectMoveActions(action);
 
-        this.editor.actions.doMany(objectMoveActions);
+        await this.editor.actions.doMany(objectMoveActions);
     }
 
     /**
@@ -256,7 +256,7 @@ export class TerrainHeightPaintTool extends TerrainPaintTool {
             const tY = leaf.y0 * heightSampler.height;
 
             const action_value = action.patch.sampleChannelBicubic(tX - action.x, tY - action.y, 0);
-            const existing_value = heightSampler.sampleChannelBicubic(tY, tY, 0);
+            const existing_value = heightSampler.sampleChannelBicubic(tX, tY, 0);
 
             const delta = action_value - existing_value;
 
@@ -279,8 +279,13 @@ export class TerrainHeightPaintTool extends TerrainPaintTool {
         return result;
     }
 
-    start() {
-        super.start();
+    handleStart() {
+        if (this.terrain === null) {
+            return;
+        }
+
+        // entities move between strokes; the height-follow index is only valid per stroke
+        this.buildTransformIndex();
 
         this.editor.actions.mark('terrain height paint');
     }

package/editor/tools/paint/TerrainPaintTool.d.ts

@@ -1,31 +1,82 @@
-export class TerrainPaintTool extends Tool {
-    name: string;
-    __brushPosition: Vector2;
-    __brushImage: HTMLCanvasElement;
-    __paint_debt: number;
-    __paint_pending: boolean;
-    /**
-     *
-     * @param {number} timeDelta
-     */
-    paint(timeDelta: number): Promise<void>;
-    /**
-     *
-     * @param {number} timeDelta
-     */
-    update(timeDelta: number): void;
-    updateBrushImage(): void;
-    updateBrushPosition(): void;
-    updateOverlay(): void;
-    /**
-     *
-     * @param {Vector3} delta
-     * @private
-     */
-    private __handleMouseWheel;
-    terrain: import("../../../src/engine/ecs/terrain/ecs/Terrain.js").default;
-    terrainEntity: any;
-}
-import Tool from "../engine/Tool.js";
-import Vector2 from "../../../src/core/geom/Vector2.js";
+export class TerrainPaintTool extends Tool {
+    /**
+     * Scale a UV rect into the continuous texel space of a sampler of the given dimensions.
+     *
+     * Kept separate from {@link TerrainPaintTool#computeBrushUVRect} because the terrain's
+     * heightmap, splat map and overlay all have different resolutions, and each one converts the
+     * same UV footprint into its own domain.
+     *
+     * `result` may be the same array as `uv_rect`.
+     *
+     * @param {Float64Array|number[]} result `[x0, y0, x1, y1]` in texels
+     * @param {Float64Array|number[]} uv_rect `[x0, y0, x1, y1]` in UV
+     * @param {number} width sampler width in texels
+     * @param {number} height sampler height in texels
+     */
+    static uvRectToTexelRect(result: Float64Array | number[], uv_rect: Float64Array | number[], width: number, height: number): void;
+    /**
+     * Snap a continuous texel rect to the integer texel range that lies fully inside it: low bounds
+     * round up, high bounds round down. Written out once because the two paint tools iterate the
+     * resulting range with `for (x = x0; x < x1; x++)` and must agree on which texels a brush
+     * covers.
+     *
+     * `result` may be the same array as `texel_rect`.
+     *
+     * @param {Float64Array|number[]} result `[x0, y0, x1, y1]`, x1/y1 exclusive
+     * @param {Float64Array|number[]} texel_rect `[x0, y0, x1, y1]`
+     */
+    static texelRectToIntegerRect(result: Float64Array | number[], texel_rect: Float64Array | number[]): void;
+    name: string;
+    __paint_debt: number;
+    __paint_pending: boolean;
+    /**
+     * whether the last terrain pick hit; painting is gated on it
+     * @type {boolean}
+     */
+    __brush_valid: boolean;
+    /**
+     * @type {Terrain|null}
+     */
+    terrain: Terrain | null;
+    __brushPosition: Vector2;
+    __brushImage: HTMLCanvasElement;
+    /**
+     *
+     * @param {number} timeDelta
+     */
+    paint(timeDelta: number): Promise<void>;
+    /**
+     *
+     * @param {number} timeDelta
+     */
+    update(timeDelta: number): void;
+    updateBrushImage(): void;
+    updateBrushPosition(): void;
+    /**
+     * Footprint of the brush in terrain UV space (`[0,1]` across the terrain extent), written as
+     * `[x0, y0, x1, y1]`.
+     *
+     * Every consumer of the brush — the on-screen overlay preview and each subclass's `paint` —
+     * must derive its rect from this one definition, otherwise the preview stops matching what is
+     * actually painted.
+     *
+     * @param {Float64Array|number[]} result
+     */
+    computeBrushUVRect(result: Float64Array | number[]): void;
+    updateOverlay(): void;
+    /**
+     * Grow or shrink the brush footprint
+     * @param {number} delta size change, world units
+     * @private
+     */
+    private __adjustBrushSize;
+    /**
+     *
+     * @param {KeyboardEvent} event
+     */
+    handleKeyboardEvent(event: KeyboardEvent): void;
+    terrainEntity: number;
+}
+import Tool from "../engine/Tool.js";
+import Vector2 from "../../../src/core/geom/Vector2.js";
 //# sourceMappingURL=TerrainPaintTool.d.ts.map

package/editor/tools/paint/TerrainPaintTool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TerrainPaintTool.d.ts","sourceRoot":"","sources":["TerrainPaintTool.js"],"names":[],"mappings":"AAYA;IAIQ,aAA2B;IAc3B,yBAAoC;IAEpC,gCAAoD;IAEpD,qBAAqB;IACrB,yBAA4B;IAGhC;;;OAGG;IACH,iBAFW,MAAM,iBAIhB;IAED;;;OAGG;IACH,kBAFW,MAAM,QAwBhB;IAED,yBAiCC;IAED,4BAYC;IAED,sBAuBC;IAED;;;;OAIG;IACH,2BAWC;IAUG,0EAEE;IADE,mBAA2B;CAmCtC;iBAxMgB,mBAAmB;oBARhB,mCAAmC"}
+{"version":3,"file":"TerrainPaintTool.d.ts","sourceRoot":"","sources":["TerrainPaintTool.js"],"names":[],"mappings":"AAqBA;IAgKI;;;;;;;;;;;;;OAaG;IACH,iCALW,YAAY,GAAC,MAAM,EAAE,WACrB,YAAY,GAAC,MAAM,EAAE,SACrB,MAAM,UACN,MAAM,QAOhB;IAED;;;;;;;;;;OAUG;IACH,sCAHW,YAAY,GAAC,MAAM,EAAE,cACrB,YAAY,GAAC,MAAM,EAAE,QAO/B;IApMD,aAAuB;IACvB,qBAAiB;IACjB,yBAAwB;IAExB;;;OAGG;IACH,eAFU,OAAO,CAEK;IAEtB;;OAEG;IACH,SAFU,UAAQ,IAAI,CAEP;IAiBX,yBAAoC;IAEpC,gCAAoD;IAGxD;;;OAGG;IACH,iBAFW,MAAM,iBAIhB;IAED;;;OAGG;IACH,kBAFW,MAAM,QA6BhB;IAED,yBAiCC;IAED,4BAkBC;IAED;;;;;;;;;OASG;IACH,2BAFW,YAAY,GAAC,MAAM,EAAE,QAkB/B;IAyCD,sBAoBC;IAED;;;;OAIG;IACH,0BAMC;IAED;;;OAGG;IACH,2BAFW,aAAa,QAUvB;IAYO,sBAA2B;CAwCtC;iBApTgB,mBAAmB;oBAThB,mCAAmC"}