@woosh/meep-engine 2.169.6 → 2.170.0

package/editor/tools/TransformToolV2.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Selection transform gizmo on the engine-native TransformControls.
+ *
+ * The gizmo attaches to the primary (most recent) selection. During a drag the primary's
+ * delta is applied uniformly to every selected entity: translation as a shared world
+ * offset, rotation as the same world-frame delta about each entity's own pivot, scale as
+ * the same per-axis ratio. A drag commits as one undo mark of per-entity
+ * TransformModifyActions.
+ *
+ * Keys (via the editor keymap forwarding): W/E/R switch mode, Q toggles world/local
+ * space, Escape cancels a drag in flight.
+ */
+export class TransformToolV2 extends Tool {
+    name: string;
+    /**
+     * @type {ObservedValue<string>} one of {@link TransformMode}
+     */
+    mode: any;
+    /**
+     * @type {TransformControls|null}
+     */
+    __controls: TransformControls | null;
+    /**
+     * dragging state at the previous update tick
+     * @type {boolean}
+     */
+    __was_dragging: boolean;
+    /**
+     * Transform state per selected entity at drag start
+     * @type {Map<number, Transform>}
+     */
+    __drag_snapshots: Map<number, Transform>;
+    /**
+     * The underlying gizmo; exposed so hosts and specs can drive or configure it
+     * @returns {TransformControls|null}
+     */
+    get controls(): TransformControls;
+    /**
+     * @returns {EntityComponentDataset}
+     */
+    get __dataset(): EntityComponentDataset;
+    /**
+     * Most recent selection entry carrying a Transform, -1 when none
+     * @returns {number}
+     */
+    __primaryEntity(): number;
+    __handleSelectionChanged(): void;
+    __handleDragStart(): void;
+    /**
+     * Mirror the primary's in-flight delta onto the rest of the selection.
+     */
+    __handleObjectChange(): void;
+    /**
+     * Commit the finished drag as one undo group.
+     */
+    __handleDragEnd(): void;
+    /**
+     * The rendering camera is the active Camera component's three object.
+     * @returns {THREE.Camera}
+     */
+    __resolveActiveCameraObject(): THREE.Camera;
+    update(timeDelta: any): void;
+    __handleModeChanged(): void;
+    __handleSpaceChanged(): void;
+    __applySnapSettings(): void;
+    /**
+     *
+     * @param {KeyboardEvent} event
+     */
+    handleKeyboardEvent(event: KeyboardEvent): void;
+}
+import Tool from "./engine/Tool.js";
+import { TransformControls } from "./v2/TransformControls.js";
+import { Transform } from "../../src/engine/ecs/transform/Transform.js";
+import { Camera } from "../../src/engine/graphics/ecs/camera/Camera.js";
+//# sourceMappingURL=TransformToolV2.d.ts.map

package/editor/tools/TransformToolV2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TransformToolV2.d.ts","sourceRoot":"","sources":["TransformToolV2.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;GAWG;AACH;IACI,aAA2B;IAE3B;;OAEG;IACH,UAAkD;IAElD;;OAEG;IACH,YAFU,iBAAiB,GAAC,IAAI,CAEd;IAElB;;;OAGG;IACH,gBAFU,OAAO,CAEM;IAuBnB;;;OAGG;IACH,kBAFU,IAAI,MAAM,EAAE,SAAS,CAAC,CAEC;IAGrC;;;OAGG;IACH,kCAEC;IAED;;OAEG;IACH,wCAEC;IAED;;;OAGG;IACH,mBAFa,MAAM,CAclB;IAED,iCAUC;IAED,0BAiCC;IAED;;OAEG;IACH,6BAiDC;IAED;;OAEG;IACH,wBA+BC;IAED;;;OAGG;IACH,+BAFa,YAAY,CAaxB;IA2DD,6BAgCC;IAED,4BAEC;IAED,6BAEC;IAED,4BAQC;IAED;;;OAGG;IACH,2BAFW,aAAa,QAkBvB;CACJ;iBAnYgB,kBAAkB;kCACD,2BAA2B;0BALnC,6CAA6C;uBAChD,gDAAgD"}

package/editor/tools/TransformToolV2.js

