@woosh/meep-engine 3.11.3 → 3.13.0

package/src/engine/graphics3/CameraSystem3.js

@@ -1,170 +1,10 @@
-import { assert } from "../../core/assert.js";
-import { SignalBinding } from "../../core/events/signal/SignalBinding.js";
-import { DEG_TO_RAD } from "../../core/math/DEG_TO_RAD.js";
-import { System } from "../ecs/System.js";
-import { Transform } from "../ecs/transform/Transform.js";
-import { Camera } from "../graphics/ecs/camera/Camera.js";
-import { camera_sync_from_transform } from "./camera_sync_from_transform.js";
+import { CameraSystem } from "./CameraSystem.js";
 
 /**
- * Drives the camera the frame is drawn from, from whichever camera entity is active.
+ * @deprecated Renamed to {@link CameraSystem}. 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 old system gave every camera entity a three camera of its own and pointed
- * `graphics.camera` at one of them. Shade's facade **owns** its camera — one of them, for the whole
- * engine — so this does the other thing: whichever entity is active has its pose and its lens copied
- * onto that one. Nothing is swapped, so there is no state to get out of step, and a camera entity
- * appearing or leaving cannot leave the renderer pointed at a camera nobody owns.
- *
- * **Read once per tick rather than followed by signal**, which is the opposite of how
- * {@link MeshSystem3} and {@link LightSystem3} work, for a reason that is specific to cameras: the
- * component's clip planes are plain fields whose setters write straight through to the three camera
- * object it used to own, so there is no signal to bind to. A camera that changed its near plane while
- * standing still would silently keep the old one. It also happens to be the cheaper arrangement — a
- * game camera moves on almost every frame, so a signal per property would fire constantly to do work
- * this does once.
+ * 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 CameraSystem3 extends System {
-    /**
-     * @type {GraphicsEngine3}
-     */
-    #graphics;
-
-    /**
-     * The camera entities present, and the binding watching each one's active flag.
-     *
-     * @type {Map<number, {camera: Camera, transform: Transform, binding: SignalBinding}>}
-     */
-    #entries = new Map();
-
-    /**
-     * Which entity is driving the render camera, or −1 when none is.
-     *
-     * @type {number}
-     */
-    #active = -1;
-
-    /**
-     * @param {GraphicsEngine3} graphics
-     */
-    constructor(graphics) {
-        super();
-
-        assert.equal(graphics.isGraphicsEngine, true, 'graphics.isGraphicsEngine !== true');
-
-        this.#graphics = graphics;
-
-        this.dependencies = [Camera, Transform];
-    }
-
-    async startup(entityManager) {
-        this.entityManager = entityManager;
-    }
-
-    async shutdown(entityManager) {
-        for (const entity of Array.from(this.#entries.keys())) {
-            this.#drop(entity);
-        }
-    }
-
-    /**
-     * Which entity is driving the render camera, or −1.
-     *
-     * @returns {number}
-     */
-    get active_entity() {
-        return this.#active;
-    }
-
-    /**
-     * @param {Camera} camera
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    link(camera, transform, entity) {
-        const binding = new SignalBinding(camera.active.onChanged, () => this.#elect());
-
-        binding.link();
-
-        this.#entries.set(entity, { camera, transform, binding });
-
-        this.#elect();
-    }
-
-    /**
-     * @param {Camera} camera
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    unlink(camera, transform, entity) {
-        this.#drop(entity);
-    }
-
-    /**
-     * Copy the active camera entity onto the camera Shade draws with, and its frustum back.
-     *
-     * @param {number} time_delta
-     */
-    update(time_delta) {
-        const entry = this.#entries.get(this.#active);
-
-        if (entry === undefined) {
-            // no camera entity is active; the facade keeps whatever it was last given, which is what
-            // lets a scene without a camera still render from wherever the last one left it
-            return;
-        }
-
-        const target = this.#graphics.camera.camera;
-
-        // degrees on the component, radians on Shade's; the facade's own `render` owns the aspect
-        // ratio, because only it knows what resolution the frame is going out at
-        target.fov = entry.camera.fov.getValue() * DEG_TO_RAD;
-        target.near = entry.camera.clip_near;
-        target.far = entry.camera.clip_far;
-
-        camera_sync_from_transform(target, entry.transform);
-
-        /*
-         The return trip. Gameplay asks what the camera can see — which armies to generate now,
-         which terrain tiles a scene has to have before it is shown — and the honest answer is the
-         frustum the renderer is drawing with, not a second one derived from the component. It is
-         copied rather than aliased because the renderer's camera is one object and any number of
-         camera entities can pass through it.
-        */
-        entry.camera.publishFrustum(target.frustum);
-    }
-
-    /**
-     * Settle on which entity drives the camera.
-     *
-     * First active one wins, and it is re-decided from scratch rather than tracked incrementally so
-     * that two entities both claiming to be active resolve the same way however they got there.
-     */
-    #elect() {
-        this.#active = -1;
-
-        for (const [entity, entry] of this.#entries) {
-            if (entry.camera.active.getValue()) {
-                this.#active = entity;
-
-                return;
-            }
-        }
-    }
-
-    /**
-     * @param {number} entity
-     */
-    #drop(entity) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined) {
-            return;
-        }
-
-        entry.binding.unlink();
-
-        this.#entries.delete(entity);
-
-        this.#elect();
-    }
-}
+export const CameraSystem3 = CameraSystem;

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

