@woosh/meep-engine 3.11.2 → 3.12.0

package/src/engine/graphics3/TooltipComponentSystem.js

@@ -0,0 +1,328 @@
+import { assert } from "../../core/assert.js";
+import Rectangle from "../../core/geom/2d/Rectangle.js";
+import { Vector2 } from "../../core/geom/Vector2.js";
+import Vector3 from "../../core/geom/Vector3.js";
+import { VisualTip } from "../../view/tooltip/VisualTip.js";
+import { System } from "../ecs/System.js";
+import { TooltipComponent } from "../ecs/tooltip/TooltipComponent.js";
+import { PickingQuery } from "./PickingQuery.js";
+import { PickingResult } from "./PickingResult.js";
+
+/**
+ * @type {Vector2}
+ */
+const SCRATCH_POINT = new Vector2();
+
+/**
+ * @type {Vector3}
+ */
+const SCRATCH_ORIGIN = new Vector3();
+
+/**
+ * @type {Vector3}
+ */
+const SCRATCH_DIRECTION = new Vector3();
+
+/**
+ * How far from the pointer, in pixels, the rectangle a tooltip is anchored to sits.
+ *
+ * @type {number}
+ */
+const ANCHOR_MARGIN = 10;
+
+/**
+ * Shows an entity's tooltip when the pointer is over it, under Shade.
+ *
+ * **The target is a promise, and that is the visible difference.** The renderer this replaces
+ * answered "what is under the pointer" inside the call that asked, by walking every visible mesh and
+ * raycasting three's geometry. Picking here is asynchronous and batched by contract (I-9), because
+ * the backend it is built for reads entity ids off the visibility buffer — a frame late, a batch at
+ * a time. So the answer arrives a tick after the question, and a tooltip appears a tick later than
+ * it used to. That is a change to the UI's timing, not to what it points at.
+ *
+ * **One ray, one answer, and it is the nearest thing.** The old path tested only entities that
+ * carried a tooltip, so a chest behind a wall described itself through the wall. This asks what the
+ * pointer is on and takes what comes back: something in front without a tooltip means no tooltip,
+ * which is both what the player can see and the only thing an id read off a pixel could ever say.
+ *
+ * **{@link Pickable} governs what can be found.** An entity with a tooltip and no `Pickable` is not
+ * in the picking index and has no tooltip in practice — the opt-in is authored next to the tooltip
+ * itself.
+ *
+ * The delay is a delay before a tooltip *appears*. Once one is up the pointer is asked about on
+ * every tick, so moving off an entity takes the tooltip away without waiting again.
+ */
+export class TooltipComponentSystem extends System {
+    dependencies = [TooltipComponent];
+
+    /**
+     * How long the pointer has to rest before a tooltip appears, in seconds.
+     *
+     * @type {number}
+     */
+    display_delay = 0.2;
+
+    /**
+     * The screen-space rectangle the tooltip points at. Follows the pointer while a tooltip is up.
+     *
+     * @readonly
+     * @type {Rectangle}
+     */
+    target = new Rectangle();
+
+    /**
+     * @type {GraphicsEngine}
+     */
+    #graphics;
+
+    /**
+     * @type {TooltipManager}
+     */
+    #tooltips;
+
+    /**
+     * @type {PointerDevice}
+     */
+    #pointer;
+
+    /**
+     * @type {Localization}
+     */
+    #localization;
+
+    /**
+     * @type {PickingSystem}
+     */
+    #picking;
+
+    /**
+     * @type {VisualTip|null}
+     */
+    #tip = null;
+
+    /**
+     * @type {number}
+     */
+    #tip_entity = PickingResult.NOTHING;
+
+    /**
+     * @type {number}
+     */
+    #time_since_pointer_moved = 0;
+
+    /**
+     * Whether a pick is out and has not answered yet. One question at a time: a second would be
+     * asked about the same pointer position as the first.
+     *
+     * @type {boolean}
+     */
+    #query_in_flight = false;
+
+    /**
+     * Whether the system is between {@link startup} and {@link shutdown}. An answer that arrives
+     * after the system has stopped is not acted on — the level it describes is being taken down.
+     *
+     * @type {boolean}
+     */
+    #running = false;
+
+    /**
+     * @param {GraphicsEngine} graphics
+     * @param {TooltipManager} tooltips
+     * @param {PointerDevice} pointer
+     * @param {Localization} localization
+     * @param {PickingSystem} picking
+     */
+    constructor({ graphics, tooltips, pointer, localization, picking }) {
+        super();
+
+        assert.defined(graphics, 'graphics');
+        assert.defined(tooltips, 'tooltips');
+        assert.defined(pointer, 'pointer');
+        assert.defined(localization, 'localization');
+        assert.defined(picking, 'picking');
+
+        this.#graphics = graphics;
+        this.#tooltips = tooltips;
+        this.#pointer = pointer;
+        this.#localization = localization;
+        this.#picking = picking;
+    }
+
+    /**
+     * Which entity the tooltip currently on screen describes, or {@link PickingResult.NOTHING}.
+     *
+     * @returns {number}
+     */
+    get tip_entity() {
+        return this.#tip_entity;
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+
+        this.#running = true;
+
+        this.#pointer.position.onChanged.add(this.#handle_pointer_moved, this);
+    }
+
+    async shutdown(entityManager) {
+        this.#running = false;
+
+        this.#pointer.position.onChanged.remove(this.#handle_pointer_moved, this);
+
+        this.#clear_tip();
+    }
+
+    /**
+     * @param {TooltipComponent} tooltip
+     * @param {number} entity
+     */
+    unlink(tooltip, entity) {
+        if (entity === this.#tip_entity) {
+            // whatever the tooltip described has stopped describing itself
+            this.#clear_tip();
+        }
+    }
+
+    update(time_delta) {
+        this.#time_since_pointer_moved += time_delta;
+
+        if (this.#query_in_flight) {
+            return;
+        }
+
+        if (this.entityManager.dataset === null) {
+            this.#clear_tip();
+
+            return;
+        }
+
+        if (this.#graphics.domElement !== this.#pointer.getTargetElement()) {
+            // the pointer is over the GUI, or off the page — the game field is not what it is on
+            this.#clear_tip();
+
+            return;
+        }
+
+        if (this.#tip === null && this.#time_since_pointer_moved < this.display_delay) {
+            return;
+        }
+
+        this.#ask();
+    }
+
+    #handle_pointer_moved() {
+        this.#time_since_pointer_moved = 0;
+
+        if (this.#tip !== null) {
+            this.#anchor_to_pointer();
+        }
+    }
+
+    #anchor_to_pointer() {
+        const position = this.#pointer.position;
+
+        this.target.set(
+            position.x - ANCHOR_MARGIN,
+            position.y - ANCHOR_MARGIN,
+            ANCHOR_MARGIN * 2,
+            ANCHOR_MARGIN * 2
+        );
+    }
+
+    /**
+     * The ray is built here and the answer acted on whenever it comes. Nothing checks whether the
+     * pointer has moved since: the answer describes where the pointer was, the next tick asks about
+     * where it is now, and a tooltip that lags the pointer by a tick is what the whole item is.
+     */
+    async #ask() {
+        const graphics = this.#graphics;
+        const position = this.#pointer.position;
+
+        SCRATCH_POINT.set(position.x, position.y);
+
+        graphics.normalizeViewportPoint(SCRATCH_POINT, SCRATCH_POINT);
+        graphics.viewportProjectionRay(
+            SCRATCH_POINT.x, SCRATCH_POINT.y,
+            SCRATCH_ORIGIN, SCRATCH_DIRECTION
+        );
+
+        const query = PickingQuery.from(SCRATCH_ORIGIN, SCRATCH_DIRECTION);
+
+        this.#query_in_flight = true;
+
+        const [result] = await this.#picking.pick([query]);
+
+        this.#query_in_flight = false;
+
+        this.#receive(result.entity);
+    }
+
+    /**
+     * @param {number} entity what the ray found, or {@link PickingResult.NOTHING}
+     */
+    #receive(entity) {
+        if (!this.#running) {
+            return;
+        }
+
+        if (entity === PickingResult.NOTHING) {
+            this.#clear_tip();
+
+            return;
+        }
+
+        const dataset = this.entityManager.dataset;
+
+        if (dataset === null || !dataset.entityExists(entity)) {
+            // the level went away, or that entity did, while the question was out
+            this.#clear_tip();
+
+            return;
+        }
+
+        const tooltip = dataset.getComponent(entity, TooltipComponent);
+
+        if (tooltip === undefined) {
+            this.#clear_tip();
+
+            return;
+        }
+
+        if (entity === this.#tip_entity) {
+            return;
+        }
+
+        this.#clear_tip();
+        this.#show_tip(entity, tooltip);
+    }
+
+    /**
+     * @param {number} entity
+     * @param {TooltipComponent} tooltip
+     */
+    #show_tip(entity, tooltip) {
+        this.#anchor_to_pointer();
+
+        const tooltips = this.#tooltips;
+        const text = this.#localization.getString(tooltip.key);
+
+        const tip = new VisualTip(this.target, () => tooltips.getGML().compile(text));
+
+        this.#tip = tip;
+        this.#tip_entity = entity;
+
+        tooltips.add(tip);
+    }
+
+    #clear_tip() {
+        if (this.#tip !== null) {
+            this.#tooltips.remove(this.#tip);
+
+            this.#tip = null;
+        }
+
+        this.#tip_entity = PickingResult.NOTHING;
+    }
+}

