@woosh/meep-engine 3.23.0 → 3.25.0

package/src/shade/renderer/scene/NODE3D_STRUCT.d.ts

@@ -21,11 +21,11 @@ export const NODE3D_STRUCT: WebGPUStruct;
 /**
  * Reserved row id for the scene root in the GPU `transforms` table.
  *
- * The scene's transform record sits at index 0 — set up once during
- * {@link GPUSceneContext.build} from `scene.transform_local`. Any node
- * whose CPU-side `parent` is null (i.e. a top-level node) gets a GPU
- * `parent` field of `NODE3D_SCENE_ID`, so it inherits the scene's
- * world transform.
+ * The root's record sits at index 0 — identity, written once by
+ * `GPUSceneContext.build`, its first. An entity whose attachment names
+ * no entity with a row gets a GPU `parent` field of `NODE3D_SCENE_ID`
+ * and carries its world pose as its local one, so the composition is
+ * exact.
  *
  * The transform-hierarchy pass also treats `parent == NODE3D_SCENE_ID`
  * as the walk termination condition. That makes 0 — the natural value

package/src/shade/renderer/scene/NODE3D_STRUCT.js

@@ -69,11 +69,11 @@ export const NODE3D_STRUCT = WebGPUStruct.from({
 /**
  * Reserved row id for the scene root in the GPU `transforms` table.
  *
- * The scene's transform record sits at index 0 — set up once during
- * {@link GPUSceneContext.build} from `scene.transform_local`. Any node
- * whose CPU-side `parent` is null (i.e. a top-level node) gets a GPU
- * `parent` field of `NODE3D_SCENE_ID`, so it inherits the scene's
- * world transform.
+ * The root's record sits at index 0 — identity, written once by
+ * `GPUSceneContext.build`, its first. An entity whose attachment names
+ * no entity with a row gets a GPU `parent` field of `NODE3D_SCENE_ID`
+ * and carries its world pose as its local one, so the composition is
+ * exact.
  *
  * The transform-hierarchy pass also treats `parent == NODE3D_SCENE_ID`
  * as the walk termination condition. That makes 0 — the natural value

package/src/shade/renderer/scene/Scene.d.ts

@@ -1,35 +1,27 @@
 /**
- * Scene root. Acts as the implicit parent of every top-level node in
- * the GPU scene-graph: `GPUSceneContext.build` allocates row 0 of the
- * `transforms` table to the scene and sets every orphan node's GPU
- * `parent` field to {@link NODE3D_SCENE_ID} (= 0). The scene's own
- * `transform_local` defaults to identity, but the user can pose it
- * (e.g. world-shift the whole hierarchy) just like any other Node3D.
+ * @typedef {import("../../../engine/ecs/EntityComponentDataset.js").EntityComponentDataset} EntityComponentDataset
+ */
+/**
+ * A scene: the dataset whose entities are what it draws and poses, and the three things that are
+ * not entities — its lights' collection, a light probe volume, volumetrics.
  *
- * Inheriting from {@link Node3D} keeps the CPU and GPU views aligned —
- * the scene has the same TRS-backed transform shape as every other
- * node, and animation tracks targeting node id 0 work without any
- * special case.
+ * Everything drawn is an entity of {@link dataset} holding a row of the scene's GPU database
+ * (`GPUSceneContext.rows`), at `entity + 1`. A game's systems take rows as components appear; a
+ * scene with no systems places a model with `prefab_place`, a primitive with `place_primitive`
+ * and a light with `place_light`. Nothing is added to the scene itself.
  */
