@woosh/meep-engine 3.15.0 → 3.16.0

package/editor/tools/v2/TransformControls.js

@@ -1,971 +1,1003 @@
-import { assert } from "../../../src/core/assert.js";
-import Quaternion from "../../../src/core/geom/Quaternion.js";
-import Vector3 from "../../../src/core/geom/Vector3.js";
-import { Transform } from "../../../src/engine/ecs/transform/Transform.js";
-import { FrameRunner } from "../../../src/engine/graphics/FrameRunner.js";
-import { GizmoNode } from "./GizmoNode.js";
-import { gizmo_drag_plane_normal, gizmo_ray_plane_point } from "./handle/gizmo_drag_plane.js";
-import { gizmo_draw } from "./handle/gizmo_draw.js";
-import { gizmo_handles_of_mode, gizmo_pick_handle } from "./handle/gizmo_handles.js";
-import { TransformMode } from "./TransformMode.js";
-
-/**
- * @type {Object<string, Vector3>}
- */
-const UNIT = {
-    X: new Vector3(1, 0, 0),
-    Y: new Vector3(0, 1, 0),
-    Z: new Vector3(0, 0, 1)
-};
-
-/**
- * How fast a free rotation follows the pointer, in radians per world unit at one unit from the
- * camera. Carried over from the three gizmo unchanged, because it is a feel and not a derivation.
- *
- * @type {number}
- */
-const ROTATION_SPEED = 20;
-
-/**
- * The largest the gizmo is allowed to grow relative to its distance, which caps how big a very wide
- * field of view can make it. three's number, kept for the same reason.
- *
- * @type {number}
- */
-const SIZE_CLAMP = 7;
-
-const _changeEvent = { type: 'change' };
-const _mouseDownEvent = { type: 'mouseDown', mode: null };
-const _mouseUpEvent = { type: 'mouseUp', mode: null };
-const _objectChangeEvent = { type: 'objectChange' };
-
-/**
- * @type {Vector3}
- */
-const ray_origin = new Vector3();
-
-/**
- * @type {Vector3}
- */
-const ray_direction = new Vector3();
-
-/**
- * @type {Vector3}
- */
-const scratch_point = new Vector3();
-
-/**
- * @type {Vector3}
- */
-const scratch_vector = new Vector3();
-
-/**
- * @type {Vector3}
- */
-const scratch_vector_2 = new Vector3();
-
-/**
- * @type {Quaternion}
- */
-const scratch_quaternion = new Quaternion();
-
-/**
- * @readonly
- * @type {Transform}
- */
-const _tempTransform = new Transform();
-
-/**
- * The transform gizmo.
- *
- * **What it controls is an entity, and what it needs from a renderer is one ray.** Both of those are
- * why this can be renderer-neutral at all: `Transform` is world-space by contract, so there is no
- * scene graph to walk, and `viewportProjectionRay` is on both graphics engines and answers in world
- * space. Everything else — which handle the pointer is on, what surface a drag is measured on, where
- * the handles are drawn — is arithmetic, and lives in `handle/`.
- *
- * The three version answered the first two questions by building meshes and raycasting them: an
- * invisible cone per arm, an invisible 100000-unit `PlaneGeometry` per drag. That is why it needed
- * a three camera object on the component. It needs none now:
- * the ray through the middle of the viewport starts at the eye and points where the camera looks,
- * and the ray through the top edge gives the field of view the gizmo is sized against.
- *
- * The **drag maths is the three version's**, ported to meep `Vector3`/`Quaternion` — this is the
- * feel of a tool people have used, not something to redesign. Two things did change:
- *
- * - the parent transform is gone. It was set to the identity on every update and multiplied through
- *   the whole of `pointerMove`, because `Transform` is world-space and there is no parent to
- *   compose with.
- * - a drag no longer starts when the drag plane is edge-on to the pointer. three started one anyway,
- *   from whatever `pointStart` the previous drag left behind.
- *
- * The three gizmo's `showX`/`showY`/`showZ` are gone with the meshes they hid; nothing in the tree
- * set them.
- */
-class TransformControls extends GizmoNode {
-    /**
-     * Entity ID that we are controlling. -1 indicates no entity
-     * @type {number}
-     */
-    object = -1;
-
-    isTransformControls = true;
-
-    /**
-     * @type {boolean}
-     */
-    enabled = true;
-
-    /**
-     * The handle under the pointer, or the one being dragged. One of the names in
-     * {@link gizmo_handles_of_mode}, or `null`.
-     *
-     * @type {string|null}
-     */
-    axis = null;
-
-    /**
-     * @type {string} one of {@link TransformMode}
-     */
-    mode = TransformMode.Translate;
-
-    /**
-     * @type {string} `'world'` or `'local'`
-     */
-    space = 'world';
-
-    /**
-     * How big the gizmo is drawn, as a multiple of its default screen size.
-     *
-     * @type {number}
-     */
-    size = 1;
-
-    /**
-     * @type {boolean}
-     */
-    dragging = false;
-
-    /**
-     * World units per step, or `null` for none.
-     *
-     * @type {number|null}
-     */
-    translationSnap = null;
-
-    /**
-     * Radians per step, or `null` for none.
-     *
-     * @type {number|null}
-     */
-    rotationSnap = null;
-
-    /**
-     * @type {number|null}
-     */
-    scaleSnap = null;
-
-    /**
-     * @type {Vector3}
-     */
-    worldPosition = new Vector3();
-
-    /**
-     * @type {Quaternion}
-     */
-    worldQuaternion = new Quaternion();
-
-    /**
-     * Where the controlled entity was when the drag started. The tool reads these to build its undo
-     * state, because by the time it looks the entity has already moved.
-     *
-     * @type {Vector3}
-     */
-    worldPositionStart = new Vector3();
-
-    /**
-     * @type {Quaternion}
-     */
-    worldQuaternionStart = new Quaternion();
-
-    /**
-     * @type {Vector3}
-     */
-    _worldScaleStart = new Vector3(1, 1, 1);
-
-    /**
-     * @type {Vector3}
-     */
-    _worldScale = new Vector3(1, 1, 1);
-
-    /**
-     * @type {Quaternion}
-     */
-    _worldQuaternionInv = new Quaternion();
-
-    /**
-     * @type {Vector3}
-     */
-    _positionStart = new Vector3();
-
-    /**
-     * @type {Quaternion}
-     */
-    _quaternionStart = new Quaternion();
-
-    /**
-     * @type {Vector3}
-     */
-    _scaleStart = new Vector3(1, 1, 1);
-
-    /**
-     * Where the pointer met the drag plane when the drag started, relative to the gizmo.
-     *
-     * @type {Vector3}
-     */
-    pointStart = new Vector3();
-
-    /**
-     * @type {Vector3}
-     */
-    pointEnd = new Vector3();
-
-    /**
-     * @type {Vector3}
-     */
-    _offset = new Vector3();
-
-    /**
-     * @type {Vector3}
-     */
-    _startNorm = new Vector3();
-
-    /**
-     * @type {Vector3}
-     */
-    _endNorm = new Vector3();
-
-    /**
-     * @type {Vector3}
-     */
-    rotationAxis = new Vector3();
-
-    /**
-     * @type {number}
-     */
-    rotationAngle = 0;
-
-    /**
-     * Where the camera is, and a unit vector from the gizmo towards it.
-     *
-     * @type {Vector3}
-     */
-    cameraPosition = new Vector3();
-
-    /**
-     * @type {Vector3}
-     */
-    eye = new Vector3(0, 0, 1);
-
-    /**
-     * The direction the camera looks along.
-     *
-     * @type {Vector3}
-     */
-    #camera_forward = new Vector3(0, 0, -1);
-
-    /**
-     * A ray through the top edge of the viewport, which is half a field of view away from
-     * {@link #camera_forward}.
-     *
-     * @type {Vector3}
-     */
-    #camera_edge = new Vector3(0, 0, -1);
-
-    /**
-     * The surface a drag is measured on, rebuilt every update from the current mode, axis, space and
-     * eye.
-     *
-     * A drag measures a delta between two points on this surface, so it would matter if the surface
-     * moved mid-drag — and it cannot. An arm's plane is built from the part of the eye perpendicular
-     * to that arm, and moving the object along the arm changes only the part parallel to it; a tile's
-     * is a basis vector; a free drag's and a rotation's is the view direction. Nothing a drag does to
-     * the object it is dragging can change any of them.
-     *
-     * @type {Vector3}
-     */
-    #plane_normal = new Vector3(0, 0, 1);
-
-    /**
-     * How the handles are turned: the identity in world space, the object's own rotation in local
-     * space and always in scale mode.
-     *
-     * @type {Quaternion}
-     */
-    #handle_rotation = new Quaternion();
-
-    /**
-     * How big the gizmo is in world units, one gizmo unit each.
-     *
-     * @type {number}
-     */
-    #handle_size = 1;
-
-    /**
-     * @type {function}
-     */
-    #draw;
-
-    /**
-     * @param {GraphicsEngine|GraphicsEngine} graphics the only thing a renderer is asked for is
-     * {@link GraphicsEngine#viewportProjectionRay} and the `preRender` signal to draw on
-     * @param {HTMLElement} domElement
-     * @param {boolean} [autoUpdate] update on a frame loop of its own, rather than being driven
-     */
-    constructor(graphics, domElement, autoUpdate = true) {
-        super();
-
-        assert.defined(graphics, 'graphics');
-        assert.defined(domElement, 'domElement');
-
-        this.graphics = graphics;
-        this.domElement = domElement;
-
-        this.domElement.style.touchAction = 'none'; // disable touch scroll
-
-        this.visible = false;
-
-        this._getPointer = getPointer.bind(this);
-        this._onPointerDown = onPointerDown.bind(this);
-        this._onPointerHover = onPointerHover.bind(this);
-        this._onPointerMove = onPointerMove.bind(this);
-        this._onPointerUp = onPointerUp.bind(this);
-
-        this.domElement.addEventListener('pointerdown', this._onPointerDown);
-        this.domElement.addEventListener('pointermove', this._onPointerHover);
-        this.domElement.addEventListener('pointerup', this._onPointerUp);
-
-        this.#draw = () => this.#record();
-
-        if (autoUpdate) {
-            const fr = new FrameRunner(this.update.bind(this));
-            this.on.built.add(fr.startup, fr);
-            this.on.destroyed.add(fr.shutdown, fr);
-        }
-    }
-
-    /**
-     * @param {EntityComponentDataset} ecd
-     */
-    build(ecd) {
-        super.build(ecd);
-
-        this.graphics.on.preRender.add(this.#draw);
-    }
-
-    /**
-     * How big one gizmo unit is in world units.
-     *
-     * The gizmo is a fixed size on screen, so its world size is the distance to it times the tangent
-     * of half the vertical field of view — and that tangent comes from the angle between the ray
-     * through the middle of the viewport and the ray through its top edge, which is the same
-     * measurement on either renderer and needs no camera object.
-     *
-     * A parallel projection has no such angle and would size the gizmo to nothing;
-     * `viewportProjectionRay` does not describe one on either engine, so nothing here branches on it.
-     *
-     * @returns {number}
-     */
-    #size_in_world() {
-        const cos = this.#camera_forward.dot(this.#camera_edge);
-
-        const tan = Math.sqrt(1 - cos * cos) / cos;
-
-        const distance = this.cameraPosition.distanceTo(this.worldPosition);
-
-        return distance * Math.min(1.9 * tan, SIZE_CLAMP) * this.size / 4;
-    }
-
-    /**
-     * Key transformation variables, and the drag surface, for this frame.
-     */
-    update() {
-        const graphics = this.graphics;
-
-        // both camera facts come out of the projection itself: the ray through the middle of the
-        // viewport starts at the eye and points where the camera looks
-        graphics.viewportProjectionRay(0, 0, this.cameraPosition, this.#camera_forward);
-        graphics.viewportProjectionRay(0, 1, scratch_point, this.#camera_edge);
-
-        if (this.object !== -1) {
-
-            const object_transform = this.object_transform;
-
-            this.worldPosition.copy(object_transform.position);
-            this.worldQuaternion.copy(object_transform.rotation);
-            this._worldScale.copy(object_transform.scale);
-
-            this._worldQuaternionInv.copy(this.worldQuaternion).invert();
-
-        }
-
-        this.eye.copy(this.cameraPosition).sub(this.worldPosition).normalize();
-
-        const local = this.mode === TransformMode.Scale || this.space === 'local';
-
-        if (local) {
-            this.#handle_rotation.copy(this.worldQuaternion);
-        } else {
-            this.#handle_rotation.set(0, 0, 0, 1);
-        }
-
-        this.#handle_size = this.#size_in_world();
-
-        if (this.axis !== null) {
-            gizmo_drag_plane_normal(
-                this.#plane_normal,
-                this.mode, this.axis, this.space,
-                this.worldQuaternion,
-                this.eye, this.#camera_forward
-            );
-        }
-
-        super.update();
-    }
-
-    /**
-     * One frame of the gizmo, onto the debug-draw pass.
-     */
-    #record() {
-        if (!this.visible || this.object === -1) {
-            return;
-        }
-
-        gizmo_draw(
-            this.mode,
-            this.worldPosition,
-            this.#handle_rotation,
-            this.#handle_size,
-            this.axis,
-            this.#camera_forward
-        );
-    }
-
-    /**
-     * The world ray under a pointer, into the module's own scratch.
-     *
-     * @param {{x:number, y:number}} pointer clip space
-     */
-    #pointer_ray(pointer) {
-        this.graphics.viewportProjectionRay(pointer.x, pointer.y, ray_origin, ray_direction);
-    }
-
-    pointerHover(pointer) {
-
-        if (this.object === -1 || this.dragging === true) return;
-
-        this.#pointer_ray(pointer);
-
-        this.axis = gizmo_pick_handle(
-            gizmo_handles_of_mode(this.mode),
-            ray_origin, ray_direction,
-            this.worldPosition, this.#handle_rotation, this.#handle_size
-        );
-
-    }
-
-    pointerDown(pointer) {
-
-        if (this.object === -1 || this.dragging === true || pointer.button !== 0) return;
-
-        if (this.axis === null) return;
-
-        const ot = this.object_transform;
-
-        this.#pointer_ray(pointer);
-
-        gizmo_drag_plane_normal(
-            this.#plane_normal,
-            this.mode, this.axis, this.space,
-            ot.rotation,
-            this.eye, this.#camera_forward
-        );
-
-        if (!gizmo_ray_plane_point(
-            scratch_point, ray_origin, ray_direction, ot.position, this.#plane_normal
-        )) {
-            // the drag surface is edge-on to the pointer, so there is no point on it to drag from
-            return;
-        }
-
-        this._positionStart.copy(ot.position);
-        this._quaternionStart.copy(ot.rotation);
-        this._scaleStart.copy(ot.scale);
-
-        this.worldPositionStart.copy(ot.position);
-        this.worldQuaternionStart.copy(ot.rotation);
-        this._worldScaleStart.copy(ot.scale);
-
-        this.pointStart.copy(scratch_point).sub(this.worldPositionStart);
-
-        this.dragging = true;
-
-        _mouseDownEvent.mode = this.mode;
-        this.dispatchEvent(_mouseDownEvent);
-
-    }
-
-    /**
-     *
-     * @param {{type:string}} event
-     */
-    dispatchEvent(event) {
-        this.entity.sendEvent(event.type, event);
-    }
-
-    pointerMove(pointer) {
-
-        const axis = this.axis;
-        const mode = this.mode;
-        const object = this.object;
-
-        let space = this.space;
-
-        if (mode === TransformMode.Scale) {
-
-            space = 'local';
-
-        } else if (axis === 'E' || axis === 'XYZE' || axis === 'XYZ') {
-
-            space = 'world';
-
-        }
-
-        if (object === -1 || axis === null || this.dragging === false || pointer.button !== -1) return;
-
-        const object_transform = this.object_transform;
-
-        this.#pointer_ray(pointer);
-
-        if (!gizmo_ray_plane_point(
-            scratch_point, ray_origin, ray_direction, this.worldPositionStart, this.#plane_normal
-        )) {
-            return;
-        }
-
-        this.pointEnd.copy(scratch_point).sub(this.worldPositionStart);
-
-        if (mode === TransformMode.Translate) {
-
-            // Apply translate
-
-            this._offset.copy(this.pointEnd).sub(this.pointStart);
-
-            if (space === 'local' && axis !== 'XYZ') {
-
-                this._offset.applyQuaternion(this._worldQuaternionInv);
-
-            }
-
-            if (axis.indexOf('X') === -1) this._offset.x = 0;
-            if (axis.indexOf('Y') === -1) this._offset.y = 0;
-            if (axis.indexOf('Z') === -1) this._offset.z = 0;
-
-            if (space === 'local' && axis !== 'XYZ') {
-
-                this._offset.applyQuaternion(this._quaternionStart);
-
-            }
-
-            _tempTransform.position.copy(this._offset);
-            _tempTransform.position.add(this._positionStart);
-
-            // Apply translation snap; snapping operates on the candidate position — the
-            // controlled object is an entity id, Transforms are world-space by contract
-            if (this.translationSnap) {
-
-                if (space === 'local') {
-
-                    _tempTransform.position.applyQuaternion(
-                        scratch_quaternion.copy(this._quaternionStart).invert()
-                    );
-
-                }
-
-                if (axis.search('X') !== -1) {
-
-                    _tempTransform.position.setX(Math.round(_tempTransform.position.x / this.translationSnap) * this.translationSnap);
-
-                }
-
-                if (axis.search('Y') !== -1) {
-
-                    _tempTransform.position.setY(Math.round(_tempTransform.position.y / this.translationSnap) * this.translationSnap);
-
-                }
-
-                if (axis.search('Z') !== -1) {
-
-                    _tempTransform.position.setZ(Math.round(_tempTransform.position.z / this.translationSnap) * this.translationSnap);
-
-                }
-
-                if (space === 'local') {
-
-                    _tempTransform.position.applyQuaternion(this._quaternionStart);
-
-                }
-
-            }
-
-            // write
-            object_transform.position.copy(_tempTransform.position);
-
-        } else if (mode === TransformMode.Scale) {
-
-            if (axis.search('XYZ') !== -1) {
-
-                let d = this.pointEnd.length() / this.pointStart.length();
-
-                if (this.pointEnd.dot(this.pointStart) < 0) d *= -1;
-
-                scratch_vector_2.set(d, d, d);
-
-            } else {
-
-                scratch_vector.copy(this.pointStart);
-                scratch_vector_2.copy(this.pointEnd);
-
-                scratch_vector.applyQuaternion(this._worldQuaternionInv);
-                scratch_vector_2.applyQuaternion(this._worldQuaternionInv);
-
-                scratch_vector_2.divide(scratch_vector);
-
-                if (axis.search('X') === -1) {
-
-                    scratch_vector_2.x = 1;
-
-                }
-
-                if (axis.search('Y') === -1) {
-
-                    scratch_vector_2.y = 1;
-
-                }
-
-                if (axis.search('Z') === -1) {
-
-                    scratch_vector_2.z = 1;
-
-                }
-
-            }
-
-            // Apply scale
-
-            _tempTransform.scale.copy(this._scaleStart);
-            _tempTransform.scale.multiply(scratch_vector_2);
-
-            if (this.scaleSnap) {
-
-                if (axis.search('X') !== -1) {
-
-                    _tempTransform.scale.setX(Math.round(_tempTransform.scale.x / this.scaleSnap) * this.scaleSnap || this.scaleSnap);
-
-                }
-
-                if (axis.search('Y') !== -1) {
-
-                    _tempTransform.scale.setY(Math.round(_tempTransform.scale.y / this.scaleSnap) * this.scaleSnap || this.scaleSnap);
-
-                }
-
-                if (axis.search('Z') !== -1) {
-
-                    _tempTransform.scale.setZ(Math.round(_tempTransform.scale.z / this.scaleSnap) * this.scaleSnap || this.scaleSnap);
-
-                }
-
-            }
-
-            object_transform.scale.copy(_tempTransform.scale);
-
-        } else if (mode === TransformMode.Rotate) {
-
-            this._offset.copy(this.pointEnd).sub(this.pointStart);
-
-            const speed = ROTATION_SPEED / this.worldPosition.distanceTo(this.cameraPosition);
-
-            if (axis === 'E') {
-
-                this.rotationAxis.copy(this.eye);
-                this.rotationAngle = this.pointEnd.angleTo(this.pointStart);
-
-                this._startNorm.copy(this.pointStart).normalize();
-                this._endNorm.copy(this.pointEnd).normalize();
-
-                this.rotationAngle *= (this._endNorm.cross(this._startNorm).dot(this.eye) < 0 ? 1 : -1);
-
-            } else if (axis === 'XYZE') {
-
-                this.rotationAxis.copy(this._offset).cross(this.eye).normalize();
-                this.rotationAngle = this._offset.dot(scratch_vector.copy(this.rotationAxis).cross(this.eye)) * speed;
-
-            } else if (axis === 'X' || axis === 'Y' || axis === 'Z') {
-
-                this.rotationAxis.copy(UNIT[axis]);
-
-                scratch_vector.copy(UNIT[axis]);
-
-                if (space === 'local') {
-
-                    scratch_vector.applyQuaternion(this.worldQuaternion);
-
-                }
-
-                this.rotationAngle = this._offset.dot(scratch_vector.cross(this.eye).normalize()) * speed;
-
-            }
-
-            // Apply rotation snap
-
-            if (this.rotationSnap) this.rotationAngle = Math.round(this.rotationAngle / this.rotationSnap) * this.rotationSnap;
-
-            // Apply rotate
-            if (space === 'local' && axis !== 'E' && axis !== 'XYZE') {
-
-                _tempTransform.rotation.copy(this._quaternionStart);
-                _tempTransform.rotation.multiply(
-                    scratch_quaternion.fromAxisAngle(this.rotationAxis, this.rotationAngle)
-                ).normalize();
-
-            } else {
-
-                _tempTransform.rotation.copy(
-                    scratch_quaternion.fromAxisAngle(this.rotationAxis, this.rotationAngle)
-                );
-                _tempTransform.rotation.multiply(this._quaternionStart);
-                _tempTransform.rotation.normalize();
-
-            }
-
-            object_transform.rotation.copy(_tempTransform.rotation);
-        }
-
-        this.dispatchEvent(_changeEvent);
-        this.dispatchEvent(_objectChangeEvent);
-
-    }
-
-    pointerUp(pointer) {
-
-        if (pointer.button !== 0) return;
-
-        if (this.dragging && (this.axis !== null)) {
-
-            _mouseUpEvent.mode = this.mode;
-            this.dispatchEvent(_mouseUpEvent);
-
-        }
-
-        this.dragging = false;
-        this.axis = null;
-
-    }
-
-    dispose() {
-
-        this.domElement.removeEventListener('pointerdown', this._onPointerDown);
-        this.domElement.removeEventListener('pointermove', this._onPointerHover);
-        this.domElement.removeEventListener('pointermove', this._onPointerMove);
-        this.domElement.removeEventListener('pointerup', this._onPointerUp);
-
-        this.graphics.on.preRender.remove(this.#draw);
-
-    }
-
-    /**
-     * Set current object
-     * @param {number} entity
-     * @returns {TransformControls}
-     */
-    attach(entity) {
-        assert.isNonNegativeInteger(entity, 'entity');
-
-        this.object = entity;
-
-        this.visible = true;
-
-        return this;
-
-    }
-
-    /**
-     *
-     * @returns {Transform|undefined}
-     */
-    get object_transform() {
-        const ecd = this.entity.dataset;
-
-        return ecd.getComponent(this.object, Transform);
-    }
-
-    // Detatch from object
-    detach() {
-
-        this.object = -1;
-
-        this.visible = false;
-        this.axis = null;
-
-        // a drag in flight has no target anymore
-        this.dragging = false;
-
-        return this;
-
-    }
-
-    reset() {
-
-        if (!this.enabled) return;
-
-        if (this.dragging) {
-
-            this.object_transform.position.copy(this._positionStart);
-            this.object_transform.rotation.copy(this._quaternionStart);
-            this.object_transform.scale.copy(this._scaleStart);
-
-            this.dispatchEvent(_changeEvent);
-            this.dispatchEvent(_objectChangeEvent);
-
-            this.pointStart.copy(this.pointEnd);
-
-        }
-
-    }
-
-    // TODO: deprecate
-
-    getMode() {
-
-        return this.mode;
-
-    }
-
-    setMode(mode) {
-
-        this.mode = mode;
-
-    }
-
-    setTranslationSnap(translationSnap) {
-
-        this.translationSnap = translationSnap;
-
-    }
-
-    setRotationSnap(rotationSnap) {
-
-        this.rotationSnap = rotationSnap;
-
-    }
-
-    setScaleSnap(scaleSnap) {
-
-        this.scaleSnap = scaleSnap;
-
-    }
-
-    setSize(size) {
-
-        this.size = size;
-
-    }
-
-    setSpace(space) {
-
-        this.space = space;
-
-    }
-
-}
-
-// mouse / touch event handlers
-
-function getPointer(event) {
-
-    if (this.domElement.ownerDocument.pointerLockElement) {
-
-        return {
-            x: 0,
-            y: 0,
-            button: event.button
-        };
-
-    } else {
-
-        const rect = this.domElement.getBoundingClientRect();
-
-        return {
-            x: (event.clientX - rect.left) / rect.width * 2 - 1,
-            y: -(event.clientY - rect.top) / rect.height * 2 + 1,
-            button: event.button
-        };
-
-    }
-
-}
-
-function onPointerHover(event) {
-
-    if (!this.enabled) return;
-
-    switch (event.pointerType) {
-
-        case 'mouse':
-        case 'pen':
-            this.pointerHover(this._getPointer(event));
-            break;
-
-    }
-
-}
-
-function onPointerDown(event) {
-
-    if (!this.enabled) return;
-
-    if (!document.pointerLockElement) {
-
-        this.domElement.setPointerCapture(event.pointerId);
-
-    }
-
-    this.domElement.addEventListener('pointermove', this._onPointerMove);
-
-    this.pointerHover(this._getPointer(event));
-    this.pointerDown(this._getPointer(event));
-
-}
-
-function onPointerMove(event) {
-
-    if (!this.enabled) return;
-
-    this.pointerMove(this._getPointer(event));
-
-}
-
-function onPointerUp(event) {
-
-    if (!this.enabled) return;
-
-    this.domElement.releasePointerCapture(event.pointerId);
-
-    this.domElement.removeEventListener('pointermove', this._onPointerMove);
-
-    this.pointerUp(this._getPointer(event));
-
-}
-
-export { TransformControls };
+import { assert } from "../../../src/core/assert.js";
+import Quaternion from "../../../src/core/geom/Quaternion.js";
+import Vector3 from "../../../src/core/geom/Vector3.js";
+import { Transform64 } from "../../../src/engine/ecs/transform/Transform64.js";
+import { FrameRunner } from "../../../src/engine/graphics/FrameRunner.js";
+import { GizmoNode } from "./GizmoNode.js";
+import { gizmo_drag_plane_normal, gizmo_ray_plane_point } from "./handle/gizmo_drag_plane.js";
+import { gizmo_draw } from "./handle/gizmo_draw.js";
+import { gizmo_handles_of_mode, gizmo_pick_handle } from "./handle/gizmo_handles.js";
+import { TransformMode } from "./TransformMode.js";
+
+/**
+ * @type {Object<string, Vector3>}
+ */
+const UNIT = {
+    X: new Vector3(1, 0, 0),
+    Y: new Vector3(0, 1, 0),
+    Z: new Vector3(0, 0, 1)
+};
+
+/**
+ * How fast a free rotation follows the pointer, in radians per world unit at one unit from the
+ * camera. Carried over from the three gizmo unchanged, because it is a feel and not a derivation.
+ *
+ * @type {number}
+ */
+const ROTATION_SPEED = 20;
+
+/**
+ * The largest the gizmo is allowed to grow relative to its distance, which caps how big a very wide
+ * field of view can make it. three's number, kept for the same reason.
+ *
+ * @type {number}
+ */
+const SIZE_CLAMP = 7;
+
+const _changeEvent = { type: 'change' };
+const _mouseDownEvent = { type: 'mouseDown', mode: null };
+const _mouseUpEvent = { type: 'mouseUp', mode: null };
+const _objectChangeEvent = { type: 'objectChange' };
+
+/**
+ * @type {Vector3}
+ */
+const ray_origin = new Vector3();
+
+/**
+ * @type {Vector3}
+ */
+const ray_direction = new Vector3();
+
+/**
+ * @type {Vector3}
+ */
+const scratch_point = new Vector3();
+
+/**
+ * @type {Vector3}
+ */
+const scratch_vector = new Vector3();
+
+/**
+ * @type {Vector3}
+ */
+const scratch_vector_2 = new Vector3();
+const scratch_scale = new Vector3();
+
+const scratch_translation = new Vector3();
+
+/**
+ * @type {Quaternion}
+ */
+const scratch_quaternion = new Quaternion();
+
+const scratch_quaternion_2 = new Quaternion();
+
+/**
+ * The transform gizmo.
+ *
+ * **What it controls is an entity, and what it needs from a renderer is one ray.** Both of those are
+ * why this can be renderer-neutral at all: `Transform` is world-space by contract, so there is no
+ * scene graph to walk, and `viewportProjectionRay` is on both graphics engines and answers in world
+ * space. Everything else — which handle the pointer is on, what surface a drag is measured on, where
+ * the handles are drawn — is arithmetic, and lives in `handle/`.
+ *
+ * The three version answered the first two questions by building meshes and raycasting them: an
+ * invisible cone per arm, an invisible 100000-unit `PlaneGeometry` per drag. That is why it needed
+ * a three camera object on the component. It needs none now:
+ * the ray through the middle of the viewport starts at the eye and points where the camera looks,
+ * and the ray through the top edge gives the field of view the gizmo is sized against.
+ *
+ * The **drag maths is the three version's**, ported to meep `Vector3`/`Quaternion` — this is the
+ * feel of a tool people have used, not something to redesign. Two things did change:
+ *
+ * - the parent transform is gone. It was set to the identity on every update and multiplied through
+ *   the whole of `pointerMove`, because `Transform` is world-space and there is no parent to
+ *   compose with.
+ * - a drag no longer starts when the drag plane is edge-on to the pointer. three started one anyway,
+ *   from whatever `pointStart` the previous drag left behind.
+ *
+ * The three gizmo's `showX`/`showY`/`showZ` are gone with the meshes they hid; nothing in the tree
+ * set them.
+ */
+class TransformControls extends GizmoNode {
+    /**
+     * Entity ID that we are controlling. -1 indicates no entity
+     * @type {number}
+     */
+    object = -1;
+
+    isTransformControls = true;
+
+    /**
+     * @type {boolean}
+     */
+    enabled = true;
+
+    /**
+     * The handle under the pointer, or the one being dragged. One of the names in
+     * {@link gizmo_handles_of_mode}, or `null`.
+     *
+     * @type {string|null}
+     */
+    axis = null;
+
+    /**
+     * @type {string} one of {@link TransformMode}
+     */
+    mode = TransformMode.Translate;
+
+    /**
+     * @type {string} `'world'` or `'local'`
+     */
+    space = 'world';
+
+    /**
+     * How big the gizmo is drawn, as a multiple of its default screen size.
+     *
+     * @type {number}
+     */
+    size = 1;
+
+    /**
+     * @type {boolean}
+     */
+    dragging = false;
+
+    /**
+     * World units per step, or `null` for none.
+     *
+     * @type {number|null}
+     */
+    translationSnap = null;
+
+    /**
+     * Radians per step, or `null` for none.
+     *
+     * @type {number|null}
+     */
+    rotationSnap = null;
+
+    /**
+     * @type {number|null}
+     */
+    scaleSnap = null;
+
+    /**
+     * @type {Vector3}
+     */
+    worldPosition = new Vector3();
+
+    /**
+     * @type {Quaternion}
+     */
+    worldQuaternion = new Quaternion();
+
+    /**
+     * Where the controlled entity was when the drag started. The tool reads these to build its undo
+     * state, because by the time it looks the entity has already moved.
+     *
+     * @type {Vector3}
+     */
+    worldPositionStart = new Vector3();
+
+    /**
+     * @type {Quaternion}
+     */
+    worldQuaternionStart = new Quaternion();
+
+    /**
+     * @type {Vector3}
+     */
+    _worldScaleStart = new Vector3(1, 1, 1);
+
+    /**
+     * @type {Vector3}
+     */
+    _worldScale = new Vector3(1, 1, 1);
+
+    /**
+     * @type {Quaternion}
+     */
+    _worldQuaternionInv = new Quaternion();
+
+    /**
+     * @type {Vector3}
+     */
+    _positionStart = new Vector3();
+
+    /**
+     * @type {Quaternion}
+     */
+    _quaternionStart = new Quaternion();
+
+    /**
+     * @type {Vector3}
+     */
+    _scaleStart = new Vector3(1, 1, 1);
+
+    /**
+     * Where the pointer met the drag plane when the drag started, relative to the gizmo.
+     *
+     * @type {Vector3}
+     */
+    pointStart = new Vector3();
+
+    /**
+     * @type {Vector3}
+     */
+    pointEnd = new Vector3();
+
+    /**
+     * @type {Vector3}
+     */
+    _offset = new Vector3();
+
+    /**
+     * @type {Vector3}
+     */
+    _startNorm = new Vector3();
+
+    /**
+     * @type {Vector3}
+     */
+    _endNorm = new Vector3();
+
+    /**
+     * @type {Vector3}
+     */
+    rotationAxis = new Vector3();
+
+    /**
+     * @type {number}
+     */
+    rotationAngle = 0;
+
+    /**
+     * Where the camera is, and a unit vector from the gizmo towards it.
+     *
+     * @type {Vector3}
+     */
+    cameraPosition = new Vector3();
+
+    /**
+     * @type {Vector3}
+     */
+    eye = new Vector3(0, 0, 1);
+
+    /**
+     * The direction the camera looks along.
+     *
+     * @type {Vector3}
+     */
+    #camera_forward = new Vector3(0, 0, -1);
+
+    /**
+     * A ray through the top edge of the viewport, which is half a field of view away from
+     * {@link #camera_forward}.
+     *
+     * @type {Vector3}
+     */
+    #camera_edge = new Vector3(0, 0, -1);
+
+    /**
+     * The surface a drag is measured on, rebuilt every update from the current mode, axis, space and
+     * eye.
+     *
+     * A drag measures a delta between two points on this surface, so it would matter if the surface
+     * moved mid-drag — and it cannot. An arm's plane is built from the part of the eye perpendicular
+     * to that arm, and moving the object along the arm changes only the part parallel to it; a tile's
+     * is a basis vector; a free drag's and a rotation's is the view direction. Nothing a drag does to
+     * the object it is dragging can change any of them.
+     *
+     * @type {Vector3}
+     */
+    #plane_normal = new Vector3(0, 0, 1);
+
+    /**
+     * How the handles are turned: the identity in world space, the object's own rotation in local
+     * space and always in scale mode.
+     *
+     * @type {Quaternion}
+     */
+    #handle_rotation = new Quaternion();
+
+    /**
+     * How big the gizmo is in world units, one gizmo unit each.
+     *
+     * @type {number}
+     */
+    #handle_size = 1;
+
+    /**
+     * @type {function}
+     */
+    #draw;
+
+    /**
+     * @param {GraphicsEngine|GraphicsEngine} graphics the only thing a renderer is asked for is
+     * {@link GraphicsEngine#viewportProjectionRay} and the `preRender` signal to draw on
+     * @param {HTMLElement} domElement
+     * @param {boolean} [autoUpdate] update on a frame loop of its own, rather than being driven
+     */
+    constructor(graphics, domElement, autoUpdate = true) {
+        super();
+
+        assert.defined(graphics, 'graphics');
+        assert.defined(domElement, 'domElement');
+
+        this.graphics = graphics;
+        this.domElement = domElement;
+
+        this.domElement.style.touchAction = 'none'; // disable touch scroll
+
+        this.visible = false;
+
+        this._getPointer = getPointer.bind(this);
+        this._onPointerDown = onPointerDown.bind(this);
+        this._onPointerHover = onPointerHover.bind(this);
+        this._onPointerMove = onPointerMove.bind(this);
+        this._onPointerUp = onPointerUp.bind(this);
+
+        this.domElement.addEventListener('pointerdown', this._onPointerDown);
+        this.domElement.addEventListener('pointermove', this._onPointerHover);
+        this.domElement.addEventListener('pointerup', this._onPointerUp);
+
+        this.#draw = () => this.#record();
+
+        if (autoUpdate) {
+            const fr = new FrameRunner(this.update.bind(this));
+            this.on.built.add(fr.startup, fr);
+            this.on.destroyed.add(fr.shutdown, fr);
+        }
+    }
+
+    /**
+     * @param {EntityComponentDataset} ecd
+     */
+    build(ecd) {
+        super.build(ecd);
+
+        this.graphics.on.preRender.add(this.#draw);
+    }
+
+    /**
+     * How big one gizmo unit is in world units.
+     *
+     * The gizmo is a fixed size on screen, so its world size is the distance to it times the tangent
+     * of half the vertical field of view — and that tangent comes from the angle between the ray
+     * through the middle of the viewport and the ray through its top edge, which is the same
+     * measurement on either renderer and needs no camera object.
+     *
+     * A parallel projection has no such angle and would size the gizmo to nothing;
+     * `viewportProjectionRay` does not describe one on either engine, so nothing here branches on it.
+     *
+     * @returns {number}
+     */
+    #size_in_world() {
+        const cos = this.#camera_forward.dot(this.#camera_edge);
+
+        const tan = Math.sqrt(1 - cos * cos) / cos;
+
+        const distance = this.cameraPosition.distanceTo(this.worldPosition);
+
+        return distance * Math.min(1.9 * tan, SIZE_CLAMP) * this.size / 4;
+    }
+
+    /**
+     * Key transformation variables, and the drag surface, for this frame.
+     */
+    update() {
+        const graphics = this.graphics;
+
+        // both camera facts come out of the projection itself: the ray through the middle of the
+        // viewport starts at the eye and points where the camera looks
+        graphics.viewportProjectionRay(0, 0, this.cameraPosition, this.#camera_forward);
+        graphics.viewportProjectionRay(0, 1, scratch_point, this.#camera_edge);
+
+        if (this.object !== -1) {
+
+            const object_transform = this.object_transform;
+
+            this.worldPosition.set(object_transform.translation_x, object_transform.translation_y, object_transform.translation_z);
+            this.worldQuaternion.set(object_transform.rotation_x, object_transform.rotation_y, object_transform.rotation_z, object_transform.rotation_w);
+            this._worldScale.set(object_transform.scale_x, object_transform.scale_y, object_transform.scale_z);
+
+            this._worldQuaternionInv.copy(this.worldQuaternion).invert();
+
+        }
+
+        this.eye.copy(this.cameraPosition).sub(this.worldPosition).normalize();
+
+        const local = this.mode === TransformMode.Scale || this.space === 'local';
+
+        if (local) {
+            this.#handle_rotation.copy(this.worldQuaternion);
+        } else {
+            this.#handle_rotation.set(0, 0, 0, 1);
+        }
+
+        this.#handle_size = this.#size_in_world();
+
+        if (this.axis !== null) {
+            gizmo_drag_plane_normal(
+                this.#plane_normal,
+                this.mode, this.axis, this.space,
+                this.worldQuaternion,
+                this.eye, this.#camera_forward
+            );
+        }
+
+        super.update();
+    }
+
+    /**
+     * One frame of the gizmo, onto the debug-draw pass.
+     */
+    #record() {
+        if (!this.visible || this.object === -1) {
+            return;
+        }
+
+        gizmo_draw(
+            this.mode,
+            this.worldPosition,
+            this.#handle_rotation,
+            this.#handle_size,
+            this.axis,
+            this.#camera_forward
+        );
+    }
+
+    /**
+     * The world ray under a pointer, into the module's own scratch.
+     *
+     * @param {{x:number, y:number}} pointer clip space
+     */
+    #pointer_ray(pointer) {
+        this.graphics.viewportProjectionRay(pointer.x, pointer.y, ray_origin, ray_direction);
+    }
+
+    pointerHover(pointer) {
+
+        if (this.object === -1 || this.dragging === true) return;
+
+        this.#pointer_ray(pointer);
+
+        this.axis = gizmo_pick_handle(
+            gizmo_handles_of_mode(this.mode),
+            ray_origin, ray_direction,
+            this.worldPosition, this.#handle_rotation, this.#handle_size
+        );
+
+    }
+
+    pointerDown(pointer) {
+
+        if (this.object === -1 || this.dragging === true || pointer.button !== 0) return;
+
+        if (this.axis === null) return;
+
+        const ot = this.object_transform;
+
+        this.#pointer_ray(pointer);
+
+        gizmo_drag_plane_normal(
+            this.#plane_normal,
+            this.mode, this.axis, this.space,
+            ot.rotation,
+            this.eye, this.#camera_forward
+        );
+
+        if (!gizmo_ray_plane_point(
+            scratch_point, ray_origin, ray_direction, ot.translation, this.#plane_normal
+        )) {
+            // the drag surface is edge-on to the pointer, so there is no point on it to drag from
+            return;
+        }
+
+        this._positionStart.set(ot.translation_x, ot.translation_y, ot.translation_z);
+        this._quaternionStart.set(ot.rotation_x, ot.rotation_y, ot.rotation_z, ot.rotation_w);
+        this._scaleStart.set(ot.scale_x, ot.scale_y, ot.scale_z);
+
+        this.worldPositionStart.set(ot.translation_x, ot.translation_y, ot.translation_z);
+        this.worldQuaternionStart.set(ot.rotation_x, ot.rotation_y, ot.rotation_z, ot.rotation_w);
+        this._worldScaleStart.set(ot.scale_x, ot.scale_y, ot.scale_z);
+
+        this.pointStart.copy(scratch_point).sub(this.worldPositionStart);
+
+        this.dragging = true;
+
+        _mouseDownEvent.mode = this.mode;
+        this.dispatchEvent(_mouseDownEvent);
+
+    }
+
+    /**
+     *
+     * @param {{type:string}} event
+     */
+    dispatchEvent(event) {
+        this.entity.sendEvent(event.type, event);
+    }
+
+    pointerMove(pointer) {
+
+        const axis = this.axis;
+        const mode = this.mode;
+        const object = this.object;
+
+        let space = this.space;
+
+        if (mode === TransformMode.Scale) {
+
+            space = 'local';
+
+        } else if (axis === 'E' || axis === 'XYZE' || axis === 'XYZ') {
+
+            space = 'world';
+
+        }
+
+        if (object === -1 || axis === null || this.dragging === false || pointer.button !== -1) return;
+
+        const object_transform = this.object_transform;
+
+        this.#pointer_ray(pointer);
+
+        if (!gizmo_ray_plane_point(
+            scratch_point, ray_origin, ray_direction, this.worldPositionStart, this.#plane_normal
+        )) {
+            return;
+        }
+
+        this.pointEnd.copy(scratch_point).sub(this.worldPositionStart);
+
+        if (mode === TransformMode.Translate) {
+
+            // Apply translate
+
+            this._offset.copy(this.pointEnd).sub(this.pointStart);
+
+            if (space === 'local' && axis !== 'XYZ') {
+
+                this._offset.applyQuaternion(this._worldQuaternionInv);
+
+            }
+
+            if (axis.indexOf('X') === -1) this._offset.x = 0;
+            if (axis.indexOf('Y') === -1) this._offset.y = 0;
+            if (axis.indexOf('Z') === -1) this._offset.z = 0;
+
+            if (space === 'local' && axis !== 'XYZ') {
+
+                this._offset.applyQuaternion(this._quaternionStart);
+
+            }
+
+            /*
+             The candidate lives in a vector rather than a scratch transform: snapping in local
+             space rotates it, and rotating is something a Vector3 does and four numbers inside a
+             Transform64 do not.
+            */
+            scratch_translation.set(
+                this._offset.x + this._positionStart.x,
+                this._offset.y + this._positionStart.y,
+                this._offset.z + this._positionStart.z
+            );
+
+            // Apply translation snap; snapping operates on the candidate position — the
+            // controlled object is an entity id, Transforms are world-space by contract
+            if (this.translationSnap) {
+
+                if (space === 'local') {
+
+                    scratch_translation.applyQuaternion(
+                        scratch_quaternion.copy(this._quaternionStart).invert()
+                    );
+
+                }
+
+                if (axis.search('X') !== -1) {
+
+                    scratch_translation.setX(
+                        Math.round(scratch_translation.x / this.translationSnap) * this.translationSnap
+                    );
+
+                }
+
+                if (axis.search('Y') !== -1) {
+
+                    scratch_translation.setY(
+                        Math.round(scratch_translation.y / this.translationSnap) * this.translationSnap
+                    );
+
+                }
+
+                if (axis.search('Z') !== -1) {
+
+                    scratch_translation.setZ(
+                        Math.round(scratch_translation.z / this.translationSnap) * this.translationSnap
+                    );
+
+                }
+
+                if (space === 'local') {
+
+                    scratch_translation.applyQuaternion(this._quaternionStart);
+
+                }
+
+            }
+
+            // write - the translation IS the matrix's own column, so nothing is left stale
+            object_transform.setTranslation(
+                scratch_translation.x, scratch_translation.y, scratch_translation.z
+            );
+
+        } else if (mode === TransformMode.Scale) {
+
+            if (axis.search('XYZ') !== -1) {
+
+                let d = this.pointEnd.length() / this.pointStart.length();
+
+                if (this.pointEnd.dot(this.pointStart) < 0) d *= -1;
+
+                scratch_vector_2.set(d, d, d);
+
+            } else {
+
+                scratch_vector.copy(this.pointStart);
+                scratch_vector_2.copy(this.pointEnd);
+
+                scratch_vector.applyQuaternion(this._worldQuaternionInv);
+                scratch_vector_2.applyQuaternion(this._worldQuaternionInv);
+
+                scratch_vector_2.divide(scratch_vector);
+
+                if (axis.search('X') === -1) {
+
+                    scratch_vector_2.x = 1;
+
+                }
+
+                if (axis.search('Y') === -1) {
+
+                    scratch_vector_2.y = 1;
+
+                }
+
+                if (axis.search('Z') === -1) {
+
+                    scratch_vector_2.z = 1;
+
+                }
+
+            }
+
+            // Apply scale
+
+            // the scale is computed in a Vector3 and written once: a transform keeps its scale as
+            // three numbers, with no multiply or per-axis setter of its own
+            scratch_scale.copy(this._scaleStart);
+            scratch_scale.multiply(scratch_vector_2);
+
+            if (this.scaleSnap) {
+
+                if (axis.search('X') !== -1) {
+
+                    scratch_scale.setX(Math.round(scratch_scale.x / this.scaleSnap) * this.scaleSnap || this.scaleSnap);
+
+                }
+
+                if (axis.search('Y') !== -1) {
+
+                    scratch_scale.setY(Math.round(scratch_scale.y / this.scaleSnap) * this.scaleSnap || this.scaleSnap);
+
+                }
+
+                if (axis.search('Z') !== -1) {
+
+                    scratch_scale.setZ(Math.round(scratch_scale.z / this.scaleSnap) * this.scaleSnap || this.scaleSnap);
+
+                }
+
+            }
+
+            object_transform.setScale(scratch_scale.x, scratch_scale.y, scratch_scale.z);
+            object_transform.updateMatrix();
+
+        } else if (mode === TransformMode.Rotate) {
+
+            this._offset.copy(this.pointEnd).sub(this.pointStart);
+
+            const speed = ROTATION_SPEED / this.worldPosition.distanceTo(this.cameraPosition);
+
+            if (axis === 'E') {
+
+                this.rotationAxis.copy(this.eye);
+                this.rotationAngle = this.pointEnd.angleTo(this.pointStart);
+
+                this._startNorm.copy(this.pointStart).normalize();
+                this._endNorm.copy(this.pointEnd).normalize();
+
+                this.rotationAngle *= (this._endNorm.cross(this._startNorm).dot(this.eye) < 0 ? 1 : -1);
+
+            } else if (axis === 'XYZE') {
+
+                this.rotationAxis.copy(this._offset).cross(this.eye).normalize();
+                this.rotationAngle = this._offset.dot(scratch_vector.copy(this.rotationAxis).cross(this.eye)) * speed;
+
+            } else if (axis === 'X' || axis === 'Y' || axis === 'Z') {
+
+                this.rotationAxis.copy(UNIT[axis]);
+
+                scratch_vector.copy(UNIT[axis]);
+
+                if (space === 'local') {
+
+                    scratch_vector.applyQuaternion(this.worldQuaternion);
+
+                }
+
+                this.rotationAngle = this._offset.dot(scratch_vector.cross(this.eye).normalize()) * speed;
+
+            }
+
+            // Apply rotation snap
+
+            if (this.rotationSnap) this.rotationAngle = Math.round(this.rotationAngle / this.rotationSnap) * this.rotationSnap;
+
+            /*
+             Apply rotate. The composition runs entirely in quaternions and lands on the transform
+             once: a Transform64's rotation is four numbers in its array, so there is no quaternion
+             there to multiply, and `set` on the view means the typed-array one, which takes an
+             array and quietly does nothing with four loose numbers.
+            */
+            if (space === 'local' && axis !== 'E' && axis !== 'XYZE') {
+
+                scratch_quaternion.copy(this._quaternionStart);
+                scratch_quaternion.multiply(
+                    scratch_quaternion_2.fromAxisAngle(this.rotationAxis, this.rotationAngle)
+                );
+
+            } else {
+
+                scratch_quaternion.fromAxisAngle(this.rotationAxis, this.rotationAngle);
+                scratch_quaternion.multiply(this._quaternionStart);
+
+            }
+
+            scratch_quaternion.normalize();
+
+            object_transform.setRotation(
+                scratch_quaternion.x, scratch_quaternion.y,
+                scratch_quaternion.z, scratch_quaternion.w
+            );
+            object_transform.updateMatrix();
+        }
+
+        this.dispatchEvent(_changeEvent);
+        this.dispatchEvent(_objectChangeEvent);
+
+    }
+
+    pointerUp(pointer) {
+
+        if (pointer.button !== 0) return;
+
+        if (this.dragging && (this.axis !== null)) {
+
+            _mouseUpEvent.mode = this.mode;
+            this.dispatchEvent(_mouseUpEvent);
+
+        }
+
+        this.dragging = false;
+        this.axis = null;
+
+    }
+
+    dispose() {
+
+        this.domElement.removeEventListener('pointerdown', this._onPointerDown);
+        this.domElement.removeEventListener('pointermove', this._onPointerHover);
+        this.domElement.removeEventListener('pointermove', this._onPointerMove);
+        this.domElement.removeEventListener('pointerup', this._onPointerUp);
+
+        this.graphics.on.preRender.remove(this.#draw);
+
+    }
+
+    /**
+     * Set current object
+     * @param {number} entity
+     * @returns {TransformControls}
+     */
+    attach(entity) {
+        assert.isNonNegativeInteger(entity, 'entity');
+
+        this.object = entity;
+
+        this.visible = true;
+
+        return this;
+
+    }
+
+    /**
+     *
+     * @returns {Transform64|undefined}
+     */
+    get object_transform() {
+        const ecd = this.entity.dataset;
+
+        return ecd.getComponent(this.object, Transform64);
+    }
+
+    // Detatch from object
+    detach() {
+
+        this.object = -1;
+
+        this.visible = false;
+        this.axis = null;
+
+        // a drag in flight has no target anymore
+        this.dragging = false;
+
+        return this;
+
+    }
+
+    reset() {
+
+        if (!this.enabled) return;
+
+        if (this.dragging) {
+
+            this.object_transform.setTranslation(this._positionStart.x, this._positionStart.y, this._positionStart.z);
+            this.object_transform.setRotation(
+                this._quaternionStart.x, this._quaternionStart.y,
+                this._quaternionStart.z, this._quaternionStart.w
+            );
+            this.object_transform.setScale(
+                this._scaleStart.x, this._scaleStart.y, this._scaleStart.z
+            );
+            this.object_transform.updateMatrix();
+
+            this.dispatchEvent(_changeEvent);
+            this.dispatchEvent(_objectChangeEvent);
+
+            this.pointStart.copy(this.pointEnd);
+
+        }
+
+    }
+
+    // TODO: deprecate
+
+    getMode() {
+
+        return this.mode;
+
+    }
+
+    setMode(mode) {
+
+        this.mode = mode;
+
+    }
+
+    setTranslationSnap(translationSnap) {
+
+        this.translationSnap = translationSnap;
+
+    }
+
+    setRotationSnap(rotationSnap) {
+
+        this.rotationSnap = rotationSnap;
+
+    }
+
+    setScaleSnap(scaleSnap) {
+
+        this.scaleSnap = scaleSnap;
+
+    }
+
+    setSize(size) {
+
+        this.size = size;
+
+    }
+
+    setSpace(space) {
+
+        this.space = space;
+
+    }
+
+}
+
+// mouse / touch event handlers
+
+function getPointer(event) {
+
+    if (this.domElement.ownerDocument.pointerLockElement) {
+
+        return {
+            x: 0,
+            y: 0,
+            button: event.button
+        };
+
+    } else {
+
+        const rect = this.domElement.getBoundingClientRect();
+
+        return {
+            x: (event.clientX - rect.left) / rect.width * 2 - 1,
+            y: -(event.clientY - rect.top) / rect.height * 2 + 1,
+            button: event.button
+        };
+
+    }
+
+}
+
+function onPointerHover(event) {
+
+    if (!this.enabled) return;
+
+    switch (event.pointerType) {
+
+        case 'mouse':
+        case 'pen':
+            this.pointerHover(this._getPointer(event));
+            break;
+
+    }
+
+}
+
+function onPointerDown(event) {
+
+    if (!this.enabled) return;
+
+    if (!document.pointerLockElement) {
+
+        this.domElement.setPointerCapture(event.pointerId);
+
+    }
+
+    this.domElement.addEventListener('pointermove', this._onPointerMove);
+
+    this.pointerHover(this._getPointer(event));
+    this.pointerDown(this._getPointer(event));
+
+}
+
+function onPointerMove(event) {
+
+    if (!this.enabled) return;
+
+    this.pointerMove(this._getPointer(event));
+
+}
+
+function onPointerUp(event) {
+
+    if (!this.enabled) return;
+
+    this.domElement.releasePointerCapture(event.pointerId);
+
+    this.domElement.removeEventListener('pointermove', this._onPointerMove);
+
+    this.pointerUp(this._getPointer(event));
+
+}
+
+export { TransformControls };