@@ -0,0 +1,72 @@
+/**
+ * Draws what {@link Gizmo} recorded this frame, under Shade.
+ *
+ * **The Shade half of the pair `GizmoRenderingPlugin` is the three half of.** The immediate-mode API
+ * a tool calls is renderer-neutral and records into buffers; this turns one frame of those buffers
+ * into geometry and puts it on the dynamic-mesh path (D5/D11), which is where every piece of
+ * generated content in this phase belongs.
+ *
+ * **One mesh, one geometry, rewritten every frame.** Debug drawing has no persistent objects to key
+ * anything on — a shape is a call, not a thing — so there is nothing to cache and nothing to
+ * release between frames. Colour rides the vertices rather than the mesh, which is what lets one
+ * draw carry a whole frame's worth of differently coloured shapes.
+ *
+ * **Blended and depth-tested, never depth-writing.** Debug shapes are occluded by the scene and
+ * occlude nothing, including each other: two overlapping solid shapes composite in the order they
+ * were recorded rather than by depth. Whether a gizmo should instead sit on top of everything is
+ * the gizmo's question and V6 answers it.
+ *
+ * **The recording is cleared once the frame that consumed it has been submitted**, on the same
+ * signal the three backend clears on. An immediate-mode API that leaks its contents keeps drawing a
+ * world that has moved on, so "what was drawn last frame is gone this frame" is a property of the
+ * pass rather than a courtesy of its callers.
+ */
+export class DebugDrawSystem extends System<any> {
+    /**
+     * @param {GraphicsEngine} graphics
+     */
+    constructor(graphics: GraphicsEngine);
+    /**
+     * Width of a drawn line, in CSS pixels of the display — so it is the same thickness whatever
+     * the device pixel ratio is and wherever the resolution controller has the frame this instant.
+     *
+     * **A property of the pass, not of a draw.** The recording API has no width — it is an
+     * immediate-mode debug surface, and one that asked every caller for a line width would be
+     * asking about the display rather than about the thing being drawn.
+     *
+     * @type {number}
+     */
+    line_width: number;
+    /**
+     * What the pass draws. Read-only — the geometry follows the recording.
+     *
+     * @returns {DynamicMeshBatch}
+     */
+    get batch(): DynamicMeshBatch;
+    startup(entityManager: any): Promise<void>;
+    shutdown(entityManager: any): Promise<void>;
+    /**
+     * @param {FrameContext} frame
+     */
+    record(frame: FrameContext): void;
+    #private;
+}
+/**
+ * **The single deliberate exception to the fog of war.** Everything else drawn into the scene is
+ * concealed by it; developer geometry that the fog can hide is a debugging tool that stops working
+ * exactly where debugging is needed, so this says so rather than relying on where it was registered.
+ */
+export class DebugDrawExtension extends RenderExtension {
+    /**
+     * @param {DebugDrawSystem} system
+     */
+    constructor(system: DebugDrawSystem);
+    after: (typeof FogOfWarExtension)[];
+    record(frame: any): void;
+    #private;
+}
+import { System } from "../ecs/System.js";
+import { DynamicMeshBatch } from "../../shade/renderer/scene/DynamicMeshBatch.js";
+import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
+import { FogOfWarExtension } from "./FogOfWarSystem.js";
+//# sourceMappingURL=DebugDrawSystem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DebugDrawSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/DebugDrawSystem.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAkEI;;OAEG;IACH,sCAcC;IAlFD;;;;;;;;;OASG;IACH,YAFU,MAAM,CAED;IA8Cf;;;;OAIG;IACH,8BAEC;IAqBD,2CAMC;IAED,4CAYC;IAED;;OAEG;IACH,kCAwBC;;CACJ;AAED;;;;GAIG;AACH;IAYI;;OAEG;IACH,oBAFW,eAAe,EAMzB;IAdD,oCAA4B;IAgB5B,yBAEC;;CACJ;uBAlMsB,kBAAkB;iCADR,gDAAgD;gCAJjD,mDAAmD;kCAFjD,qBAAqB"}

