@woosh/meep-engine 3.11.2 → 3.12.0

package/src/engine/graphics3/ShadedGeometrySystem.js

@@ -0,0 +1,169 @@
+import { assert } from "../../core/assert.js";
+import { SignalBinding } from "../../core/events/signal/SignalBinding.js";
+import { Mesh } from "../../shade/renderer/scene/Mesh.js";
+import Name from "../ecs/name/Name.js";
+import { System } from "../ecs/System.js";
+import { Transform } from "../ecs/transform/Transform.js";
+import { t64_copy_from_transform } from "../ecs/transform/t64_copy_from_transform.js";
+import { ShadedGeometry } from "../graphics/ecs/mesh-v2/ShadedGeometry.js";
+
+/**
+ * Puts one primitive into Shade's scene, and keeps it where the entity says.
+ *
+ * **The component and the row are the same shape, which is the whole reason this system is short.**
+ * `ShadedGeometry` is a geometry, a material and a flat transform — *"not a hierarchical data
+ * structure"*, in its own docblock — and Shade's `Mesh` is a `Node3D` carrying a `MeshletGeometry`
+ * and a `ShadeMaterial`. §4.3 asks for exactly that mapping, 1:1, and there is nothing else to do.
+ *
+ * **What it is not is a model.** A model file is many primitives arranged in a hierarchy, and in an
+ * ECS a hierarchy is entities — one per node, parented through `EntityNode`, each carrying its own
+ * `ShadedGeometry` where it draws (D47). `SGMesh` is the layer that expands a loaded file into
+ * those entities; this system never sees the file, only the primitives that came out of it, and
+ * cannot tell them from primitives some tool built by hand.
+ *
+ * **The payload is the renderer's own.** Under three the same component holds a `BufferGeometry`
+ * and a three `Material`, and `ShadedGeometrySystem` reads those; here it holds Shade's pair. One
+ * renderer runs at a time and each system reads what its own renderer draws — the same bargain the
+ * v1 component made with `Mesh.mesh`, and not a neutral geometry format, which would be a redesign
+ * rather than a transition.
+ */
+export class ShadedGeometrySystem extends System {
+    /**
+     * @type {GraphicsEngine}
+     */
+    #graphics;
+
+    /**
+     * @type {Scene}
+     */
+    #scene;
+
+    /**
+     * What each entity put in the scene, and what is listening on its behalf.
+     *
+     * @type {Map<number, {node: Mesh, bindings: SignalBinding[]}>}
+     */
+    #entries = new Map();
+
+    /**
+     * @param {GraphicsEngine} graphics
+     * @param {Scene} scene
+     */
+    constructor(graphics, scene) {
+        super();
+
+        assert.defined(graphics, 'graphics');
+        assert.defined(scene, 'scene');
+
+        this.#graphics = graphics;
+        this.#scene = scene;
+
+        this.dependencies = [ShadedGeometry, Transform];
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+    }
+
+    async shutdown(entityManager) {
+        for (const entity of Array.from(this.#entries.keys())) {
+            this.#drop(entity);
+        }
+    }
+
+    /**
+     * @param {ShadedGeometry} geometry
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    link(geometry, transform, entity) {
+        const node = new Mesh();
+
+        node.geometry = geometry.geometry;
+        node.material = geometry.material;
+
+        /*
+         The row takes the entity's name when it has one. Nothing draws differently for it — what it
+         buys is that a walk over what is in the scene still answers with the names the model file
+         gave its nodes, which is what `MeshSystem.traverse_meshes` has always yielded and what
+         makes a scene readable in a debugger.
+        */
+        const name = this.entityManager.dataset.getComponent(entity, Name);
+
+        if (name !== undefined && name !== null) {
+            node.name = name.getValue();
+        }
+
+        const bindings = [];
+
+        // placed when the transform moves rather than on a poll, which is the bargain `MeshSystem`
+        // makes for the same reason: an entity that has not moved costs nothing downstream either
+        const place = () => this.#place(entity, transform);
+
+        for (const component of [transform.position, transform.rotation, transform.scale]) {
+            const binding = new SignalBinding(component.onChanged, place);
+
+            binding.link();
+
+            bindings.push(binding);
+        }
+
+        this.#entries.set(entity, { node, bindings });
+
+        // the component carries its own row, so anything holding the component can ask where the
+        // primitive ended up without going through this system
+        geometry.node = node;
+
+        this.#scene.add(node);
+
+        this.#place(entity, transform);
+    }
+
+    /**
+     * @param {ShadedGeometry} geometry
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    unlink(geometry, transform, entity) {
+        geometry.node = null;
+
+        this.#drop(entity);
+    }
+
+    /**
+     * @param {number} entity
+     * @param {Transform} transform
+     */
+    #place(entity, transform) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        t64_copy_from_transform(entry.node.transform_local, transform);
+
+        // recomputes `transform_global` and bumps the version the scene database reads to decide
+        // what to upload
+        entry.node.updateMatrices();
+    }
+
+    /**
+     * @param {number} entity
+     */
+    #drop(entity) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        for (const binding of entry.bindings) {
+            binding.unlink();
+        }
+
+        this.#scene.remove(entry.node);
+
+        this.#entries.delete(entity);
+    }
+}

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

