@woosh/meep-engine 3.23.0 → 3.25.0

package/src/engine/graphics3/LightSystem.js

@@ -12,11 +12,13 @@ import { TRANSFORM64_EVENT_CHANGE } from "../ecs/transform/TRANSFORM64_EVENT_CHA
 /**
  * Mirrors light entities into Shade's scene.
  *
- * The same shape as {@link MeshSystem} and for the same reason: the ECS says what exists and where,
- * and this keeps the renderer's own objects in step. A Shade light **is** a `Node3D`, so `Scene.add`
- * routes it into the light collection on its own and placement is the same transform copy meshes
- * get — which for a directional light is also what aims it, since the engine's convention is that a
- * light shines along its forward.
+ * The same shape as {@link ShadedGeometrySystem} and for the same reason: the ECS says what exists
+ * and where, and this keeps the renderer's own objects in step. A Shade light is placed at an
+ * entity — `scene.lights.add(light, entity)` — and the GPU reads its pose from the entity's row,
+ * which the scene context holds on the light collection's behalf; the light's own `transform` is
+ * the entity's `Transform64`, the one object, so there is no copy to fall behind. For a directional
+ * light the pose is also what aims it, since the engine's convention is that a light shines along
+ * its forward.
  *
  * **Ambient lights are deliberately not carried over.** Shade lights indirect from the environment
  * by default, and that environment is the ambient term — a separate flat ambient light would be
@@ -34,7 +36,7 @@ export class LightSystem extends System {
     #scene;
 
     /**
-     * @type {Map<number, {light: Light, bindings: SignalBinding[]}>}
+     * @type {Map<number, {light: Light, bindings: SignalBinding[], on_transform_changed: function|null}>}
      */
     #entries = new Map();
 
