@woosh/meep-engine 3.23.0 → 3.24.0

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

@@ -1 +1 @@
-{"version":3,"file":"PathDisplaySystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/PathDisplaySystem.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IA8CI;;OAEG;IACH,sCAMC;IAtDD,mDAAmC;IAoCnC;;;;OAIG;IACH,8BAEC;IAaD,2CAIC;IAED,4CAYC;IAED;;;;OAIG;IACH,cAJW,WAAW,QACX,IAAI,UACJ,MAAM,QAehB;IAED;;;;OAIG;IACH,gBAJW,WAAW,QACX,IAAI,UACJ,MAAM,QAkBhB;IAED,6BAgBC;IAwFD;;OAEG;IACH,kCAeC;;CACJ;AAED;;;GAGG;AACH;IAUI;;OAEG;IACH,oBAFW,iBAAiB,EAM3B;IAED,yBAEC;;CACJ;uBA3SsB,kBAAkB;iBAIxB,sCAAsC;4BAH3B,qCAAqC;iCAFhC,gDAAgD;gCAJjD,mDAAmD"}
+{"version":3,"file":"PathDisplaySystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/PathDisplaySystem.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IA8CI;;OAEG;IACH,sCAMC;IAtDD,mDAAmC;IAoCnC;;;;OAIG;IACH,8BAEC;IAaD,2CAIC;IAED,4CAYC;IAED;;;;OAIG;IACH,cAJW,WAAW,QACX,IAAI,UACJ,MAAM,QAehB;IAED;;;;OAIG;IACH,gBAJW,WAAW,QACX,IAAI,UACJ,MAAM,QAkBhB;IAED,6BAgBC;IAsFD;;OAEG;IACH,kCAeC;;CACJ;AAED;;;GAGG;AACH;IAUI;;OAEG;IACH,oBAFW,iBAAiB,EAM3B;IAED,yBAEC;;CACJ;uBAzSsB,kBAAkB;iBAIxB,sCAAsC;4BAH3B,qCAAqC;iCAFhC,gDAAgD;gCAJjD,mDAAmD"}

package/src/engine/graphics3/PathDisplaySystem.js

@@ -225,12 +225,10 @@ export class PathDisplaySystem extends System {
             return existing;
         }
 
+        // the sweep produces world-space vertices, and what the draw applies is the mesh's own
+        // transform, identity until moved
         const mesh = DynamicMesh.from(new Geometry());
 
-        // the sweep 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();
-
         entry.meshes.push(mesh);
 
         this.#batch.add(mesh);

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

@@ -1,37 +1,31 @@
 /**
- * One ray to be answered by {@link PickingSystem#pick}.
+ * One question for {@link PickingSystem#pick}: what is drawn at this point of the main view.
  *
- * A type rather than a pair of loose vectors because queries travel in batches, and a batch of
- * `[origin, direction, origin, direction, …]` is a shape that goes wrong silently.
+ * A point of the view rather than a ray, because the answer comes off the visibility buffer — the
+ * entity the rasterizer drew there, at the depth it drew it — and a ray that does not start at the
+ * camera has no pixel. The point is a fraction of the view, `(0, 0)` at the top left and `(1, 1)`
+ * at the bottom right, so that a caller with a pointer in viewport pixels and a frame drawn at
+ * some other resolution need not know the other resolution; the frame that answers turns it into
+ * the texel it drew.
  */
 export class PickingQuery {
     /**
-     * @param {Vector3} origin
-     * @param {Vector3} direction unit length
-     * @param {number} [max_distance]
+     * @param {number} u across, 0 at the left
+     * @param {number} v down, 0 at the top
      * @returns {PickingQuery}
      */
-    static from(origin: Vector3, direction: Vector3, max_distance?: number): PickingQuery;
+    static from_viewport(u: number, v: number): PickingQuery;
     /**
-     * Where the ray starts, in world space.
+     * Across the view, 0 at the left edge.
      *
-     * @type {Vector3}
-     */
-    origin: Vector3;
-    /**
-     * Which way it goes. Must be unit length — distances in the result are measured along it, so a
-     * direction of any other length rescales every one of them.
-     *
-     * @type {Vector3}
+     * @type {number}
      */
-    direction: Vector3;
+    u: number;
     /**
-     * How far along the ray to look. Everything beyond is not a hit, which is how a caller asks
-     * "within reach" rather than "anywhere in the world".
+     * Down the view, 0 at the top edge.
      *
      * @type {number}
      */
-    max_distance: number;
+    v: number;
 }