package/src/engine/graphics3/DebugDrawSystem.js

@@ -0,0 +1,205 @@
+import { assert } from "../../core/assert.js";
+import { GPUDynamicMeshRenderer } from "../../shade/renderer/dynamic/GPUDynamicMeshRenderer.js";
+import { Geometry } from "../../shade/renderer/geometry/Geometry.js";
+import { FogOfWarExtension } from "./FogOfWarSystem.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 { Gizmo } from "../graphics/render/gizmo/Gizmo.js";
+import { gizmo_view_from_camera } from "./debug/gizmo_view_from_camera.js";
+import { gizmo_write_geometry } from "./debug/gizmo_write_geometry.js";
+
+/**
+ * Draws what {@link Gizmo} recorded this frame, under Shade.
+ *
+ * **The Shade half of the pair `GizmoRenderingPlugin` is the three half of.** The immediate-mode API
+ * a tool calls is renderer-neutral and records into buffers; this turns one frame of those buffers
+ * into geometry and puts it on the dynamic-mesh path (D5/D11), which is where every piece of
+ * generated content in this phase belongs.
+ *
+ * **One mesh, one geometry, rewritten every frame.** Debug drawing has no persistent objects to key
+ * anything on — a shape is a call, not a thing — so there is nothing to cache and nothing to
+ * release between frames. Colour rides the vertices rather than the mesh, which is what lets one
+ * draw carry a whole frame's worth of differently coloured shapes.
+ *
+ * **Blended and depth-tested, never depth-writing.** Debug shapes are occluded by the scene and
+ * occlude nothing, including each other: two overlapping solid shapes composite in the order they
+ * were recorded rather than by depth. Whether a gizmo should instead sit on top of everything is
+ * the gizmo's question and V6 answers it.
+ *
+ * **The recording is cleared once the frame that consumed it has been submitted**, on the same
+ * signal the three backend clears on. An immediate-mode API that leaks its contents keeps drawing a
+ * world that has moved on, so "what was drawn last frame is gone this frame" is a property of the
+ * pass rather than a courtesy of its callers.
+ */
+export class DebugDrawSystem extends System {
+    /**
+     * Width of a drawn line, in CSS pixels of the display — so it is the same thickness whatever
+     * the device pixel ratio is and wherever the resolution controller has the frame this instant.
+     *
+     * **A property of the pass, not of a draw.** The recording API has no width — it is an
+     * immediate-mode debug surface, and one that asked every caller for a line width would be
+     * asking about the display rather than about the thing being drawn.
+     *
+     * @type {number}
+     */
+    line_width = 2;
+
+    /**
+     * @type {GraphicsEngine}
+     */
+    #graphics;
+
+    /**
+     * @type {GPUDynamicMeshRenderer}
+     */
+    #renderer = new GPUDynamicMeshRenderer();
+
+    /**
+     * @type {DynamicMeshBatch}
+     */
+    #batch = new DynamicMeshBatch();
+
+    /**
+     * @type {DynamicMesh}
+     */
+    #mesh = DynamicMesh.from(new Geometry());
+
+    /**
+     * @type {RenderExtension|null}
+     */
+    #extension = null;
+
+    /**
+     * @type {function}
+     */
+    #clear;
+
+    /**
+     * Where the camera is and what it looks along, refilled per frame — the pass runs once and
+     * nothing else reads this.
+     *
+     * @type {GizmoView}
+     */
+    #view = {
+        eye: new Float32Array(3),
+        forward: new Float32Array(3),
+        projection_scale: 1,
+        viewport_height: 1,
+        line_width: 1
+    };
+
+    /**
+     * What the pass draws. Read-only — the geometry follows the recording.
+     *
+     * @returns {DynamicMeshBatch}
+     */
+    get batch() {
+        return this.#batch;
+    }
+
+    /**
+     * @param {GraphicsEngine} graphics
+     */
+    constructor(graphics) {
+        super();
+
+        assert.defined(graphics, 'graphics');
+
+        this.#graphics = graphics;
+
+        // vertices are written in world space, so what the draw applies is identity — but a node's
+        // world transform is derived and stays unset until it is asked for
+        this.#mesh.updateMatrices();
+
+        this.#batch.add(this.#mesh);
+
+        this.#clear = () => Gizmo.clear();
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+
+        this.#extension = this.#graphics.add_extension(new DebugDrawExtension(this));
+
+        this.#graphics.on.postRender.add(this.#clear);
+    }
+
+    async shutdown(entityManager) {
+        if (this.#extension !== null) {
+            this.#graphics.remove_extension(this.#extension);
+
+            this.#extension = null;
+        }
+
+        this.#graphics.on.postRender.remove(this.#clear);
+
+        this.#renderer.destroy();
+
+        Gizmo.clear();
+    }
+
+    /**
+     * @param {FrameContext} frame
+     */
+    record(frame) {
+        gizmo_view_from_camera(
+            this.#view,
+            frame.view.camera.camera,
+            this.#graphics.viewport.size.y,
+            this.line_width
+        );
+
+        gizmo_write_geometry(this.#mesh.geometry, Gizmo, this.#view);
+
+        if (Gizmo.empty) {
+            // nothing was recorded, 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
+        });
+    }
+}
+
+/**
+ * **The single deliberate exception to the fog of war.** Everything else drawn into the scene is
+ * concealed by it; developer geometry that the fog can hide is a debugging tool that stops working
+ * exactly where debugging is needed, so this says so rather than relying on where it was registered.
+ */
+export class DebugDrawExtension extends RenderExtension {
+    name = "debug draw";
+
+    phase = FramePhase.AfterTransparency;
+
+    after = [FogOfWarExtension];
+
+    /**
+     * @type {DebugDrawSystem}
+     */
+    #system;
+
+    /**
+     * @param {DebugDrawSystem} system
+     */
+    constructor(system) {
+        super();
+
+        this.#system = system;
+    }
+
+    record(frame) {
+        this.#system.record(frame);
+    }
+}

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