@@ -57,7 +59,18 @@ export class LightSystem extends System {
     async startup(entityManager) {
         this.entityManager = entityManager;
 
-        this.#graphics.set_scene(this.#scene);
+        // the scene's rows are this dataset's entities; the first system to place one says so
+        const dataset = entityManager.dataset;
+        const scene = this.#scene;
+
+        assert.ok(
+            scene.dataset === null || scene.dataset === undefined || scene.dataset === dataset,
+            'the scene is bound to another dataset'
+        );
+
+        scene.dataset = dataset;
+
+        this.#graphics.set_scene(scene);
     }
 
     async shutdown(entityManager) {
@@ -81,41 +94,42 @@ export class LightSystem extends System {
 
         apply_light_properties(light, component);
 
-        light.transform_local.copy(transform);
-        light.updateMatrices();
+        // The entity's transform is the light's: one object, so the row and the shadow camera are
+        // built from what the entity moved, and there is no copy to fall behind it.
+        light.transform = transform;
+
+        const lights = this.#scene.lights;
 
-        this.#scene.add(light);
+        lights.add(light, entity);
 
-        const entry = { light, bindings: [] };
+        const entry = { light, bindings: [], on_transform_changed: null };
 
         this.#entries.set(entity, entry);
 
         /*
          Adding and removing a light invalidates the collection on its own, but **changing one in
          place does not** — the GPU light table is rebuilt only when the collection's version moves,
-         so a light that is recoloured, re-aimed or dimmed keeps rendering with the values it was
-         uploaded with. `needsUpdate` is what says otherwise, and both paths below go through it.
+         and so is the row the GPU reads the pose from, so a light that is recoloured, re-aimed or
+         dimmed keeps rendering with the values it was uploaded with. `needsUpdate` is what says
+         otherwise, and both paths below go through it.
 
          Worth knowing because it is invisible from the CPU side: the light object holds the new
          value, everything reads back correctly, and only the picture is stale.
          */
-        const place = () => {
-            light.transform_local.copy(transform);
-            light.updateMatrices();
-
-            this.#scene.lights.needsUpdate = true;
+        const moved = () => {
+            lights.needsUpdate = true;
         };
 
         const refresh = () => {
             apply_light_properties(light, component);
 
-            this.#scene.lights.needsUpdate = true;
+            lights.needsUpdate = true;
         };
 
         // One dataset listener replaces the three sub-object signals a Transform used to carry.
         // Coarser - it wakes on any change to the transform rather than on a named channel - and
-        // that is the trade: the placement reads the whole transform anyway.
-        entry.on_transform_changed = place;
+        // that is the trade: the row is rewritten whole anyway.
+        entry.on_transform_changed = moved;
 
         this.entityManager.dataset.addEntityEventListener(
             entity, TRANSFORM64_EVENT_CHANGE, entry.on_transform_changed
@@ -173,7 +187,7 @@ export class LightSystem extends System {
             entry.on_transform_changed = null;
         }
 
-        this.#scene.remove(entry.light);
+        this.#scene.lights.remove(entry.light);
 
         this.#entries.delete(entity);
     }

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

@@ -1,22 +1,23 @@
 /**
- * Puts entities into Shade's scene and keeps them where the ECS says they are.
+ * Puts models into the scene as entities, and keeps their rows where the entities say.
  *
- * **It owns the scene and tells the facade to draw it**, rather than the facade handing a graph out
- * for anyone to write into — that coupling is what §2.1 retires along with `GraphicsEngine.scene`.
- *
- * Placement is a `Transform` copied into `Node3D.transform_local`, through
- * {@link t64_copy_from_transform} because the node's transform is a `Transform64` since S2 and the
- * two types stay deliberately distinct. `transform_global` is **derived** — `updateMatrices`
- * recomputes it from the local transform and the parent chain — so writing it directly would be
- * undone by the next refresh, and the entity is placed through the local one.
+ * **A model is a prefab, and a placement is entities.** A loaded bundle is compiled once per url
+ * ({@link prefab_compile}) and spawned once per entity that wears it
+ * ({@link prefab_instantiate}): every node of the file becomes an entity attached to its parent's,
+ * named, drawing where it draws, with the placing entity as the root. What used to be a private
+ * copy of a node tree per placement is the dataset's own hierarchy, addressable by every system —
+ * IK finds a foot by name, cloth seeds from joints, gameplay asks where a socket is — and the
+ * renderer's tables are indexed by those entities, at `entity + 1`.
  *
- * What makes this affordable is S1: the scene database takes row-level updates, so moving one
- * entity writes one row. Nothing here rebuilds anything.
+ * **It owns the scene and tells the facade to draw it**, rather than the facade handing a graph out
+ * for anyone to write into.
  *
- * **It also hands each instance to the GPU's animation manager** ({@link update}), because it is
- * what builds instances and therefore the only thing that knows when one exists. Driving those
- * clips is not its business — that is the animation systems' — but a clip nothing has registered
- * cannot be driven by anyone.
+ * **Rows need a device, and registration does too.** A model loads whenever it loads, and there
+ * may be no renderer yet; {@link update} attaches every instance's entities to the scene's GPU
+ * context when one arrives, registers its skins with the animation manager, and does both again
+ * after a renderer restart. Driving the clips is not this system's business — that is the
+ * animation systems' — but a clip nothing has registered cannot be driven by anyone, which is why
+ * the instance is handed out ({@link instance_of}) rather than kept.
  */
 export class MeshSystem extends System<any> {
     /**
@@ -31,34 +32,20 @@ export class MeshSystem extends System<any> {
      */
     get scene(): Scene;
     /**
-     * Visit every node of an entity's model that carries geometry.
-     *
-     * The nodes are what the scene database keys on, so anything that has to say something about a
-     * particular entity's meshes — which rows they occupy, which of them the visibility buffer will
-     * name — starts here. A grouping node is skipped, because it has no geometry and therefore no
-     * row of its own.
-     *
-     * @param {number} entity
-     * @param {function(SGMesh): void} visitor
-     * @returns {boolean} `false` when the entity has nothing in the scene — never seen, or still
-     * loading, and neither is an error
-     */
-    traverse_meshes(entity: number, visitor: (arg0: SGMesh) => void): boolean;
-    /**
-     * The private copy of the model an entity is showing — its clips among other things, which is
-     * where their names and their durations come from.
+     * The model an entity is showing, as entities: its skins and clips addressed to them, and its
+     * nodes by name.
      *
      * Handed out rather than copied because an animation driver has to know *which* instance it is
      * bound to: a model swap builds a new one, and a driver still holding the old one would be
-     * driving nodes that left the scene. The object's identity is the only signal that says so.
+     * driving entities that have gone. The object's identity is the only signal that says so.
      *
      * @param {number} entity
-     * @returns {SceneBundleInstance|null} `null` for an entity this system has never seen, or one
+     * @returns {PrefabInstance|null} `null` for an entity this system has never seen, or one
      * whose model has not finished loading
      */
-    instance_of(entity: number): SceneBundleInstance | null;
+    instance_of(entity: number): PrefabInstance | null;
     /**
-     * What the GPU's animation manager gave back for that instance — the skin and clip ids, in the
+     * What the GPU's animation manager gave back for that instance — the skin ids, in the
      * instance's own order.
      *
      * Same reasoning as {@link instance_of} and a stronger version of it: these ids belong to one
@@ -71,11 +58,22 @@ export class MeshSystem extends System<any> {
      */
     animation_of(entity: number): InstanceAnimationRegistration | null;
     /**
-     * Where an entity's model is, in world space.
+     * The entities of an entity's model that draw — one per primitive of the file. Each holds the
+     * `meshes` row `entity + 1`, which is what the visibility buffer writes for every pixel it
+     * covers; anything that has to say something about a particular model's meshes starts here.
+     *
+     * @param {number} entity
+     * @returns {Int32Array} empty for an entity with nothing in the scene — never seen, or still
+     * loading, and neither is an error. Not to be kept: a model swap replaces it
+     */
+    mesh_entities_of(entity: number): Int32Array;
+    /**
+     * Where an entity's model is, in world space: the union of its primitives' geometry bounds
+     * under their own entities' world transforms — which the ECS composes, so this answers with no
+     * device and with no frame of latency, from what the simulation knows. The box the renderer
+     * culls by is derived on the GPU from the same and is not consulted.
      *
-     * This is what makes picking possible without a second copy of the geometry: Shade already keeps
-     * a world bounding box per mesh, refreshed as part of the `updateMatrices` that places it, so the
-     * answer is a walk over what the entity has in the scene and nothing is recomputed.
+     * A skinned primitive answers at its rest pose, under the frame its skin deforms in.
      *
      * @param {ArrayLike<number>|number[]|Float32Array} target aabb3, order `x0,y0,z0,x1,y1,z1`
      * @param {number} entity
@@ -99,6 +97,12 @@ export class MeshSystem extends System<any> {
     unlink(model: SGMesh, transform: Transform64, entity: number): void;
     #private;
 }
+export type GPUSceneContext = import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext;
+export type SceneBundle = import("../../shade/renderer/loader/SceneBundle.js").SceneBundle;
+export type Prefab = import("./prefab/Prefab.js").Prefab;
+export type PrefabInstance = import("./prefab/PrefabInstance.js").PrefabInstance;
+export type InstanceAnimationRegistration = import("./register_instance_animation.js").InstanceAnimationRegistration;
+export type GraphicsEngine = import("./GraphicsEngine.js").GraphicsEngine;
 import { System } from "../ecs/System.js";
 import { Transform64 } from "../ecs/transform/Transform64.js";
 import { SGMesh } from "../graphics/ecs/mesh-v2/aggregate/SGMesh.js";

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

@@ -1 +1 @@
-{"version":3,"file":"MeshSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/MeshSystem.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAmFI;;;;OAIG;IACH,6CAHW,KAAK,eACI,MAAM,KAAG,oBAAoB,EAchD;IADG,qDAAyC;IAG7C;;OAEG;IACH,mBAEC;IAED;;;;;;;;;;;;OAYG;IACH,wBALW,MAAM,kBACG,MAAM,KAAG,IAAI,GACpB,OAAO,CAqBnB;IAoCD;;;;;;;;;;;OAWG;IACH,oBAJW,MAAM,GACJ,sBAAoB,IAAI,CAWpC;IAED;;;;;;;;;;;OAWG;IACH,qBAJW,MAAM,GACJ,gCAA8B,IAAI,CAW9C;IAED;;;;;;;;;;;OAWG;IACH,6BALW,UAAU,MAAM,CAAC,GAAC,MAAM,EAAE,GAAC,YAAY,UACvC,MAAM,GACJ,OAAO,CAuCnB;IAED,2CAIC;IAED,4CASC;IA6GD;;;;OAIG;IACH,YAJW,MAAM,aACN,WAAW,UACX,MAAM,QA2BhB;IAED;;;;OAIG;IACH,cAJW,MAAM,aACN,WAAW,UACX,MAAM,QAIhB;;CAoMJ;uBAlpBsB,kBAAkB;4BACb,iCAAiC;uBAGtC,6CAA6C;sBAV9C,qCAAqC"}
+{"version":3,"file":"MeshSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/MeshSystem.js"],"names":[],"mappings":"AA6FA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAqEI;;;;OAIG;IACH,sBAJW,cAAc,SACd,KAAK,eACI,MAAM,KAAG,QAAQ,WAAW,CAAC,EAchD;IADG,qDAAyC;IAG7C;;OAEG;IACH,mBAEC;IAED;;;;;;;;;;;OAWG;IACH,oBAJW,MAAM,GACJ,cAAc,GAAC,IAAI,CAW/B;IAED;;;;;;;;;;;OAWG;IACH,qBAJW,MAAM,GACJ,6BAA6B,GAAC,IAAI,CAW9C;IAED;;;;;;;;OAQG;IACH,yBAJW,MAAM,GACJ,UAAU,CAWtB;IAED;;;;;;;;;;;;OAYG;IACH,6BALW,UAAU,MAAM,CAAC,GAAC,MAAM,EAAE,GAAC,YAAY,UACvC,MAAM,GACJ,OAAO,CAwCnB;IAED,2CAeC;IAED,4CASC;IA0HD;;;;OAIG;IACH,YAJW,MAAM,aACN,WAAW,UACX,MAAM,QAgChB;IAED;;;;OAIG;IACH,cAJW,MAAM,aACN,WAAW,UACX,MAAM,QAIhB;;CAgJJ;8BAloBY,OAAO,+CAA+C,EAAE,eAAe;0BACvE,OAAO,4CAA4C,EAAE,WAAW;qBAChE,OAAO,oBAAoB,EAAE,MAAM;6BACnC,OAAO,4BAA4B,EAAE,cAAc;4CACnD,OAAO,kCAAkC,EAAE,6BAA6B;6BACxE,OAAO,qBAAqB,EAAE,cAAc;uBAnBlC,kBAAkB;4BACb,iCAAiC;uBAItC,6CAA6C;sBAN9C,qCAAqC"}