@woosh/meep-engine 3.11.2 → 3.12.0

package/src/engine/graphics3/TooltipComponentSystem3.js

@@ -1,328 +1,10 @@
-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";
+import { TooltipComponentSystem } from "./TooltipComponentSystem.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.
+ * @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.
  *
- * **{@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 {
-    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 {GraphicsEngine3}
-     */
-    #graphics;
-
-    /**
-     * @type {TooltipManager}
-     */
-    #tooltips;
-
-    /**
-     * @type {PointerDevice}
-     */
-    #pointer;
-
-    /**
-     * @type {Localization}
-     */
-    #localization;
-
-    /**
-     * @type {PickingSystem3}
-     */
-    #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 {GraphicsEngine3} graphics
-     * @param {TooltipManager} tooltips
-     * @param {PointerDevice} pointer
-     * @param {Localization} localization
-     * @param {PickingSystem3} 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;
-    }
-}
+export const TooltipComponentSystem3 = TooltipComponentSystem;

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

@@ -0,0 +1,73 @@
+/**
+ * Draws {@link Trail3D}'s tubes under Shade, on the dynamic-geometry path.
+ *
+ * **A trail is dynamic content by definition** — every knot of it is rewritten as the entity moves
+ * and every knot's opacity as it ages — so it goes down S4's dedicated non-meshlet path (D5/I-10),
+ * the same one particles, paths and debug shapes take.
+ *
+ * **The simulation is not this system's, and that is deliberate.** {@link seed_trail_tube} and
+ * {@link advance_trail} are what the legacy `Trail3DSystem` runs too: the knots a trail lays down
+ * are a property of the trail, not of the renderer drawing it, and two implementations of them
+ * would be two trails that age differently. What is this system's is turning those knots into
+ * vertices, once a frame, per trail.
+ *
+ * **Every trail is rewritten every frame it exists**, moving or not, because the simulator ages
+ * every knot on every tick and the age is what the vertex opacity carries. There is no quiet trail
+ * — a trail that has stopped is a trail fading out.
+ *
+ * **What the tube material had and this does not**: a texture, and per-trail depth writing. The
+ * dynamic path has one pipeline, one vertex layout — position and colour — and one blend mode
+ * (straight alpha over the finished scene, depth tested, never written), which is what a trail
+ * wants and what the game's trails are authored as. `Trail3D.textureURL` therefore draws untinted
+ * here; nothing in the game's own effects sets it to anything a flat colour does not carry.
+ */
+export class Trail3DSystem extends System<any> {
+    /**
+     * @param {GraphicsEngine} graphics
+     */
+    constructor(graphics: GraphicsEngine);
+    dependencies: (typeof Transform | typeof Trail3D)[];
+    /**
+     * What the pass draws. Read-only — the meshes follow the entities.
+     *
+     * @returns {DynamicMeshBatch}
+     */
+    get batch(): DynamicMeshBatch;
+    startup(entityManager: any): Promise<void>;
+    shutdown(entityManager: any): Promise<void>;
+    /**
+     * @param {Trail3D} trail
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    link(trail: Trail3D, transform: Transform, entity: number): void;
+    /**
+     * @param {Trail3D} trail
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    unlink(trail: Trail3D, transform: Transform, entity: number): void;
+    update(timeDelta: any): void;
+    /**
+     * @param {FrameContext} frame
+     */
+    record(frame: FrameContext): void;
+    #private;
+}
+/**
+ * A trail is drawn into the scene and is concealed by the fog of war like anything else in it.
+ */
+export class TrailExtension extends RenderExtension {
+    /**
+     * @param {Trail3DSystem} system
+     */
+    constructor(system: Trail3DSystem);
+    record(frame: any): void;
+    #private;
+}
+import { System } from "../ecs/System.js";
+import { Transform } from "../ecs/transform/Transform.js";
+import Trail3D from "../graphics/ecs/trail3d/Trail3D.js";
+import { DynamicMeshBatch } from "../../shade/renderer/scene/DynamicMeshBatch.js";
+import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
+//# sourceMappingURL=Trail3DSystem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Trail3DSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/Trail3DSystem.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IA0CI;;OAEG;IACH,sCAMC;IAlDD,oDAAoC;IAgCpC;;;;OAIG;IACH,8BAEC;IAaD,2CAIC;IAED,4CAWC;IAED;;;;OAIG;IACH,YAJW,OAAO,aACP,SAAS,UACT,MAAM,QAkBhB;IAED;;;;OAIG;IACH,cAJW,OAAO,aACP,SAAS,UACT,MAAM,QAiBhB;IAED,6BAYC;IAED;;OAEG;IACH,kCAeC;;CACJ;AAED;;GAEG;AACH;IAUI;;OAEG;IACH,oBAFW,aAAa,EAMvB;IAED,yBAEC;;CACJ;uBAnNsB,kBAAkB;0BACf,+BAA+B;oBAGrC,oCAAoC;iCALvB,gDAAgD;gCAJjD,mDAAmD"}