@@ -1,72 +1,10 @@
 /**
- * Draws what {@link Gizmo} recorded this frame, under Shade.
+ * @deprecated Renamed to {@link DebugDrawSystem}. 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 Shade half of the pair `GizmoRenderingPlugin` is the three half of.** The immediate-mode API
- * a tool calls is renderer-neutral and records into buffers; this turns one frame of those buffers
- * into geometry and puts it on the dynamic-mesh path (D5/D11), which is where every piece of
- * generated content in this phase belongs.
- *
- * **One mesh, one geometry, rewritten every frame.** Debug drawing has no persistent objects to key
- * anything on — a shape is a call, not a thing — so there is nothing to cache and nothing to
- * release between frames. Colour rides the vertices rather than the mesh, which is what lets one
- * draw carry a whole frame's worth of differently coloured shapes.
- *
- * **Blended and depth-tested, never depth-writing.** Debug shapes are occluded by the scene and
- * occlude nothing, including each other: two overlapping solid shapes composite in the order they
- * were recorded rather than by depth. Whether a gizmo should instead sit on top of everything is
- * the gizmo's question and V6 answers it.
- *
- * **The recording is cleared once the frame that consumed it has been submitted**, on the same
- * signal the three backend clears on. An immediate-mode API that leaks its contents keeps drawing a
- * world that has moved on, so "what was drawn last frame is gone this frame" is a property of the
- * pass rather than a courtesy of its callers.
- */
-export class DebugDrawSystem3 extends System<any> {
-    /**
-     * @param {GraphicsEngine3} graphics
-     */
-    constructor(graphics: GraphicsEngine3);
-    /**
-     * Width of a drawn line, in CSS pixels of the display — so it is the same thickness whatever
-     * the device pixel ratio is and wherever the resolution controller has the frame this instant.
-     *
-     * **A property of the pass, not of a draw.** The recording API has no width — it is an
-     * immediate-mode debug surface, and one that asked every caller for a line width would be
-     * asking about the display rather than about the thing being drawn.
-     *
-     * @type {number}
-     */
-    line_width: number;
-    /**
-     * What the pass draws. Read-only — the geometry follows the recording.
-     *
-     * @returns {DynamicMeshBatch}
-     */
-    get batch(): DynamicMeshBatch;
-    startup(entityManager: any): Promise<void>;
-    shutdown(entityManager: any): Promise<void>;
-    /**
-     * @param {FrameContext} frame
-     */
-    record(frame: FrameContext): void;
-    #private;
-}
-/**
- * **The single deliberate exception to the fog of war.** Everything else drawn into the scene is
- * concealed by it; developer geometry that the fog can hide is a debugging tool that stops working
- * exactly where debugging is needed, so this says so rather than relying on where it was registered.
+ * 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 DebugDrawExtension extends RenderExtension {
-    /**
-     * @param {DebugDrawSystem3} system
-     */
-    constructor(system: DebugDrawSystem3);
-    after: (typeof FogOfWarExtension)[];
-    record(frame: any): void;
-    #private;
-}
-import { System } from "../ecs/System.js";
-import { DynamicMeshBatch } from "../../shade/renderer/scene/DynamicMeshBatch.js";
-import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
-import { FogOfWarExtension } from "./FogOfWarSystem3.js";
+export const DebugDrawSystem3: typeof DebugDrawSystem;
+import { DebugDrawSystem } from "./DebugDrawSystem.js";
 //# sourceMappingURL=DebugDrawSystem3.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"DebugDrawSystem3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/DebugDrawSystem3.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAkEI;;OAEG;IACH,uCAcC;IAlFD;;;;;;;;;OASG;IACH,YAFU,MAAM,CAED;IA8Cf;;;;OAIG;IACH,8BAEC;IAqBD,2CAMC;IAED,4CAYC;IAED;;OAEG;IACH,kCAwBC;;CACJ;AAED;;;;GAIG;AACH;IAYI;;OAEG;IACH,oBAFW,gBAAgB,EAM1B;IAdD,oCAA4B;IAgB5B,yBAEC;;CACJ;uBAlMsB,kBAAkB;iCADR,gDAAgD;gCAJjD,mDAAmD;kCAFjD,sBAAsB"}
+{"version":3,"file":"DebugDrawSystem3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/DebugDrawSystem3.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,sDAAgD;gCAThB,sBAAsB"}