@@ -1,47 +1,10 @@
 /**
- * Puts one primitive into Shade's scene, and keeps it where the entity says.
+ * @deprecated Renamed to {@link ShadedGeometrySystem}. 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 component and the row are the same shape, which is the whole reason this system is short.**
- * `ShadedGeometry` is a geometry, a material and a flat transform — *"not a hierarchical data
- * structure"*, in its own docblock — and Shade's `Mesh` is a `Node3D` carrying a `MeshletGeometry`
- * and a `ShadeMaterial`. §4.3 asks for exactly that mapping, 1:1, and there is nothing else to do.
- *
- * **What it is not is a model.** A model file is many primitives arranged in a hierarchy, and in an
- * ECS a hierarchy is entities — one per node, parented through `EntityNode`, each carrying its own
- * `ShadedGeometry` where it draws (D47). `SGMesh` is the layer that expands a loaded file into
- * those entities; this system never sees the file, only the primitives that came out of it, and
- * cannot tell them from primitives some tool built by hand.
- *
- * **The payload is the renderer's own.** Under three the same component holds a `BufferGeometry`
- * and a three `Material`, and `ShadedGeometrySystem` reads those; here it holds Shade's pair. One
- * renderer runs at a time and each system reads what its own renderer draws — the same bargain the
- * v1 component made with `Mesh.mesh`, and not a neutral geometry format, which would be a redesign
- * rather than a transition.
+ * 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 ShadedGeometrySystem3 extends System<any> {
-    /**
-     * @param {GraphicsEngine3} graphics
-     * @param {Scene} scene
-     */
-    constructor(graphics: GraphicsEngine3, scene: Scene);
-    dependencies: (typeof Transform | typeof ShadedGeometry)[];
-    startup(entityManager: any): Promise<void>;
-    shutdown(entityManager: any): Promise<void>;
-    /**
-     * @param {ShadedGeometry} geometry
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    link(geometry: ShadedGeometry, transform: Transform, entity: number): void;
-    /**
-     * @param {ShadedGeometry} geometry
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    unlink(geometry: ShadedGeometry, transform: Transform, entity: number): void;
-    #private;
-}
-import { System } from "../ecs/System.js";
-import { Transform } from "../ecs/transform/Transform.js";
-import { ShadedGeometry } from "../graphics/ecs/mesh-v2/ShadedGeometry.js";
+export const ShadedGeometrySystem3: typeof ShadedGeometrySystem;
+import { ShadedGeometrySystem } from "./ShadedGeometrySystem.js";
 //# sourceMappingURL=ShadedGeometrySystem3.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ShadedGeometrySystem3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/ShadedGeometrySystem3.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAkBI;;;OAGG;IACH,qDAUC;IADG,2DAA+C;IAGnD,2CAEC;IAED,4CAIC;IAED;;;;OAIG;IACH,eAJW,cAAc,aACd,SAAS,UACT,MAAM,QA2ChB;IAED;;;;OAIG;IACH,iBAJW,cAAc,aACd,SAAS,UACT,MAAM,QAMhB;;CAsCJ;uBApKsB,kBAAkB;0BACf,+BAA+B;+BAE1B,2CAA2C"}
+{"version":3,"file":"ShadedGeometrySystem3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/ShadedGeometrySystem3.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,gEAA0D;qCATrB,2BAA2B"}

package/src/engine/graphics3/ShadedGeometrySystem3.js

@@ -1,169 +1,10 @@
-import { assert } from "../../core/assert.js";
-import { SignalBinding } from "../../core/events/signal/SignalBinding.js";
-import { Mesh } from "../../shade/renderer/scene/Mesh.js";
-import Name from "../ecs/name/Name.js";
-import { System } from "../ecs/System.js";
-import { Transform } from "../ecs/transform/Transform.js";
-import { t64_copy_from_transform } from "../ecs/transform/t64_copy_from_transform.js";
-import { ShadedGeometry } from "../graphics/ecs/mesh-v2/ShadedGeometry.js";
+import { ShadedGeometrySystem } from "./ShadedGeometrySystem.js";
 
 /**
- * Puts one primitive into Shade's scene, and keeps it where the entity says.
+ * @deprecated Renamed to {@link ShadedGeometrySystem}. 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 component and the row are the same shape, which is the whole reason this system is short.**
- * `ShadedGeometry` is a geometry, a material and a flat transform — *"not a hierarchical data
- * structure"*, in its own docblock — and Shade's `Mesh` is a `Node3D` carrying a `MeshletGeometry`
- * and a `ShadeMaterial`. §4.3 asks for exactly that mapping, 1:1, and there is nothing else to do.
- *
- * **What it is not is a model.** A model file is many primitives arranged in a hierarchy, and in an
- * ECS a hierarchy is entities — one per node, parented through `EntityNode`, each carrying its own
- * `ShadedGeometry` where it draws (D47). `SGMesh` is the layer that expands a loaded file into
- * those entities; this system never sees the file, only the primitives that came out of it, and
- * cannot tell them from primitives some tool built by hand.
- *
- * **The payload is the renderer's own.** Under three the same component holds a `BufferGeometry`
- * and a three `Material`, and `ShadedGeometrySystem` reads those; here it holds Shade's pair. One
- * renderer runs at a time and each system reads what its own renderer draws — the same bargain the
- * v1 component made with `Mesh.mesh`, and not a neutral geometry format, which would be a redesign
- * rather than a transition.
+ * 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 ShadedGeometrySystem3 extends System {
-    /**
-     * @type {GraphicsEngine3}
-     */
-    #graphics;
-
-    /**
-     * @type {Scene}
-     */
-    #scene;
-
-    /**
-     * What each entity put in the scene, and what is listening on its behalf.
-     *
-     * @type {Map<number, {node: Mesh, bindings: SignalBinding[]}>}
-     */
-    #entries = new Map();
-
-    /**
-     * @param {GraphicsEngine3} graphics
-     * @param {Scene} scene
-     */
-    constructor(graphics, scene) {
-        super();
-
-        assert.defined(graphics, 'graphics');
-        assert.defined(scene, 'scene');
-
-        this.#graphics = graphics;
-        this.#scene = scene;
-
-        this.dependencies = [ShadedGeometry, Transform];
-    }
-
-    async startup(entityManager) {
-        this.entityManager = entityManager;
-    }
-
-    async shutdown(entityManager) {
-        for (const entity of Array.from(this.#entries.keys())) {
-            this.#drop(entity);
-        }
-    }
-
-    /**
-     * @param {ShadedGeometry} geometry
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    link(geometry, transform, entity) {
-        const node = new Mesh();
-
-        node.geometry = geometry.geometry;
-        node.material = geometry.material;
-
-        /*
-         The row takes the entity's name when it has one. Nothing draws differently for it — what it
-         buys is that a walk over what is in the scene still answers with the names the model file
-         gave its nodes, which is what `MeshSystem3.traverse_meshes` has always yielded and what
-         makes a scene readable in a debugger.
-        */
-        const name = this.entityManager.dataset.getComponent(entity, Name);
-
-        if (name !== undefined && name !== null) {
-            node.name = name.getValue();
-        }
-
-        const bindings = [];
-
-        // placed when the transform moves rather than on a poll, which is the bargain `MeshSystem3`
-        // makes for the same reason: an entity that has not moved costs nothing downstream either
-        const place = () => this.#place(entity, transform);
-
-        for (const component of [transform.position, transform.rotation, transform.scale]) {
-            const binding = new SignalBinding(component.onChanged, place);
-
-            binding.link();
-
-            bindings.push(binding);
-        }
-
-        this.#entries.set(entity, { node, bindings });
-
-        // the component carries its own row, so anything holding the component can ask where the
-        // primitive ended up without going through this system
-        geometry.node = node;
-
-        this.#scene.add(node);
-
-        this.#place(entity, transform);
-    }
-
-    /**
-     * @param {ShadedGeometry} geometry
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    unlink(geometry, transform, entity) {
-        geometry.node = null;
-
-        this.#drop(entity);
-    }
-
-    /**
-     * @param {number} entity
-     * @param {Transform} transform
-     */
-    #place(entity, transform) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined) {
-            return;
-        }
-
-        t64_copy_from_transform(entry.node.transform_local, transform);
-
-        // recomputes `transform_global` and bumps the version the scene database reads to decide
-        // what to upload
-        entry.node.updateMatrices();
-    }
-
-    /**
-     * @param {number} entity
-     */
-    #drop(entity) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined) {
-            return;
-        }
-
-        for (const binding of entry.bindings) {
-            binding.unlink();
-        }
-
-        this.#scene.remove(entry.node);
-
-        this.#entries.delete(entity);
-    }
-}
+export const ShadedGeometrySystem3 = ShadedGeometrySystem;

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