package/src/engine/graphics3/Trail3DSystem.js

@@ -0,0 +1,221 @@
+import { assert } from "../../core/assert.js";
+import { GPUDynamicMeshRenderer } from "../../shade/renderer/dynamic/GPUDynamicMeshRenderer.js";
+import { Geometry } from "../../shade/renderer/geometry/Geometry.js";
+import { FramePhase } from "../../shade/renderer/extension/FramePhase.js";
+import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
+import { SceneColor } from "../../shade/renderer/extension/SceneColor.js";
+import { ViewTextures } from "../../shade/renderer/extension/ViewTextures.js";
+import { DynamicMesh } from "../../shade/renderer/scene/DynamicMesh.js";
+import { DynamicMeshBatch } from "../../shade/renderer/scene/DynamicMeshBatch.js";
+import { System } from "../ecs/System.js";
+import { Transform } from "../ecs/transform/Transform.js";
+import { advance_trail } from "../graphics/ecs/trail3d/advance_trail.js";
+import { seed_trail_tube } from "../graphics/ecs/trail3d/seed_trail_tube.js";
+import Trail3D from "../graphics/ecs/trail3d/Trail3D.js";
+import { Trail3DFlags } from "../graphics/ecs/trail3d/Trail3DFlags.js";
+import {
+    TubeXFixedPhysicsSimulator
+} from "../graphics/trail/tube/simulator/TubeXFixedPhysicsSimulator.js";
+import { trail_tube_write_geometry } from "./trail/trail_tube_write_geometry.js";
+
+/**
+ * Draws {@link Trail3D}'s tubes under Shade, on the dynamic-geometry path.
+ *
+ * **A trail is dynamic content by definition** — every knot of it is rewritten as the entity moves
+ * and every knot's opacity as it ages — so it goes down S4's dedicated non-meshlet path (D5/I-10),
+ * the same one particles, paths and debug shapes take.
+ *
+ * **The simulation is not this system's, and that is deliberate.** {@link seed_trail_tube} and
+ * {@link advance_trail} are what the legacy `Trail3DSystem` runs too: the knots a trail lays down
+ * are a property of the trail, not of the renderer drawing it, and two implementations of them
+ * would be two trails that age differently. What is this system's is turning those knots into
+ * vertices, once a frame, per trail.
+ *
+ * **Every trail is rewritten every frame it exists**, moving or not, because the simulator ages
+ * every knot on every tick and the age is what the vertex opacity carries. There is no quiet trail
+ * — a trail that has stopped is a trail fading out.
+ *
+ * **What the tube material had and this does not**: a texture, and per-trail depth writing. The
+ * dynamic path has one pipeline, one vertex layout — position and colour — and one blend mode
+ * (straight alpha over the finished scene, depth tested, never written), which is what a trail
+ * wants and what the game's trails are authored as. `Trail3D.textureURL` therefore draws untinted
+ * here; nothing in the game's own effects sets it to anything a flat colour does not carry.
+ */
+export class Trail3DSystem extends System {
+    dependencies = [Trail3D, Transform];
+
+    /**
+     * @type {GraphicsEngine}
+     */
+    #graphics;
+
+    /**
+     * @type {GPUDynamicMeshRenderer}
+     */
+    #renderer = new GPUDynamicMeshRenderer();
+
+    /**
+     * @type {DynamicMeshBatch}
+     */
+    #batch = new DynamicMeshBatch();
+
+    /**
+     * @type {Map<number, {trail: Trail3D, transform: Transform, mesh: DynamicMesh}>}
+     */
+    #entries = new Map();
+
+    /**
+     * @type {TubeXFixedPhysicsSimulator}
+     */
+    #simulator = new TubeXFixedPhysicsSimulator();
+
+    /**
+     * @type {RenderExtension|null}
+     */
+    #extension = null;
+
+    /**
+     * What the pass draws. Read-only — the meshes follow the entities.
+     *
+     * @returns {DynamicMeshBatch}
+     */
+    get batch() {
+        return this.#batch;
+    }
+
+    /**
+     * @param {GraphicsEngine} graphics
+     */
+    constructor(graphics) {
+        super();
+
+        assert.defined(graphics, 'graphics');
+
+        this.#graphics = graphics;
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+
+        this.#extension = this.#graphics.add_extension(new TrailExtension(this));
+    }
+
+    async shutdown(entityManager) {
+        if (this.#extension !== null) {
+            this.#graphics.remove_extension(this.#extension);
+
+            this.#extension = null;
+        }
+
+        this.#renderer.destroy();
+
+        this.#batch.clear();
+        this.#entries.clear();
+    }
+
+    /**
+     * @param {Trail3D} trail
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    link(trail, transform, entity) {
+        if (!trail.getFlag(Trail3DFlags.Built)) {
+            seed_trail_tube(trail, transform);
+        }
+
+        const mesh = DynamicMesh.from(new Geometry());
+
+        // the extrusion produces world-space vertices, so what the draw applies is identity — but a
+        // node's world transform is derived and stays unset until it is asked for
+        mesh.updateMatrices();
+
+        trail_tube_write_geometry(mesh.geometry, trail.tube);
+
+        this.#batch.add(mesh);
+
+        this.#entries.set(entity, { trail, transform, mesh });
+    }
+
+    /**
+     * @param {Trail3D} trail
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    unlink(trail, transform, entity) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        this.#batch.remove(entry.mesh);
+
+        // residency deliberately survives leaving the batch, so nothing else would free it
+        this.#renderer.release(entry.mesh.geometry);
+
+        this.#entries.delete(entity);
+
+        trail.dispose();
+    }
+
+    update(timeDelta) {
+        for (const entry of this.#entries.values()) {
+            const trail = entry.trail;
+
+            advance_trail(trail, entry.transform, timeDelta, this.#simulator);
+
+            // bounds are the GPU's business on this path (§4.5), so the flag the head raises has
+            // nobody else to answer it
+            trail.clearFlag(Trail3DFlags.BoundsNeedUpdate);
+
+            trail_tube_write_geometry(entry.mesh.geometry, trail.tube);
+        }
+    }
+
+    /**
+     * @param {FrameContext} frame
+     */
+    record(frame) {
+        if (this.#batch.count === 0) {
+            // nothing to draw, and the frame's colour is left exactly as it was
+            return;
+        }
+
+        const scene = frame.get(SceneColor);
+
+        scene.color = this.#renderer.graph_draw({
+            graph: frame.graph,
+            batch: this.#batch,
+            color: scene.color,
+            depth: frame.get(ViewTextures).depth,
+            camera: frame.view.camera.buffer
+        });
+    }
+}
+
+/**
+ * A trail is drawn into the scene and is concealed by the fog of war like anything else in it.
+ */
+export class TrailExtension extends RenderExtension {
+    name = "trails";
+
+    phase = FramePhase.AfterTransparency;
+
+    /**
+     * @type {Trail3DSystem}
+     */
+    #system;
+
+    /**
+     * @param {Trail3DSystem} system
+     */
+    constructor(system) {
+        super();
+
+        this.#system = system;
+    }
+
+    record(frame) {
+        this.#system.record(frame);
+    }
+}