package/src/engine/graphics3/TooltipComponentSystem3.d.ts

@@ -1,65 +1,10 @@
 /**
- * Shows an entity's tooltip when the pointer is over it, under Shade.
+ * @deprecated Renamed to {@link TooltipComponentSystem}. The trailing `3` marked the 2.x → 3.x renderer transition;
+ * the 2.x name it disambiguated against is gone, so the suffix no longer distinguishes anything.
  *
- * **The target is a promise, and that is the visible difference.** The renderer this replaces
- * answered "what is under the pointer" inside the call that asked, by walking every visible mesh and
- * raycasting three's geometry. Picking here is asynchronous and batched by contract (I-9), because
- * the backend it is built for reads entity ids off the visibility buffer — a frame late, a batch at
- * a time. So the answer arrives a tick after the question, and a tooltip appears a tick later than
- * it used to. That is a change to the UI's timing, not to what it points at.
- *
- * **One ray, one answer, and it is the nearest thing.** The old path tested only entities that
- * carried a tooltip, so a chest behind a wall described itself through the wall. This asks what the
- * pointer is on and takes what comes back: something in front without a tooltip means no tooltip,
- * which is both what the player can see and the only thing an id read off a pixel could ever say.
- *
- * **{@link Pickable} governs what can be found.** An entity with a tooltip and no `Pickable` is not
- * in the picking index and has no tooltip in practice — the opt-in is authored next to the tooltip
- * itself.
- *
- * The delay is a delay before a tooltip *appears*. Once one is up the pointer is asked about on
- * every tick, so moving off an entity takes the tooltip away without waiting again.
+ * Kept as a re-export rather than removed: this is a library, and an import path is as much a
+ * published interface as a class name.
  */