@@ -0,0 +1,396 @@
+import Quaternion from "../../src/core/geom/Quaternion.js";
+import Vector1 from "../../src/core/geom/Vector1.js";
+import Vector3 from "../../src/core/geom/Vector3.js";
+import ObservedValue from "../../src/core/model/ObservedValue.js";
+import { Transform } from "../../src/engine/ecs/transform/Transform.js";
+import { Camera } from "../../src/engine/graphics/ecs/camera/Camera.js";
+import { KeyCodes } from "../../src/engine/input/devices/KeyCodes.js";
+import TransformModifyAction from "../actions/concrete/TransformModifyAction.js";
+import Tool from "./engine/Tool.js";
+import { TransformControls } from "./v2/TransformControls.js";
+import { TransformMode } from "./v2/TransformMode.js";
+
+const DEG2RAD = Math.PI / 180;
+
+const scratch_delta_position = new Vector3();
+const scratch_delta_rotation = new Quaternion();
+const scratch_start_inverse = new Quaternion();
+const scratch_scale_ratio = new Vector3();
+
+/**
+ * Selection transform gizmo on the engine-native TransformControls.
+ *
+ * The gizmo attaches to the primary (most recent) selection. During a drag the primary's
+ * delta is applied uniformly to every selected entity: translation as a shared world
+ * offset, rotation as the same world-frame delta about each entity's own pivot, scale as
+ * the same per-axis ratio. A drag commits as one undo mark of per-entity
+ * TransformModifyActions.
+ *
+ * Keys (via the editor keymap forwarding): W/E/R switch mode, Q toggles world/local
+ * space, Escape cancels a drag in flight.
+ */
+export class TransformToolV2 extends Tool {
+    name = 'spatial_transform';
+
+    /**
+     * @type {ObservedValue<string>} one of {@link TransformMode}
+     */
+    mode = new ObservedValue(TransformMode.Translate);
+
+    /**
+     * @type {TransformControls|null}
+     */
+    __controls = null;
+
+    /**
+     * dragging state at the previous update tick
+     * @type {boolean}
+     */
+    __was_dragging = false;
+
+    constructor() {
+        super();
+
+        /**
+         * Translation snap increment, world units; 0 disables snapping
+         * @type {Vector1}
+         */
+        this.settings.snapTranslate = new Vector1(0);
+
+        /**
+         * Rotation snap increment, degrees; 0 disables snapping
+         * @type {Vector1}
+         */
+        this.settings.snapRotate = new Vector1(0);
+
+        /**
+         * 'world' or 'local' gizmo orientation
+         * @type {ObservedValue<string>}
+         */
+        this.settings.space = new ObservedValue('world');
+
+        /**
+         * Transform state per selected entity at drag start
+         * @type {Map<number, Transform>}
+         */
+        this.__drag_snapshots = new Map();
+    }
+
+    /**
+     * The underlying gizmo; exposed so hosts and specs can drive or configure it
+     * @returns {TransformControls|null}
+     */
+    get controls() {
+        return this.__controls;
+    }
+
+    /**
+     * @returns {EntityComponentDataset}
+     */
+    get __dataset() {
+        return this.engine.entityManager.dataset;
+    }
+
+    /**
+     * Most recent selection entry carrying a Transform, -1 when none
+     * @returns {number}
+     */
+    __primaryEntity() {
+        const selection = this.editor.selection;
+
+        for (let i = selection.length - 1; i >= 0; i--) {
+            const entity = selection.get(i);
+
+            if (this.__dataset.getComponent(entity, Transform) !== undefined) {
+                return entity;
+            }
+        }
+
+        return -1;
+    }
+
+    __handleSelectionChanged() {
+        const controls = this.__controls;
+
+        const primary = this.__primaryEntity();
+
+        if (primary === -1) {
+            controls.detach();
+        } else {
+            controls.attach(primary);
+        }
+    }
+
+    __handleDragStart() {
+        const snapshots = this.__drag_snapshots;
+
+        snapshots.clear();
+
+        const ecd = this.__dataset;
+        const controls = this.__controls;
+
+        const primary = controls.object;
+
+        this.editor.selection.forEach(entity => {
+            const transform = ecd.getComponent(entity, Transform);
+
+            if (transform === undefined) {
+                return;
+            }
+
+            if (entity === primary) {
+                // the primary may already carry same-frame drag movement; its pre-drag state
+                // is the controls' own pointer-down capture
+                const start = new Transform();
+
+                start.position.copy(controls.worldPositionStart);
+                start.rotation.copy(controls.worldQuaternionStart);
+                start.scale.copy(controls._worldScaleStart);
+
+                snapshots.set(entity, start);
+            } else {
+                // secondary entities only move through the mirroring below, which runs after
+                // this snapshot — a plain clone is exact
+                snapshots.set(entity, transform.clone());
+            }
+        });
+    }
+
+    /**
+     * Mirror the primary's in-flight delta onto the rest of the selection.
+     */
+    __handleObjectChange() {
+        const primary = this.__controls.object;
+
+        const start = this.__drag_snapshots.get(primary);
+
+        if (start === undefined) {
+            return;
+        }
+
+        const ecd = this.__dataset;
+
+        const current = ecd.getComponent(primary, Transform);
+
+        const mode = this.__controls.mode;
+
+        if (mode === TransformMode.Translate) {
+            scratch_delta_position.copy(current.position).sub(start.position);
+        } else if (mode === TransformMode.Rotate) {
+            scratch_start_inverse.copy(start.rotation).invert();
+            scratch_delta_rotation.copy(current.rotation).multiply(scratch_start_inverse);
+        } else {
+            // a zero start component has no meaningful ratio; that axis mirrors unchanged
+            scratch_scale_ratio.set(
+                start.scale.x !== 0 ? current.scale.x / start.scale.x : 1,
+                start.scale.y !== 0 ? current.scale.y / start.scale.y : 1,
+                start.scale.z !== 0 ? current.scale.z / start.scale.z : 1
+            );
+        }
+
+        for (const [entity, snapshot] of this.__drag_snapshots) {
+            if (entity === primary) {
+                continue;
+            }
+
+            const transform = ecd.getComponent(entity, Transform);
+
+            if (mode === TransformMode.Translate) {
+                transform.position.copy(snapshot.position).add(scratch_delta_position);
+            } else if (mode === TransformMode.Rotate) {
+                transform.rotation.copy(scratch_delta_rotation).multiply(snapshot.rotation);
+                transform.rotation.normalize();
+            } else {
+                transform.scale.set(
+                    snapshot.scale.x * scratch_scale_ratio.x,
+                    snapshot.scale.y * scratch_scale_ratio.y,
+                    snapshot.scale.z * scratch_scale_ratio.z
+                );
+            }
+        }
+    }
+
+    /**
+     * Commit the finished drag as one undo group.
+     */
+    __handleDragEnd() {
+        const snapshots = this.__drag_snapshots;
+
+        if (snapshots.size === 0) {
+            return;
+        }
+
+        const ecd = this.__dataset;
+        const actions = this.editor.actions;
+
+        let marked = false;
+
+        for (const [entity, snapshot] of snapshots) {
+            const transform = ecd.getComponent(entity, Transform);
+
+            if (transform === undefined || transform.equals(snapshot)) {
+                continue;
+            }
+
+            if (!marked) {
+                actions.mark('transform modification');
+                marked = true;
+            }
+
+            const action = new TransformModifyAction(entity, transform.clone());
+            action.oldState = snapshot;
+
+            actions.do(action);
+        }
+
+        snapshots.clear();
+    }
+
+    /**
+     * The rendering camera is the active Camera component's three object.
+     * @returns {THREE.Camera}
+     */
+    __resolveActiveCameraObject() {
+        let result = null;
+
+        this.__dataset.traverseComponents(Camera, c => {
+            if (c.active.getValue()) {
+                result = c.object;
+                return false;
+            }
+        });
+
+        return result;
+    }
+
+    /**
+     * Requires an active Camera component in the dataset — the editor camera while the
+     * editor is attached.
+     */
+    initialize() {
+        super.initialize();
+
+        const engine = this.engine;
+
+        // the tool drives update() from the engine tick; the controls' own frame loop stays off
+        const controls = this.__controls = new TransformControls(
+            this.__resolveActiveCameraObject(),
+            engine.gameView.el,
+            false
+        );
+
+        controls.mode = this.mode.getValue();
+        controls.space = this.settings.space.getValue();
+
+        this.__applySnapSettings();
+
+        const ecd = this.__dataset;
+
+        controls.build(ecd);
+
+        this.__was_dragging = false;
+
+        this.mode.onChanged.add(this.__handleModeChanged, this);
+        this.settings.space.onChanged.add(this.__handleSpaceChanged, this);
+        this.settings.snapTranslate.onChanged.add(this.__applySnapSettings, this);
+        this.settings.snapRotate.onChanged.add(this.__applySnapSettings, this);
+
+        this.editor.selection.on.added.add(this.__handleSelectionChanged, this);
+        this.editor.selection.on.removed.add(this.__handleSelectionChanged, this);
+
+        this.__handleSelectionChanged();
+    }
+
+    finalize() {
+        const controls = this.__controls;
+
+        this.mode.onChanged.remove(this.__handleModeChanged, this);
+        this.settings.space.onChanged.remove(this.__handleSpaceChanged, this);
+        this.settings.snapTranslate.onChanged.remove(this.__applySnapSettings, this);
+        this.settings.snapRotate.onChanged.remove(this.__applySnapSettings, this);
+
+        this.editor.selection.on.added.remove(this.__handleSelectionChanged, this);
+        this.editor.selection.on.removed.remove(this.__handleSelectionChanged, this);
+
+        controls.dispose();
+        controls.destroy();
+
+        this.__controls = null;
+
+        super.finalize();
+    }
+
+    update(timeDelta) {
+        const controls = this.__controls;
+
+        if (controls === null) {
+            return;
+        }
+
+        if (controls.object !== -1 && this.__dataset.getComponent(controls.object, Transform) === undefined) {
+            // the controlled entity lost its Transform or died outside the selection flow
+            // (inspector component removal, a game system despawning it)
+            controls.detach();
+            this.__was_dragging = false;
+            this.__drag_snapshots.clear();
+        }
+
+        controls.update();
+
+        const dragging = controls.dragging;
+
+        if (dragging && !this.__was_dragging) {
+            this.__handleDragStart();
+        }
+
+        if (dragging) {
+            this.__handleObjectChange();
+        }
+
+        if (!dragging && this.__was_dragging) {
+            this.__handleDragEnd();
+        }
+
+        this.__was_dragging = dragging;
+    }
+
+    __handleModeChanged() {
+        this.__controls.mode = this.mode.getValue();
+    }
+
+    __handleSpaceChanged() {
+        this.__controls.space = this.settings.space.getValue();
+    }
+
+    __applySnapSettings() {
+        const controls = this.__controls;
+
+        const translate = this.settings.snapTranslate.getValue();
+        const rotate = this.settings.snapRotate.getValue();
+
+        controls.translationSnap = translate > 0 ? translate : null;
+        controls.rotationSnap = rotate > 0 ? rotate * DEG2RAD : null;
+    }
+
+    /**
+     *
+     * @param {KeyboardEvent} event
+     */
+    handleKeyboardEvent(event) {
+        const keyCode = event.keyCode;
+
+        if (keyCode === KeyCodes.w) {
+            this.mode.set(TransformMode.Translate);
+        } else if (keyCode === KeyCodes.e) {
+            this.mode.set(TransformMode.Rotate);
+        } else if (keyCode === KeyCodes.r) {
+            this.mode.set(TransformMode.Scale);
+        } else if (keyCode === KeyCodes.q) {
+            const space = this.settings.space;
+
+            space.set(space.getValue() === 'world' ? 'local' : 'world');
+        } else if (keyCode === KeyCodes.escape) {
+            this.__controls.reset();
+        }
+    }
+}

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

