@woosh/meep-engine 3.11.2 → 3.12.0

package/src/engine/graphics3/DebugDrawSystem3.js

@@ -1,205 +1,10 @@
-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 "./FogOfWarSystem3.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";
+import { DebugDrawSystem } from "./DebugDrawSystem.js";
 
 /**
- * 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.
+ * 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 DebugDrawSystem3 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 {GraphicsEngine3}
-     */
-    #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 {GraphicsEngine3} 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 {DebugDrawSystem3}
-     */
-    #system;
-
-    /**
-     * @param {DebugDrawSystem3} system
-     */
-    constructor(system) {
-        super();
-
-        this.#system = system;
-    }
-
-    record(frame) {
-        this.#system.record(frame);
-    }
-}
+export const DebugDrawSystem3 = DebugDrawSystem;

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

@@ -0,0 +1,81 @@
+/**
+ * Paints the game's decals into the G-buffer under Shade.
+ *
+ * **A decal is a surface override, not a tint** (D22): it carries albedo, a tangent-space normal,
+ * roughness, metalness and emission, and it writes them into the G-buffer before anything is lit —
+ * so ambient occlusion, screen-space reflection and shading all see a decal exactly as they see the
+ * surface it is painted on. The renderer this replaces could only lerp diffuse colour inside a
+ * forward shader.
+ *
+ * **Decals reach opaque surfaces only, by construction.** The G-buffer is all they touch and
+ * transparency composites later, so a decal will never appear on water.
+ *
+ * The records are rebuilt every frame. That sounds wasteful and is the cheaper arrangement: the
+ * froxel binning depends on the camera and so has to run every frame regardless, and rebuilding the
+ * records alongside it means nothing has to watch a decal's colour for changes — which matters,
+ * because the signal that would be watched does not fire for alpha-only edits.
+ */
+export class DecalSystem extends System<any> {
+    /**
+     * @param {GraphicsEngine} graphics
+     * @param {AssetManager} assets
+     */
+    constructor(graphics: GraphicsEngine, assets: AssetManager);
+    dependencies: (typeof Transform | typeof Decal)[];
+    /**
+     * What the pass draws. Read-only — the decals follow the entities.
+     *
+     * @returns {Array}
+     */
+    get decals(): any[];
+    /**
+     * @returns {number} decals packed for the GPU by the last update
+     */
+    get record_count(): number;
+    /**
+     * What was packed, for a gate that wants to see it. Read-only.
+     *
+     * @returns {Float32Array}
+     */
+    get records(): Float32Array;
+    startup(entityManager: any): Promise<void>;
+    shutdown(entityManager: any): Promise<void>;
+    /**
+     * @param {Decal} decal
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    link(decal: Decal, transform: Transform, entity: number): void;
+    /**
+     * @param {Decal} decal
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    unlink(decal: Decal, transform: Transform, entity: number): void;
+    update(timeDelta: any): void;
+    /**
+     * @param {FrameContext} frame
+     */
+    record(frame: FrameContext): void;
+    #private;
+}
+/**
+ * **After the terrain**, because the decal composite has to see the textured ground rather than
+ * precede it. That requirement used to be met by putting a registration call above an `await` and
+ * writing a comment about it; here it is the declaration below.
+ */
+export class DecalExtension extends RenderExtension {
+    /**
+     * @param {DecalSystem} system
+     */
+    constructor(system: DecalSystem);
+    after: (typeof TerrainExtension)[];
+    record(frame: any): void;
+    #private;
+}
+import { System } from "../ecs/System.js";
+import { Transform } from "../ecs/transform/Transform.js";
+import { Decal } from "../graphics/ecs/decal/v2/Decal.js";
+import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
+import { TerrainExtension } from "./TerrainSystem.js";
+//# sourceMappingURL=DecalSystem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DecalSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/DecalSystem.js"],"names":[],"mappings":"AA0BA;;;;;;;;;;;;;;;;GAgBG;AACH;IAwHI;;;OAGG;IACH,4DAeC;IA1ID,kDAAkC;IA8FlC;;;;OAIG;IACH,oBAEC;IAED;;OAEG;IACH,2BAEC;IAED;;;;OAIG;IACH,4BAEC;IAuBD,2CAUC;IAED,4CAYC;IAED;;;;OAIG;IACH,YAJW,KAAK,aACL,SAAS,UACT,MAAM,QAmBhB;IAED;;;;OAIG;IACH,cAJW,KAAK,aACL,SAAS,UACT,MAAM,QAkBhB;IAiFD,6BAiDC;IAED;;OAEG;IACH,kCAkBC;;CACJ;AAED;;;;GAIG;AACH;IAYI;;OAEG;IACH,oBAFW,WAAW,EAMrB;IAdD,mCAA2B;IAgB3B,yBAEC;;CACJ;uBA/asB,kBAAkB;0BACf,+BAA+B;sBACnC,mCAAmC;gCALzB,mDAAmD;iCADlD,oBAAoB"}