-export class TooltipComponentSystem3 extends System<any> {
-    /**
-     * @param {GraphicsEngine3} graphics
-     * @param {TooltipManager} tooltips
-     * @param {PointerDevice} pointer
-     * @param {Localization} localization
-     * @param {PickingSystem3} picking
-     */
-    constructor({ graphics, tooltips, pointer, localization, picking }: GraphicsEngine3);
-    dependencies: (typeof TooltipComponent)[];
-    /**
-     * How long the pointer has to rest before a tooltip appears, in seconds.
-     *
-     * @type {number}
-     */
-    display_delay: number;
-    /**
-     * The screen-space rectangle the tooltip points at. Follows the pointer while a tooltip is up.
-     *
-     * @readonly
-     * @type {Rectangle}
-     */
-    readonly target: Rectangle;
-    /**
-     * Which entity the tooltip currently on screen describes, or {@link PickingResult.NOTHING}.
-     *
-     * @returns {number}
-     */
-    get tip_entity(): number;
-    startup(entityManager: any): Promise<void>;
-    shutdown(entityManager: any): Promise<void>;
-    /**
-     * @param {TooltipComponent} tooltip
-     * @param {number} entity
-     */
-    unlink(tooltip: TooltipComponent, entity: number): void;
-    update(time_delta: any): void;
-    #private;
-}
-import { System } from "../ecs/System.js";
-import { TooltipComponent } from "../ecs/tooltip/TooltipComponent.js";
-import Rectangle from "../../core/geom/2d/Rectangle.js";
+export const TooltipComponentSystem3: typeof TooltipComponentSystem;
+import { TooltipComponentSystem } from "./TooltipComponentSystem.js";
 //# sourceMappingURL=TooltipComponentSystem3.d.ts.map

package/src/engine/graphics3/TooltipComponentSystem3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TooltipComponentSystem3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/TooltipComponentSystem3.js"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IA0EI;;;;;;OAMG;IACH,qFAcC;IA9FD,0CAAkC;IAElC;;;;OAIG;IACH,eAFU,MAAM,CAEI;IAEpB;;;;;OAKG;IACH,iBAFU,SAAS,CAEM;IAiFzB;;;;OAIG;IACH,yBAEC;IAED,2CAMC;IAED,4CAMC;IAED;;;OAGG;IACH,gBAHW,gBAAgB,UAChB,MAAM,QAOhB;IAED,8BAyBC;;CAmHJ;uBAlUsB,kBAAkB;iCACR,oCAAoC;sBAL/C,iCAAiC"}
+{"version":3,"file":"TooltipComponentSystem3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/TooltipComponentSystem3.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,oEAA8D;uCATvB,6BAA6B"}