@@ -1,64 +1,88 @@
-export default Tool;
-declare class Tool {
-    name: any;
-    mode: ObservedValue;
-    settings: {};
-    modifiers: {
-        shift: boolean;
-        alternative: boolean;
-    };
-    /**
-     *
-     * @type {Engine|null}
-     */
-    engine: Engine | null;
-    /**
-     *
-     * @type {Editor|null}
-     */
-    editor: Editor | null;
-    /**
-     *
-     * @type {ObservedString}
-     */
-    icon: ObservedString;
-    /**
-     *
-     * @param {Editor} editor
-     */
-    updateIcon(editor: Editor): void;
-    /**
-     *
-     * @returns {ToolState|number}
-     */
-    getState(): ToolState | number;
-    isRunning(): boolean;
-    /**
-     * Activate the tool and prepare it for usage
-     */
-    initialize(): void;
-    /**
-     * Deactivate the tool and remove and influence it may have
-     */
-    finalize(): void;
-    /**
-     * Update loop
-     */
-    update(): void;
-    /**
-     * Start usage of the tool.
-     * @example Start painting with a brush
-     */
-    start(): void;
-    /**
-     * Finish usage of the tool
-     * @example Finish brush stroke
-     */
-    stop(): void;
-    handleKeyboardEvent(e: any): void;
-    #private;
-}
-import ObservedValue from '../../../src/core/model/ObservedValue.js';
-import ObservedString from "../../../src/core/model/ObservedString.js";
-import { ToolState } from "./ToolState.js";
+export default Tool;
+declare class Tool {
+    name: any;
+    mode: ObservedValue;
+    settings: {};
+    modifiers: {
+        shift: boolean;
+        alternative: boolean;
+    };
+    /**
+     *
+     * @type {Engine|null}
+     */
+    engine: Engine | null;
+    /**
+     *
+     * @type {Editor|null}
+     */
+    editor: Editor | null;
+    /**
+     *
+     * @type {ObservedString}
+     */
+    icon: ObservedString;
+    /**
+     *
+     * @param {Editor} editor
+     */
+    updateIcon(editor: Editor): void;
+    /**
+     * 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: Editor): View | null;
+    /**
+     *
+     * @returns {ToolState|number}
+     */
+    getState(): ToolState | number;
+    isRunning(): boolean;
+    /**
+     * Activate the tool and prepare it for usage
+     */
+    initialize(): void;
+    /**
+     * Deactivate the tool and remove and influence it may have
+     */
+    finalize(): void;
+    /**
+     * Update loop
+     */
+    update(): void;
+    /**
+     * 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(): void;
+    /**
+     * Finish usage of the tool. As with {@link Tool#start}, subclasses override
+     * {@link Tool#handleStop} rather than this.
+     *
+     * @example Finish brush stroke
+     */
+    stop(): void;
+    /**
+     * 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(): void;
+    /**
+     * 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(): void;
+    handleKeyboardEvent(e: any): void;
+    #private;
+}
+import ObservedValue from '../../../src/core/model/ObservedValue.js';
+import ObservedString from "../../../src/core/model/ObservedString.js";
+import { ToolState } from "./ToolState.js";
 //# sourceMappingURL=Tool.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Tool.d.ts","sourceRoot":"","sources":["Tool.js"],"names":[],"mappings":";AAIA;IASQ,UAAgB;IAChB,oBAA+B;IAC/B,aAAkB;IAClB;;;MAGC;IACD;;;OAGG;IACH,QAFU,SAAO,IAAI,CAEH;IAClB;;;OAGG;IACH,QAFU,SAAO,IAAI,CAEH;IAElB;;;OAGG;IACH,MAFU,cAAc,CAEU;IAGtC;;;OAGG;IACH,iCAEC;IAED;;;OAGG;IACH,YAFa,SAAS,GAAC,MAAM,CAI5B;IAED,qBAEC;IAED;;OAEG;IACH,mBAEC;IAED;;OAEG;IACH,iBAEC;IAED;;OAEG;IACH,eAEC;IAED;;;OAGG;IACH,cAEC;IAED;;;OAGG;IACH,aAEC;IAED,kCAEC;;CACJ;0BAjGyB,0CAA0C;2BADzC,2CAA2C;0BAE5C,gBAAgB"}
+{"version":3,"file":"Tool.d.ts","sourceRoot":"","sources":["Tool.js"],"names":[],"mappings":";AAIA;IAGI,UAAY;IACZ,oBAA2B;IAC3B,aAAc;IACd;;;MAGE;IAEF;;;OAGG;IACH,QAFU,SAAO,IAAI,CAEP;IAEd;;;OAGG;IACH,QAFU,SAAO,IAAI,CAEP;IAEd;;;OAGG;IACH,MAFU,cAAc,CAEM;IAS9B;;;OAGG;IACH,iCAEC;IAED;;;;;;OAMG;IACH,yCAFa,OAAK,IAAI,CAIrB;IAED;;;OAGG;IACH,YAFa,SAAS,GAAC,MAAM,CAI5B;IAED,qBAEC;IAED;;OAEG;IACH,mBAEC;IAED;;OAEG;IACH,iBAEC;IAED;;OAEG;IACH,eAEC;IAED;;;;;;OAMG;IACH,cAIC;IAED;;;;;OAKG;IACH,aASC;IAED;;;;OAIG;IACH,oBAEC;IAED;;;OAGG;IACH,mBAEC;IAED,kCAEC;;CACJ;0BA7IyB,0CAA0C;2BADzC,2CAA2C;0BAE5C,gBAAgB"}