-export class Scene extends Node3D {
-    instances: InstanceBatch;
-    /**
-     * Number of *renderable* mesh instances. Drives the rasterization
-     * pipeline's per-mesh dispatches.
-     *
-     * @return {number}
-     */
-    get instance_count(): number;
+export class Scene {
     /**
-     * Total GPU node-record count — meshes plus any non-mesh
-     * {@link Node3D}s in the batch (anchors, attachment points,
-     * future skeleton joints), *plus the scene itself* at row 0. Drives
-     * the GPU scene-graph propagation pass's iteration range.
+     * The dataset whose entities are this scene's rows. A scene is bound to one dataset; whoever
+     * owns both names it here, before anything asks the scene's GPU context for its rows. Null
+     * for a scene that draws nothing.
      *
-     * @return {number}
+     * @type {EntityComponentDataset|null}
      */
-    get node_count(): number;
+    dataset: EntityComponentDataset | null;
     /**
+     * Each light at an entity of {@link dataset} — `lights.add(light, entity)`, or `place_light`
+     * for a caller with no entity of its own.
      *
      * @type {LightCollection}
      */
@@ -44,47 +36,13 @@ export class Scene extends Node3D {
      * @type {SceneVolumetrics}
      */
     volumetrics: SceneVolumetrics;
-    hash(): number;
-    /**
-     *
-     * @param {Scene} other
-     */
-    equals(other: Scene): boolean;
-    /**
-     * Add a `Node3D` (or any of its subclasses — `Mesh`, `Light`, …) to
-     * the scene. Children of the node are traversed and added too. Pass
-     * an array to add several nodes at once.
-     *
-     * Routing rule:
-     *  - {@link isLight}-tagged nodes go to {@link lights} (their own
-     *    GPU pipeline) and are *not* tracked by the instance batch.
-     *  - Everything else — meshes, anchors, future skeleton joints —
-     *    goes into {@link instances}, the InstanceBatch. Meshes also
-     *    surface in `instances.instances` (the rendered subset);
-     *    non-mesh nodes are visible only as part of `instances.nodes`,
-     *    which is what the GPU scene-graph propagation pass iterates.
-     *
-     * @param {Node3D|Node3D[]} node
-     */
-    add(node: Node3D | Node3D[]): void;
-    /**
-     * Take a node back out, along with everything {@link add} brought in with it.
-     *
-     * Routing mirrors {@link add} exactly: lights leave {@link lights}, everything else leaves
-     * {@link instances}. A node is only ever in one of them, so the two are not both consulted.
-     *
-     * @param {Node3D|Node3D[]} node
-     * @returns {boolean} true if the node itself was found and dropped
-     */
-    remove(node: Node3D | Node3D[]): boolean;
     /**
      * @readonly
      * @type {boolean}
      */
     readonly isScene: boolean;
 }
-import { Node3D } from "./Node3D.js";
-import { InstanceBatch } from "./InstanceBatch.js";
+export type EntityComponentDataset = import("../../../engine/ecs/EntityComponentDataset.js").EntityComponentDataset;
 import { LightCollection } from "../light/LightCollection.js";
 import { LightProbeVolume } from "../global_illumination/lpv/LightProbeVolume.js";
 import { SceneVolumetrics } from "../volumetrics/SceneVolumetrics.js";

package/src/shade/renderer/scene/Scene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/Scene.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;GAYG;AACH;IACI,yBAAgC;IAEhC;;;;;OAKG;IACH,6BAEC;IAED;;;;;;;OAOG;IACH,yBAEC;IAED;;;OAGG;IACH,QAFU,eAAe,CAEM;IAE/B;;;OAGG;IACH,oBAFU,gBAAgB,CAEkB;IAE5C;;;OAGG;IACH,aAFU,gBAAgB,CAEW;IAErC,eAEC;IAED;;;OAGG;IACH,cAFW,KAAK,WAIf;IAED;;;;;;;;;;;;;;;OAeG;IACH,UAFW,MAAM,GAAC,MAAM,EAAE,QAkBzB;IAED;;;;;;;;OAQG;IACH,aAHW,MAAM,GAAC,MAAM,EAAE,GACb,OAAO,CAuBnB;IAGL;;;OAGG;IACH,kBAFU,OAAO,CAEM;CANtB;uBAvIsB,aAAa;8BADN,oBAAoB;gCAFlB,6BAA6B;iCAD5B,gDAAgD;iCAEhD,oCAAoC"}
+{"version":3,"file":"Scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/Scene.js"],"names":[],"mappings":"AAIA;;GAEG;AAEH;;;;;;;;GAQG;AACH;IACI;;;;;;OAMG;IACH,SAFU,sBAAsB,GAAC,IAAI,CAEtB;IAEf;;;;;OAKG;IACH,QAFU,eAAe,CAEM;IAE/B;;;OAGG;IACH,oBAFU,gBAAgB,CAEkB;IAE5C;;;OAGG;IACH,aAFU,gBAAgB,CAEW;IAGzC;;;OAGG;IACH,kBAFU,OAAO,CAEM;CANtB;qCAzCY,OAAO,+CAA+C,EAAE,sBAAsB;gCAJ3D,6BAA6B;iCAD5B,gDAAgD;iCAEhD,oCAAoC"}

package/src/shade/renderer/scene/Scene.js

@@ -1,146 +1,53 @@
-import { LightProbeVolume } from "../global_illumination/lpv/LightProbeVolume.js";
-import { LightCollection } from "../light/LightCollection.js";
-import { SceneVolumetrics } from "../volumetrics/SceneVolumetrics.js";
-import { InstanceBatch } from "./InstanceBatch.js";
-import { Node3D } from "./Node3D.js";
-
-/**
- * Scene root. Acts as the implicit parent of every top-level node in
- * the GPU scene-graph: `GPUSceneContext.build` allocates row 0 of the
- * `transforms` table to the scene and sets every orphan node's GPU
- * `parent` field to {@link NODE3D_SCENE_ID} (= 0). The scene's own
- * `transform_local` defaults to identity, but the user can pose it
- * (e.g. world-shift the whole hierarchy) just like any other Node3D.
- *
- * Inheriting from {@link Node3D} keeps the CPU and GPU views aligned —
- * the scene has the same TRS-backed transform shape as every other
- * node, and animation tracks targeting node id 0 work without any
- * special case.
- */
-export class Scene extends Node3D {
-    instances = new InstanceBatch();
-
-    /**
-     * Number of *renderable* mesh instances. Drives the rasterization
-     * pipeline's per-mesh dispatches.
-     *
-     * @return {number}
-     */
-    get instance_count() {
-        return this.instances.instances.length;
-    }
-
-    /**
-     * Total GPU node-record count — meshes plus any non-mesh
-     * {@link Node3D}s in the batch (anchors, attachment points,
-     * future skeleton joints), *plus the scene itself* at row 0. Drives
-     * the GPU scene-graph propagation pass's iteration range.
-     *
-     * @return {number}
-     */
-    get node_count() {
-        return this.instances.nodes.length + 1;
-    }
-
-    /**
-     *
-     * @type {LightCollection}
-     */
-    lights = new LightCollection();
-
-    /**
-     *
-     * @type {LightProbeVolume}
-     */
-    light_probe_volume = new LightProbeVolume();
-
-    /**
-     *
-     * @type {SceneVolumetrics}
-     */
-    volumetrics = new SceneVolumetrics();
-
-    hash() {
-        return 0;
-    }
-
-    /**
-     *
-     * @param {Scene} other
-     */
-    equals(other) {
-        return this.instances.equals(other.instances);
-    }
-
-    /**
-     * Add a `Node3D` (or any of its subclasses — `Mesh`, `Light`, …) to
-     * the scene. Children of the node are traversed and added too. Pass
-     * an array to add several nodes at once.
-     *
-     * Routing rule:
-     *  - {@link isLight}-tagged nodes go to {@link lights} (their own
-     *    GPU pipeline) and are *not* tracked by the instance batch.
-     *  - Everything else — meshes, anchors, future skeleton joints —
-     *    goes into {@link instances}, the InstanceBatch. Meshes also
-     *    surface in `instances.instances` (the rendered subset);
-     *    non-mesh nodes are visible only as part of `instances.nodes`,
-     *    which is what the GPU scene-graph propagation pass iterates.
-     *
-     * @param {Node3D|Node3D[]} node
-     */
-    add(node) {
-        if (Array.isArray(node)) {
-            for (const n of node) this.add(n);
-            return;
-        }
-
-        if (node.isLight === true) {
-            this.lights.add(node);
-        } else {
-            this.instances.add(node);
-        }
-
-        const children = node.children;
-        for (let i = 0; i < children.length; i++) {
-            this.add(children[i]);
-        }
-    }
-
-    /**
-     * Take a node back out, along with everything {@link add} brought in with it.
-     *
-     * Routing mirrors {@link add} exactly: lights leave {@link lights}, everything else leaves
-     * {@link instances}. A node is only ever in one of them, so the two are not both consulted.
-     *
-     * @param {Node3D|Node3D[]} node
-     * @returns {boolean} true if the node itself was found and dropped
-     */
-    remove(node) {
-        if (Array.isArray(node)) {
-            let any = false;
-
-            for (const n of node) {
-                any = this.remove(n) || any;
-            }
-
-            return any;
-        }
-
-        const removed = node.isLight === true
-            ? this.lights.remove(node)
-            : this.instances.remove(node);
-
-        const children = node.children;
-        for (let i = 0; i < children.length; i++) {
-            this.remove(children[i]);
-        }
-
-        return removed;
-    }
-}
-
-/**
- * @readonly
- * @type {boolean}
- */
-Scene.prototype.isScene = true;
+import { LightProbeVolume } from "../global_illumination/lpv/LightProbeVolume.js";
+import { LightCollection } from "../light/LightCollection.js";
+import { SceneVolumetrics } from "../volumetrics/SceneVolumetrics.js";
+
+/**
+ * @typedef {import("../../../engine/ecs/EntityComponentDataset.js").EntityComponentDataset} EntityComponentDataset
+ */
+
+/**
+ * A scene: the dataset whose entities are what it draws and poses, and the three things that are
+ * not entities — its lights' collection, a light probe volume, volumetrics.
+ *
+ * Everything drawn is an entity of {@link dataset} holding a row of the scene's GPU database
+ * (`GPUSceneContext.rows`), at `entity + 1`. A game's systems take rows as components appear; a
+ * scene with no systems places a model with `prefab_place`, a primitive with `place_primitive`
+ * and a light with `place_light`. Nothing is added to the scene itself.
+ */
+export class Scene {
+    /**
+     * The dataset whose entities are this scene's rows. A scene is bound to one dataset; whoever
+     * owns both names it here, before anything asks the scene's GPU context for its rows. Null
+     * for a scene that draws nothing.
+     *
+     * @type {EntityComponentDataset|null}
+     */
+    dataset = null;
+
+    /**
+     * Each light at an entity of {@link dataset} — `lights.add(light, entity)`, or `place_light`
+     * for a caller with no entity of its own.
+     *
+     * @type {LightCollection}
+     */
+    lights = new LightCollection();
+
+    /**
+     *
+     * @type {LightProbeVolume}
+     */
+    light_probe_volume = new LightProbeVolume();
+
+    /**
+     *
+     * @type {SceneVolumetrics}
+     */
+    volumetrics = new SceneVolumetrics();
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+Scene.prototype.isScene = true;

package/src/shade/renderer/scene/bvh/StaticSceneBVH.d.ts

@@ -10,12 +10,20 @@ export class StaticSceneBVH {
      *
      * @type {Map<number, Mesh>}
      */
-    inverse_lookup: Map<number, Mesh>;
     /**
+     * The primitive behind each leaf's user data.
      *
-     * @param {Scene} scene
+     * @type {Map<number, StaticSceneInstance>}
      */
-    build(scene: Scene): void;
+    inverse_lookup: Map<number, StaticSceneInstance>;
+    /**
+     * Build the tree over every primitive the scene draws: the mesh rows of its context, each
+     * under the world transform its entity carries — the ECS's own composition, which is exact for
+     * a scene the CPU places, and what a CPU bake of a static scene wants.
+     *
+     * @param {GPUSceneContext} scene_context
+     */
+    build(scene_context: GPUSceneContext): void;
     /**
      * Note: will produce incorrect results for non-uniformly scaled meshes
      * @param {SurfacePoint3} hit
@@ -55,6 +63,19 @@ export class StaticSceneBVH {
         distance: number;
     }[], ray: Ray3): number;
 }
+export type GPUSceneContext = import("../GPUSceneContext.js").GPUSceneContext;
+export type MeshletGeometry = import("../../geometry/MeshletGeometry.js").MeshletGeometry;
+export type ShadeMaterial = import("../../material/ShadeMaterial.js").ShadeMaterial;
+/**
+ * One primitive as the tree holds it: the entity it stands at, what it draws and with what, and a
+ * view over the world matrix its entity carries.
+ */
+export type StaticSceneInstance = {
+    entity: number;
+    geometry: MeshletGeometry;
+    material: ShadeMaterial;
+    matrix: Float64Array;
+};
 import { BVH } from "../../../../core/bvh2/bvh3/BVH.js";
 import { BinaryUint32BVH } from "../../../../core/bvh2/binary/2/BinaryUint32BVH.js";
 import { SurfacePoint3 } from "../../../../core/geom/3d/SurfacePoint3.js";

package/src/shade/renderer/scene/bvh/StaticSceneBVH.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StaticSceneBVH.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/scene/bvh/StaticSceneBVH.js"],"names":[],"mappings":"AA4DA;IAEI,kBAAyB;IAEzB;;;OAGG;IACH,cAFU,cAAc,eAAe,CAAC,CAEf;IAEzB,gCAA6B;IAE7B;;;OAGG;IACH,gBAFU,IAAI,MAAM,OAAO,CAEA;IAG3B;;;OAGG;IACH,0BA2DC;IAED;;;;;;;OAOG;IACH,qCANW,aAAa,KACb,MAAM,KACN,MAAM,KACN,MAAM,GACJ,OAAO,CAqJnB;IAED;;;;;;;;;OASG;IACH,mCARW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,OAAO,CAmEnB;IAGD;;;;;OAKG;IACH,qBAJW,aAAa,OACb,IAAI,GACF,OAAO,CA2GnB;IAED;;;;;OAKG;IACH,iBAJW;QAAC,GAAG,EAAE,aAAa,CAAC;QAAC,IAAI,OAAM;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,EAAE,OACnD,IAAI,GACH,MAAM,CAmEjB;CAGJ;oBA7iBM,mCAAmC;gCARV,mDAAmD;8BA0BrD,2CAA2C;qBADpD,sCAAsC"}
+{"version":3,"file":"StaticSceneBVH.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/scene/bvh/StaticSceneBVH.js"],"names":[],"mappings":"AA6EA;IAEI,kBAAyB;IAEzB;;;OAGG;IACH,cAFU,cAAc,eAAe,CAAC,CAEf;IAEzB,gCAA6B;IAE7B;;;OAGG;IACH;;;;OAIG;IACH,gBAFU,IAAI,MAAM,EAAE,mBAAmB,CAAC,CAEf;IAG3B;;;;;;OAMG;IACH,qBAFW,eAAe,QA4EzB;IAED;;;;;;;OAOG;IACH,qCANW,aAAa,KACb,MAAM,KACN,MAAM,KACN,MAAM,GACJ,OAAO,CAqJnB;IAED;;;;;;;;;OASG;IACH,mCARW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,OAAO,CAmEnB;IAGD;;;;;OAKG;IACH,qBAJW,aAAa,OACb,IAAI,GACF,OAAO,CA2GnB;IAED;;;;;OAKG;IACH,iBAJW;QAAC,GAAG,EAAE,aAAa,CAAC;QAAC,IAAI,OAAM;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,EAAE,OACnD,IAAI,GACH,MAAM,CAmEjB;CAGJ;8BA/hBY,OAAO,uBAAuB,EAAE,eAAe;8BAC/C,OAAO,mCAAmC,EAAE,eAAe;4BAC3D,OAAO,iCAAiC,EAAE,aAAa;;;;;kCAOvD;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAC;oBA7DhG,mCAAmC;gCARV,mDAAmD;8BA0BrD,2CAA2C;qBADpD,sCAAsC"}

package/src/shade/renderer/scene/bvh/StaticSceneBVH.js

@@ -1,4 +1,6 @@
 import { assert } from "../../../../core/assert.js";
+import { aabb3_matrix4_project } from "../../../../core/geom/3d/aabb/aabb3_matrix4_project.js";
+import { Transform64 } from "../../../../engine/ecs/transform/Transform64.js";
 import { BinaryUint32BVH } from "../../../../core/bvh2/binary/2/BinaryUint32BVH.js";
 import {
     BVH,
@@ -58,6 +60,21 @@ const scratch_surface_point = new SurfacePoint3();
 const scratch_vec3 = new Vector3();
 
 
+/**
+ * @typedef {import("../GPUSceneContext.js").GPUSceneContext} GPUSceneContext
+ * @typedef {import("../../geometry/MeshletGeometry.js").MeshletGeometry} MeshletGeometry
+ * @typedef {import("../../material/ShadeMaterial.js").ShadeMaterial} ShadeMaterial
+ */
+
+/**
+ * One primitive as the tree holds it: the entity it stands at, what it draws and with what, and a
+ * view over the world matrix its entity carries.
+ *
+ * @typedef {{entity: number, geometry: MeshletGeometry, material: ShadeMaterial, matrix: Float64Array}} StaticSceneInstance
+ */
+
+const SCRATCH_INSTANCE_BOX = new Float64Array(6);
+
 export class StaticSceneBVH {
 
     instance_bvh = new BVH();
@@ -74,14 +91,28 @@ export class StaticSceneBVH {
      *
      * @type {Map<number, Mesh>}
      */
+    /**
+     * The primitive behind each leaf's user data.
+     *
+     * @type {Map<number, StaticSceneInstance>}
+     */
     inverse_lookup = new Map();
 
 
     /**
+     * Build the tree over every primitive the scene draws: the mesh rows of its context, each
+     * under the world transform its entity carries — the ECS's own composition, which is exact for
+     * a scene the CPU places, and what a CPU bake of a static scene wants.
      *
-     * @param {Scene} scene
+     * @param {GPUSceneContext} scene_context
      */
-    build(scene) {
+    build(scene_context) {
+        assert.defined(scene_context, 'scene_context');
+
+        const dataset = scene_context.scene.dataset;
+
+        assert.ok(dataset !== null && dataset !== undefined, 'the scene names no dataset, and its primitives are entities of one');
+
         this.inverse_lookup.clear();
         this.instance_bvh.release_all();
         this.geometry_bvh.clear();
@@ -89,7 +120,15 @@ export class StaticSceneBVH {
 
         let id_count = 0;
 
-        scene.instances.instances.forEach(mesh => {
+        scene_context.rows.for_each_mesh((entity, geometry, material) => {
+            const world = dataset.getComponent(entity, Transform64);
+
+            assert.defined(world, `entity ${entity} holds a mesh row and no Transform64`);
+
+            // a view over the transform, so a placement moved before the next build is read as moved
+            const matrix = world.matrix;
+
+            aabb3_matrix4_project(SCRATCH_INSTANCE_BOX, geometry.bounding_box, matrix);
 
             const bvh = this.instance_bvh;
 
@@ -98,9 +137,12 @@ export class StaticSceneBVH {
             const id = id_count++;
 
             bvh.node_set_user_data(leaf, id)
-            bvh.node_set_aabb(leaf, mesh.bounding_box);
+            bvh.node_set_aabb(leaf, SCRATCH_INSTANCE_BOX);
             bvh.insert_leaf(leaf);
 
+            /** @type {StaticSceneInstance} */
+            const mesh = { entity, geometry, material, matrix };
+
             this.inverse_lookup.set(id, mesh);
 
             /**
@@ -121,8 +163,6 @@ export class StaticSceneBVH {
                 return bvh;
             }
 
-            const geometry = mesh.geometry;
-
             // TODO get rid of the plain geometry usage, move fully onto meshlet-based flow
             if(this.plain_geometries.has(geometry) === false) {
 
@@ -259,7 +299,7 @@ export class StaticSceneBVH {
                 const geometry_bvh = this.geometry_bvh.get(mesh.geometry);
 
                 // transform search point into local space of the geometry
-                m4_invert(scratch_transform_inverse, mesh.transform_global.matrix);
+                m4_invert(scratch_transform_inverse, mesh.matrix);
                 scratch_vec3.set(x, y, z);
                 scratch_vec3.applyMatrix4(scratch_transform_inverse);
 
@@ -280,7 +320,7 @@ export class StaticSceneBVH {
                 }
 
                 // transform result back to global space
-                scratch_surface_point.applyMatrix4(mesh.transform_global.matrix);
+                scratch_surface_point.applyMatrix4(mesh.matrix);
 
                 const geo_distance_sqr = scratch_surface_point.position._distanceSqrTo(x, y, z);
 
@@ -344,7 +384,7 @@ export class StaticSceneBVH {
             );
 
             // Get world -> object transform matrix
-            m4_invert(scratch_transform_inverse, mesh.transform_global.matrix);
+            m4_invert(scratch_transform_inverse, mesh.matrix);
 
             // Transform clipping volume to object space
             clipping_volume_matrix4_project(
@@ -414,7 +454,7 @@ export class StaticSceneBVH {
             const geometry_bvh = this.geometry_bvh.get(mesh.geometry);
 
 
-            m4_invert(scratch_transform_inverse, mesh.transform_global.matrix);
+            m4_invert(scratch_transform_inverse, mesh.matrix);
 
             scratch_local_ray.copy(ray);
             scratch_local_ray.tMax = nearest_distance;
@@ -441,7 +481,7 @@ export class StaticSceneBVH {
                 continue;
             }
 
-            sp.applyMatrix4(mesh.transform_global.matrix);
+            sp.applyMatrix4(mesh.matrix);
 
             const distance = sp.position._distanceTo(
                 ray.origin_x, ray.origin_y, ray.origin_z
@@ -520,7 +560,7 @@ export class StaticSceneBVH {
             const geometry = this.plain_geometries.get(mesh.geometry);
             const geometry_bvh = this.geometry_bvh.get(mesh.geometry);
 
-            m4_invert(scratch_transform_inverse, mesh.transform_global.matrix);
+            m4_invert(scratch_transform_inverse, mesh.matrix);
 
             scratch_local_ray.copy(ray);
             scratch_local_ray.applyMatrix4(scratch_transform_inverse);
@@ -545,7 +585,7 @@ export class StaticSceneBVH {
                 continue;
             }
 
-            sp.applyMatrix4(mesh.transform_global.matrix);
+            sp.applyMatrix4(mesh.matrix);
 
             const distance = sp.position._distanceTo(
                 ray.origin_x, ray.origin_y, ray.origin_z

package/src/shade/renderer/scene/hierarchy/graph_scene_update_transform_hierarchy.d.ts

@@ -4,12 +4,11 @@
  *
  * Builds a flat `{count, elements}` buffer holding all node IDs and
  * feeds it through {@link graph_nodes_update_transform_hierarchy}.
- * `GPUSceneContext` allocates row 0 of the transforms table to the
- * scene root (NODE3D_SCENE_ID) and a row to every other node in the
- * batch — meshes and non-mesh Node3Ds alike (anchor rigs, attachment
- * points, future skeleton joints). The scene itself is included, and
- * its walk terminates immediately at parent==SCENE_NODE_ID so its
- * identity-default global stays consistent.
+ * Row 0 of the transforms table is the scene root (NODE3D_SCENE_ID),
+ * and every other row is an entity's, at `entity + 1` — drawn or not:
+ * joints, anchors and attachment points hold rows too. The root is
+ * included, and its walk terminates immediately at parent==SCENE_NODE_ID
+ * so its identity global stays consistent.
  *
  * **The rows are not a contiguous range.** Removing a node frees its
  * row and leaves a hole, so the ids come from the table's occupancy

package/src/shade/renderer/scene/hierarchy/graph_scene_update_transform_hierarchy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_scene_update_transform_hierarchy.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/scene/hierarchy/graph_scene_update_transform_hierarchy.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH;IAZqC,KAAK;IACL,KAAK;IACL,cAAc,GAAxC,MAAM;IAOJ;IAAE,cAAc,EAAE,MAAM,CAAA;CAAE,CAwFtC"}
+{"version":3,"file":"graph_scene_update_transform_hierarchy.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/scene/hierarchy/graph_scene_update_transform_hierarchy.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH;IAZqC,KAAK;IACL,KAAK;IACL,cAAc,GAAxC,MAAM;IAOJ;IAAE,cAAc,EAAE,MAAM,CAAA;CAAE,CAwFtC"}

package/src/shade/renderer/scene/hierarchy/graph_scene_update_transform_hierarchy.js

@@ -11,12 +11,11 @@ import { graph_nodes_update_transform_hierarchy } from "./graph_nodes_update_tra
  *
  * Builds a flat `{count, elements}` buffer holding all node IDs and
  * feeds it through {@link graph_nodes_update_transform_hierarchy}.
- * `GPUSceneContext` allocates row 0 of the transforms table to the
- * scene root (NODE3D_SCENE_ID) and a row to every other node in the
- * batch — meshes and non-mesh Node3Ds alike (anchor rigs, attachment
- * points, future skeleton joints). The scene itself is included, and
- * its walk terminates immediately at parent==SCENE_NODE_ID so its
- * identity-default global stays consistent.
+ * Row 0 of the transforms table is the scene root (NODE3D_SCENE_ID),
+ * and every other row is an entity's, at `entity + 1` — drawn or not:
+ * joints, anchors and attachment points hold rows too. The root is
+ * included, and its walk terminates immediately at parent==SCENE_NODE_ID
+ * so its identity global stays consistent.
  *
  * **The rows are not a contiguous range.** Removing a node frees its
  * row and leaves a hole, so the ids come from the table's occupancy

package/src/shade/renderer/scene/optimization/scene_optimize.d.ts

@@ -1,6 +1,14 @@
 /**
+ * Make a loaded model cheaper to draw without changing what it looks like: exact-duplicate
+ * geometries collapse to one, equivalent pieces of different geometries are shared, and the
+ * textures the materials reach are deduplicated and downscaled where that loses nothing.
  *
- * @param {Scene} scene
+ * The bundle is rewritten in place — it is the tool's, not a shared asset's.
+ *
+ * @param {SceneBundle} bundle
  */
-export function scene_optimize(scene: Scene): void;
+export function scene_optimize(bundle: SceneBundle): void;
+export type SceneBundle = import("../../loader/SceneBundle.js").SceneBundle;
+export type MeshletGeometry = import("../../geometry/MeshletGeometry.js").MeshletGeometry;
+export type Geometry = import("../../geometry/Geometry.js").Geometry;
 //# sourceMappingURL=scene_optimize.d.ts.map

package/src/shade/renderer/scene/optimization/scene_optimize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scene_optimize.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/scene/optimization/scene_optimize.js"],"names":[],"mappings":"AAoMA;;;GAGG;AACH,mDA6BC"}
+{"version":3,"file":"scene_optimize.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/scene/optimization/scene_optimize.js"],"names":[],"mappings":"AAkOA;;;;;;;;GAQG;AACH,uCAFW,WAAW,QAgCrB;0BA/PY,OAAO,6BAA6B,EAAE,WAAW;8BACjD,OAAO,mCAAmC,EAAE,eAAe;uBAC3D,OAAO,4BAA4B,EAAE,QAAQ"}