@@ -0,0 +1,80 @@
+/**
+ * Draws terrain under Shade: each built tile becomes one meshlet-encoded mesh in the scene, and a
+ * pass after the opaque geometry textures the lot.
+ *
+ * **The tile is the unit, not the terrain.** Tiles are built on demand as the camera sees them and
+ * destroyed as it leaves, which is the streaming the tile manager already does; this system follows
+ * that with scene membership rather than deciding anything about it.
+ *
+ * **Tile vertices are already in terrain space** — the height-field builder positions each tile
+ * within the whole grid rather than at its own origin — so every tile mesh carries the terrain
+ * entity's transform and nothing else. That is also why the tile's own raycast inverts the same
+ * matrix.
+ *
+ * **Texturing is a full-screen pass, not a material** (U3b, D40): the tiles draw with one flat
+ * material, and at {@link FramePhase.AfterGBuffer} the splat mix and grid overlay are painted over
+ * every pixel the visibility buffer attributes to a tile — the architecture decals built (D23),
+ * keyed on mesh rows rather than froxels. Registered before `DecalSystem` in the profile, which
+ * is what puts scorch marks on top of the textured ground rather than under it.
+ *
+ * **It does not call `Terrain.link`.** That method binds a three `ShaderMaterial` through
+ * `graphics.getMaterialManager()`, which `GraphicsEngine` does not have and will not; the parts of
+ * linking that are not about three — starting the tile build service — are done here directly.
+ */
+export class TerrainSystem extends System<any> {
+    /**
+     * @param {GraphicsEngine} graphics
+     * @param {Scene} scene
+     * @param {AssetManager} assetManager
+     */
+    constructor(graphics: GraphicsEngine, scene: Scene, assetManager: AssetManager);
+    dependencies: (typeof Terrain)[];
+    startup(entityManager: any): Promise<void>;
+    shutdown(entityManager: any): Promise<void>;
+    /**
+     * @param {Terrain} terrain
+     * @param {number} entity
+     */
+    link(terrain: Terrain, entity: number): void;
+    /**
+     * @param {Terrain} terrain
+     * @param {number} entity
+     */
+    unlink(terrain: Terrain, entity: number): void;
+    update(timeDelta: any): void;
+    /**
+     * Everything the splat pass draws one terrain from, assembled against the scene that will be
+     * asked for the rows. What the pass consumes and what a gate inspects are deliberately the
+     * same object — the same reason `DecalSystem` exposes its packed records.
+     *
+     * @param {number} entity
+     * @param {GPUSceneContext} scene
+     * @returns {object|null} `null` when this terrain has nothing on screen to texture — no tiles
+     * built, or none of them in the scene database yet
+     */
+    splat_frame(entity: number, scene: GPUSceneContext): object | null;
+    /**
+     * @param {FrameContext} frame
+     */
+    record(frame: FrameContext): void;
+    #private;
+}
+/**
+ * The splat and the grid overlay are a full-screen pass writing a replacement albedo, so this is
+ * {@link FramePhase.AfterGBuffer} — the one phase where the G-buffer may be published into.
+ *
+ * Everything that paints on top of the ground declares itself after this rather than being
+ * registered after it; {@link DecalExtension} is the one that does.
+ */
+export class TerrainExtension extends RenderExtension {
+    /**
+     * @param {TerrainSystem} system
+     */
+    constructor(system: TerrainSystem);
+    record(frame: any): void;
+    #private;
+}
+import { System } from "../ecs/System.js";
+import Terrain from "../ecs/terrain/ecs/Terrain.js";
+import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
+//# sourceMappingURL=TerrainSystem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TerrainSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/TerrainSystem.js"],"names":[],"mappings":"AA2CA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAiCI;;;;OAIG;IACH,gFAUC;IA/CD,iCAAyB;IAiDzB,2CAQC;IAED,4CAUC;IAED;;;OAGG;IACH,cAHW,OAAO,UACP,MAAM,QA2DhB;IAED;;;OAGG;IACH,gBAHW,OAAO,UACP,MAAM,QAMhB;IAED,6BA0BC;IAoLD;;;;;;;;;OASG;IACH,oBALW,MAAM,2BAEJ,MAAM,GAAC,IAAI,CA2FvB;IAED;;OAEG;IACH,kCAaC;;CACJ;AAED;;;;;;GAMG;AACH;IAUI;;OAEG;IACH,oBAFW,aAAa,EAMvB;IAED,yBAEC;;CACJ;uBA5iBsB,kBAAkB;oBACrB,+BAA+B;gCAUnB,mDAAmD"}