-import Vector3 from "../../core/geom/Vector3.js";
 //# sourceMappingURL=PickingQuery.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"PickingQuery.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/PickingQuery.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH;IAwBI;;;;;OAKG;IACH,oBALW,OAAO,aACP,OAAO,iBACP,MAAM,GACJ,YAAY,CAUxB;IArCD;;;;OAIG;IACH,QAFU,OAAO,CAEM;IAEvB;;;;;OAKG;IACH,WAFU,OAAO,CAES;IAE1B;;;;;OAKG;IACH,cAFU,MAAM,CAEQ;CAiB3B;oBA/CmB,4BAA4B"}
+{"version":3,"file":"PickingQuery.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/PickingQuery.js"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH;IAeI;;;;OAIG;IACH,wBAJW,MAAM,KACN,MAAM,GACJ,YAAY,CAYxB;IA7BD;;;;OAIG;IACH,GAFU,MAAM,CAEV;IAEN;;;;OAIG;IACH,GAFU,MAAM,CAEV;CAkBT"}

package/src/engine/graphics3/PickingQuery.js

@@ -1,47 +1,43 @@
-import Vector3 from "../../core/geom/Vector3.js";
+import { assert } from "../../core/assert.js";
 
 /**
- * One ray to be answered by {@link PickingSystem#pick}.
+ * One question for {@link PickingSystem#pick}: what is drawn at this point of the main view.
  *
- * A type rather than a pair of loose vectors because queries travel in batches, and a batch of
- * `[origin, direction, origin, direction, …]` is a shape that goes wrong silently.
+ * A point of the view rather than a ray, because the answer comes off the visibility buffer — the
+ * entity the rasterizer drew there, at the depth it drew it — and a ray that does not start at the
+ * camera has no pixel. The point is a fraction of the view, `(0, 0)` at the top left and `(1, 1)`
+ * at the bottom right, so that a caller with a pointer in viewport pixels and a frame drawn at
+ * some other resolution need not know the other resolution; the frame that answers turns it into
+ * the texel it drew.
  */
 export class PickingQuery {
     /**
-     * Where the ray starts, in world space.
+     * Across the view, 0 at the left edge.
      *
-     * @type {Vector3}
-     */
-    origin = new Vector3();
-
-    /**
-     * Which way it goes. Must be unit length — distances in the result are measured along it, so a
-     * direction of any other length rescales every one of them.
-     *
-     * @type {Vector3}
+     * @type {number}
      */
-    direction = new Vector3();
+    u = 0;
 
     /**
-     * How far along the ray to look. Everything beyond is not a hit, which is how a caller asks
-     * "within reach" rather than "anywhere in the world".
+     * Down the view, 0 at the top edge.
      *
      * @type {number}
      */
-    max_distance = Infinity;
+    v = 0;
 
     /**
-     * @param {Vector3} origin
-     * @param {Vector3} direction unit length
-     * @param {number} [max_distance]
+     * @param {number} u across, 0 at the left
+     * @param {number} v down, 0 at the top
      * @returns {PickingQuery}
      */
-    static from(origin, direction, max_distance = Infinity) {
+    static from_viewport(u, v) {
+        assert.isNumber(u, 'u');
+        assert.isNumber(v, 'v');
+
         const r = new PickingQuery();
 
-        r.origin.copy(origin);
-        r.direction.copy(direction);
-        r.max_distance = max_distance;
+        r.u = u;
+        r.v = v;
 
         return r;
     }

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

@@ -1,67 +1,96 @@
 /**
- * Answers "what is under this ray" for entities that asked to be pickable.
+ * Answers "what is under this pixel" for entities that asked to be pickable.
  *
- * **Asynchronous and batched from the first line, on purpose (I-9).** The backend here is a CPU
- * bounding-volume hierarchy and could answer synchronously; the API does not let it, because the
- * backend this is meant to grow into reads entity ids back off the GPU's visibility buffer, and that
- * answer is inherently a frame late and arrives for a whole batch at once. A synchronous entry point
- * would have to be broken to get there, and every caller broken with it.
+ * **Off the visibility buffer.** The rasterizer writes every pixel's `meshes` row — an entity's
+ * row, one on — and its depth; a pick copies those two texels out of the frame that drew them and
+ * resolves the row to the entity that drew it, then up its parents to the one that opted in. What
+ * was drawn is what is picked: at triangle precision, under skinning, with nothing kept on the CPU
+ * for it — no bounds, no tree, no per-frame refresh.
  *
- * **Bounding boxes, not triangles.** A hit means the ray entered the entity's world bounding box.
- * That is the precision this can offer for free — Shade maintains those boxes as part of drawing —
- * and going finer means keeping CPU-side triangles for every pickable entity, which is the
- * duplication {@link Pickable} exists to keep small. Terrain picking, which is where the game's
- * precision actually matters, does not come through here at all: it is an exact raycast against the
- * terrain's own representation and is untouched by any of this.
+ * **Asynchronous and batched, of necessity.** The texels are copied by the frame after the query
+ * was asked and read back when the device has finished it, so an answer is a frame or two late and
+ * arrives for the whole batch at once. A result is a promise for that reason, and nothing this
+ * tick can come to depend on it.
  *
- * The index is refreshed **on query rather than per frame**. Nothing pays for picking on a frame where
- * nobody picks, and there is no window in which the index disagrees with the scene, so no class of
- * bug where a pick lands on where something used to be.
+ * Terrain picking, which is where the game's precision matters, does not come through here at all:
+ * it is an exact raycast against the terrain's own representation and is untouched by any of this.
  */
 export class PickingSystem extends System<any> {
     /**
-     * @param {MeshSystem} meshes what an entity looks like, which is where its bounds come from
+     * @param {GraphicsEngine} graphics whose frames draw the view the picks read
      */
-    constructor(meshes: MeshSystem);
-    dependencies: (typeof Transform64 | typeof Pickable)[];
+    constructor(graphics: GraphicsEngine);
+    dependencies: (typeof Pickable)[];
     startup(entityManager: any): Promise<void>;
     shutdown(entityManager: any): Promise<void>;
     /**
      * @param {Pickable} pickable
-     * @param {Transform64} transform
      * @param {number} entity
      */
-    link(pickable: Pickable, transform: Transform64, entity: number): void;
+    link(pickable: Pickable, entity: number): void;
     /**
      * @param {Pickable} pickable
-     * @param {Transform64} transform
      * @param {number} entity
      */
-    unlink(pickable: Pickable, transform: Transform64, entity: number): void;
+    unlink(pickable: Pickable, entity: number): void;
     /**
-     * How many entities the index currently stands for.
+     * How many entities have opted in.
      *
-     * The index is built on query, so this is zero until the first {@link pick} — and stays behind by
-     * however many pickable entities are still waiting on their models.
+     * @returns {number}
+     */
+    get pickable_count(): number;
+    /**
+     * Batches asked and not yet answered by a frame.
      *
      * @returns {number}
      */
-    get indexed_count(): number;
+    get waiting_count(): number;
     /**
-     * What each of these rays hits first.
+     * What is drawn under each of these pixels.
+     *
+     * One result per query, in the order the queries were given. A pixel over nothing pickable
+     * still gets a result — `entity` is {@link PickingResult.NOTHING} — so the two arrays line up
+     * by position and a caller never has to search for the answer to its own question.
      *
-     * One result per query, in the order the queries were given. A ray that hits nothing still gets a
-     * result — `entity` is {@link PickingResult.NOTHING} — so the two arrays line up by position and a
-     * caller never has to search for the answer to its own question.
+     * Answered by the next frame that draws the view, when the device has finished it.
      *
      * @param {PickingQuery[]} queries
      * @returns {Promise<PickingResult[]>}
      */
     pick(queries: PickingQuery[]): Promise<PickingResult[]>;
+    /**
+     * Take everything asked since the last frame, to be answered by this one.
+     *
+     * @returns {{queries: PickingQuery[], resolve: function(PickingResult[]): void, reject: function(Error): void}[]}
+     */
+    take_waiting(): {
+        queries: PickingQuery[];
+        resolve: (arg0: PickingResult[]) => void;
+        reject: (arg0: Error) => void;
+    }[];
+    /**
+     * The entity a drawn mesh row picks: the one that drew it, or the nearest of its ancestors,
+     * that opted in.
+     *
+     * @param {number} row a `meshes` row, as the visibility buffer holds it
+     * @returns {number} the entity, or {@link PickingResult.NOTHING}
+     */
+    resolve_row(row: number): number;
+    #private;
+}
+/**
+ * Copies the queried texels out of the frame that drew them, after the G-buffer is written and
+ * before anything overwrites the visibility buffer, and answers the batch when they land.
+ */
+export class PickingExtension extends RenderExtension {
+    /**
+     * @param {PickingSystem} system
+     */
+    constructor(system: PickingSystem);
     #private;
 }
 import { System } from "../ecs/System.js";
-import { Transform64 } from "../ecs/transform/Transform64.js";
 import { Pickable } from "./Pickable.js";
 import { PickingResult } from "./PickingResult.js";
+import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
 //# sourceMappingURL=PickingSystem.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"PickingSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/PickingSystem.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IA2BI;;OAEG;IACH,gCAQC;IADG,uDAA2C;IAG/C,2CAEC;IAED,4CAMC;IAED;;;;OAIG;IACH,eAJW,QAAQ,aACR,WAAW,UACX,MAAM,QAMhB;IAED;;;;OAIG;IACH,iBAJW,QAAQ,aACR,WAAW,UACX,MAAM,QAIhB;IAED;;;;;;;OAOG;IACH,4BAEC;IAED;;;;;;;;;OASG;IACH,cAHW,cAAc,GACZ,QAAQ,aAAa,EAAE,CAAC,CAcpC;;CAiIJ;uBAzQsB,kBAAkB;4BACb,iCAAiC;yBACpC,eAAe;8BACV,oBAAoB"}
+{"version":3,"file":"PickingSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/PickingSystem.js"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;;GAgBG;AACH;IAyBI;;OAEG;IACH,sCAQC;IADG,kCAA8B;IAGlC,2CAIC;IAED,4CAYC;IAED;;;OAGG;IACH,eAHW,QAAQ,UACR,MAAM,QAIhB;IAED;;;OAGG;IACH,iBAHW,QAAQ,UACR,MAAM,QAIhB;IAED;;;;OAIG;IACH,6BAEC;IAED;;;;OAIG;IACH,4BAEC;IAED;;;;;;;;;;;OAWG;IACH,cAHW,cAAc,GACZ,QAAQ,aAAa,EAAE,CAAC,CAYpC;IAED;;;;OAIG;IACH,gBAFa;QAAC,OAAO,EAAE,cAAc,CAAC;QAAC,OAAO,SAAW,aAAa,EAAE,KAAG,IAAI,CAAC;QAAC,MAAM,SAAW,KAAK,KAAG,IAAI,CAAA;KAAC,EAAE,CAIhH;IAED;;;;;;OAMG;IACH,iBAHW,MAAM,GACJ,MAAM,CAuBlB;;CACJ;AAED;;;GAGG;AACH;IASI;;OAEG;IACH,oBAFW,aAAa,EAMvB;;CA8IJ;uBAhWsB,kBAAkB;yBAChB,eAAe;8BACV,oBAAoB;gCAPlB,mDAAmD"}