@woosh/meep-engine 3.2.0 → 3.4.0

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

@@ -1,15 +1,45 @@
 import { assert } from "../../../core/assert.js";
 import { BVH } from "../../../core/bvh2/bvh3/BVH.js";
-import { ebvh_optimize_treelet } from "../../../core/bvh2/bvh3/ebvh_optimize_treelet.js";
+import { FrameGraph } from "../../../engine/graphics/render/frame_graph/FrameGraph.js";
+import { BufferResourceDescriptor } from "../../device/graph/BufferResourceDescriptor.js";
+import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
 import { ensure_buffer_capacity } from "../geometry/make_temp_gpu_buffer.js";
-import { BVH2_NODE_STRUCT } from "../shader/chunk/bvh/BVH2_NODE_STRUCT.js";
-import { bvh_to_gpu_buffer } from "../geometry/bvh/bvh_to_gpu_buffer.js";
+import { BVH_BUILD_SETTINGS_STRUCT } from "../gpu_primitive/bvh/BVH_BUILD_SETTINGS_STRUCT.js";
+import { bvh_buffer_size } from "../gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js";
+import { graph_bvh_build_lbvh } from "../gpu_primitive/bvh/graph_bvh_build_lbvh.js";
+import { shader_bvh_extract_instance_leaves } from "./shader_bvh_extract_instance_leaves.js";
+
+/**
+ * `root = BVH_NULL_NODE` — an empty tree, in the four bytes every consumer already reads that way.
+ * @type {Uint32Array}
+ */
+const EMPTY_TREE = Uint32Array.from([0xffffffff]);
+
+/**
+ * The scene-bounds cell before anything has been merged into it: +inf for the three minima, -inf
+ * for the three maxima, so the first contribution wins on every axis.
+ *
+ * Written host-side as exact u32 bit patterns. A pool-cleared buffer holds zeroes, and zero is a
+ * perfectly good coordinate — a scene entirely in the positive octant would end up with bounds
+ * anchored at the origin and every Morton code crushed into a corner of the grid.
+ *
+ * @type {Uint32Array}
+ */
+const SCENE_BOUNDS_SEED = Uint32Array.from([
+    0x7F800000, 0x7F800000, 0x7F800000,
+    0xFF800000, 0xFF800000, 0xFF800000,
+]);
 
 /**
  * Top-Level Acceleration Structure (TLAS)
  */
 export class GPUInstancesAccelerationStructure {
 
+    /**
+     * @type {GraphicsContext}
+     */
+    #graphics
+
     /**
      * @type {GPUDevice}
      */
@@ -17,6 +47,12 @@ export class GPUInstancesAccelerationStructure {
 
     #bvh = new BVH();
 
+    /**
+     * The CPU-side tree. Still maintained incrementally by the `instance_*` methods and still walked
+     * by CPU queries — {@link DirectionalLightShadowmap} runs `compute_tight_near_far_clipping_planes`
+     * against it per cascade per frame. What the GPU build retires is the per-frame treelet pass and
+     * the full flatten-and-upload, not the tree.
+     */
     get bvh() {
         return this.#bvh;
     }
@@ -24,6 +60,7 @@ export class GPUInstancesAccelerationStructure {
     clear() {
         this.#bvh.release_all();
         this.#node_mapping.clear();
+        this.#membership_version++;
         this.#version++;
     }
 
@@ -44,15 +81,48 @@ export class GPUInstancesAccelerationStructure {
     #version = 0;
 
     /**
+     * Bumped when the set of live rows changes — an add or a remove — and not when one merely moves.
+     * The rows list is uploaded only when this moves, so a scene in continuous motion re-uploads
+     * nothing.
+     *
+     * @type {number}
+     */
+    #membership_version = 0;
+
+    /**
+     * Membership version the {@link #rows_buffer} currently holds.
+     * @type {number}
+     */
+    #rows_gpu_version = -1;
+
+    /**
+     * Compact mirror of the live `meshes` rows, in insertion order. Rebuilt from
+     * {@link #node_mapping} when membership churns.
      *
-     * @param {GPUDevice} device
+     * @type {Uint32Array}
      */
-    constructor(device) {
-        assert.defined(device, 'device');
+    #rows = new Uint32Array(0);
+
+    /**
+     * @type {GPUBuffer|undefined}
+     */
+    #rows_buffer
+
+    /**
+     *
+     * @param {GraphicsContext} graphics
+     */
+    constructor(graphics) {
+        assert.defined(graphics, 'graphics');
+        assert.equal(graphics.isGraphicsContext, true, 'graphics.isGraphicsContext !== true');
+
+        const device = graphics.device;
 
+        this.#graphics = graphics;
         this.#device = device;
 
         this.#buffer = device.createBuffer({
+            label: 'TLAS',
             size: 1024,
             usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC
         });
@@ -83,6 +153,7 @@ export class GPUInstancesAccelerationStructure {
 
         this.#node_mapping.set(index, node);
 
+        this.#membership_version++;
         this.#version++;
     }
 
@@ -107,6 +178,7 @@ export class GPUInstancesAccelerationStructure {
 
         this.#node_mapping.delete(index);
 
+        this.#membership_version++;
         this.#version++;
     }
 
@@ -126,47 +198,186 @@ export class GPUInstancesAccelerationStructure {
         this.#version++;
     }
 
-    push_to_gpu() {
-        console.log('TLAS#push_to_gpu');
+    /**
+     * Bring {@link #rows_buffer} in line with the live row set, if and only if membership changed.
+     *
+     * @returns {number} number of live rows
+     */
+    #refresh_rows() {
+        const count = this.#node_mapping.size;
+
+        if (this.#rows_gpu_version === this.#membership_version && this.#rows.length >= count) {
+            return count;
+        }
+
+        if (this.#rows.length < count) {
+            this.#rows = new Uint32Array(count);
+        }
+
+        let i = 0;
+        for (const row of this.#node_mapping.keys()) {
+            this.#rows[i] = row;
+            i++;
+        }
+
+        const byte_size = Math.max(4, count * Uint32Array.BYTES_PER_ELEMENT);
+
+        if (this.#rows_buffer === undefined) {
+            this.#rows_buffer = this.#device.createBuffer({
+                label: 'TLAS/rows',
+                size: Math.max(1024, byte_size),
+                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC
+            });
+        } else {
+            this.#rows_buffer = ensure_buffer_capacity(this.#device, this.#rows_buffer, byte_size);
+        }
+
+        // Queue writes land in submission order ahead of command buffers submitted after them, so
+        // the build encoded below sees these rows. Offset and size are in elements of the source,
+        // per `GPUQueue.writeBuffer` — `#rows` can be longer than the live set.
+        this.#device.queue.writeBuffer(this.#rows_buffer, 0, this.#rows, 0, count);
 
-        const tree = this.#bvh;
+        this.#rows_gpu_version = this.#membership_version;
+
+        return count;
+    }
+
+    /**
+     * Build the tree, from the world AABBs the scene database holds.
+     *
+     * @param {GPUBuffer} scene_database_buffer
+     */
+    #build(scene_database_buffer) {
+        assert.defined(scene_database_buffer, 'scene_database_buffer');
 
         const device = this.#device;
 
-        ebvh_optimize_treelet(tree);
+        const element_count = this.#node_mapping.size;
 
+        // `ensure_buffer_capacity` can hand back a NEW buffer and destroy the old one. Consumers are
+        // safe because they read `tlas.buffer` per frame at pass-execute time — but the field has to
+        // be reassigned before the graph imports it.
         this.#buffer = ensure_buffer_capacity(
             device,
             this.#buffer,
-            tree.node_capacity * BVH2_NODE_STRUCT.size + 4,
+            bvh_buffer_size(Math.max(1, element_count)),
             1024,
             1024,
             1.2
         );
 
-        const tmp_buffer = bvh_to_gpu_buffer({
-            device,
-            bvh: tree,
-            usage: GPUBufferUsage.COPY_SRC,
-            label: 'TLAS/temp'
-        });
+        if (element_count === 0) {
+            device.queue.writeBuffer(this.#buffer, 0, EMPTY_TREE);
+
+            return;
+        }
+
+        this.#refresh_rows();
 
-        const encoder = device.createCommandEncoder();
+        const graph = new FrameGraph('TLAS build');
 
-        encoder.copyBufferToBuffer(tmp_buffer, 0, this.#buffer, 0, tmp_buffer.size);
+        const rows = graph.import_resource(
+            "tlas/rows",
+            BufferResourceDescriptor.fromBuffer(this.#rows_buffer),
+            this.#rows_buffer
+        );
 
-        device.queue.submit([encoder.finish()]);
+        const scene_database = graph.import_resource(
+            "scene database",
+            BufferResourceDescriptor.fromBuffer(scene_database_buffer),
+            scene_database_buffer
+        );
 
-        tmp_buffer.destroy();
+        const nodes = graph.import_resource(
+            "tlas/nodes",
+            BufferResourceDescriptor.fromBuffer(this.#buffer),
+            this.#buffer
+        );
+
+        const extract_data = {};
+        const extract_pass = graph.add("tlas/extract instance leaves", extract_data, extract_execute);
+
+        extract_data.element_count = element_count;
+        extract_data.rows = extract_pass.read(rows);
+        extract_data.scene_database = extract_pass.read(scene_database);
+
+        extract_data.leaf_bounds = extract_pass.create("tlas/leaf bounds", BufferResourceDescriptor.from(
+            element_count * 6 * Float32Array.BYTES_PER_ELEMENT,
+            GPUBufferUsage.STORAGE
+        ));
+
+        extract_data.leaf_payload = extract_pass.create("tlas/leaf payload", BufferResourceDescriptor.from(
+            element_count * Uint32Array.BYTES_PER_ELEMENT,
+            GPUBufferUsage.STORAGE
+        ));
+
+        extract_data.scene_bounds = extract_pass.create("tlas/scene bounds", BufferResourceDescriptor.from(
+            SCENE_BOUNDS_SEED.byteLength,
+            GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
+        ));
+
+        graph_bvh_build_lbvh({
+            graph,
+            leaf_bounds: extract_data.leaf_bounds,
+            leaf_payload: extract_data.leaf_payload,
+            scene_bounds: extract_data.scene_bounds,
+            element_count,
+            nodes,
+        });
+
+        const cmd = ShadeGPUCommandContext.create(this.#graphics, 'TLAS/build');
+
+        cmd.encodeGraph(graph);
+        cmd.finish();
+    }
+
+    /**
+     * @param {GPUBuffer} scene_database_buffer the table the world AABBs are read from
+     */
+    push_to_gpu(scene_database_buffer) {
+        this.#build(scene_database_buffer);
 
         this.#gpu_version = this.#version;
     }
 
-    update() {
+    /**
+     * @param {GPUBuffer} scene_database_buffer
+     */
+    update(scene_database_buffer) {
         if (this.#gpu_version === this.#version) {
             return;
         }
 
-        this.push_to_gpu();
+        this.push_to_gpu(scene_database_buffer);
     }
-}
+}
+
+/**
+ * @param pass_data
+ * @param {FramePassResources} resources
+ * @param {GraphicsExecutionContext} context
+ */
+function extract_execute(pass_data, resources, context) {
+    const encoder = context.encoder;
+
+    const scene_bounds = resources.get(pass_data.scene_bounds);
+
+    // Seeded rather than cleared: the merge is a min/max, and zero is not an identity for either.
+    encoder.writeBuffer(scene_bounds, 0, SCENE_BOUNDS_SEED.buffer, 0, SCENE_BOUNDS_SEED.byteLength);
+
+    shader_bvh_extract_instance_leaves.dispatchLinear({
+        encoder,
+        element_count: pass_data.element_count,
+        bindings: {
+            settings: encoder.allocateTransientValueBuffer(
+                BVH_BUILD_SETTINGS_STRUCT,
+                { element_count: pass_data.element_count }
+            ),
+            rows: resources.get(pass_data.rows),
+            scene_database: resources.get(pass_data.scene_database),
+            leaf_bounds: resources.get(pass_data.leaf_bounds),
+            leaf_payload: resources.get(pass_data.leaf_payload),
+            scene_bounds,
+        }
+    });
+}

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

@@ -1 +1 @@
-{"version":3,"file":"GPUSceneContext.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/GPUSceneContext.js"],"names":[],"mappings":"AA4DA;;GAEG;AACH;IAkJI;;;;OAIG;IACH,8CAFW,KAAK,EAiCf;IApLD;;;OAGG;IACH,aAFU,MAAM,CAEE;IAElB;;OAEG;IACH,+BAAW;IAEX;;OAEG;IACH,8BAAU;IAGV;;OAEG;IACH,sBAFU,cAAc,CAEH;IASrB;;;OAGG;IACH,mBAEC;IAOD,uCAEC;IAQD;;;OAGG;IACH,iCAEC;IAOD;;;OAGG;IACH,8CAEC;IAOD;;;OAGG;IACH,8CAEC;IAmBD;;;;;;;;;;;;;;OAcG;IACH,YAFU,IAAI,MAAM,EAAE,MAAM,CAAC,CAEN;IAgEvB;;OAEG;IACH,6CAEC;IAeD;;;OAGG;IACH,kCAEC;IAED;;;;;OAKG;IACH,uCAEC;IAED;;;;;;;;;;;;OAYG;IACH,uCAUC;IAED,+BAUC;IAuJD;;;;;;;;;;OAUG;IACH,2BAFa,MAAM,CAMlB;IAED;;;;;;;OAOG;IACH,gCAEC;IA+QD;;;;;;OAMG;IACH,cA4DC;IAED;;;OAGG;IACH,mCAsBC;IAED;;;;;;;;;;;;;OAaG;IACH,cAHW,sBAAsB,cACtB,MAAM,QAIhB;IAED,gBAQC;IAIL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C;+BAz3B8B,iDAAiD;sBAI1D,YAAY;oCADE,uCAAuC;mCADxC,gCAAgC;oCAD/B,mDAAmD;kDAIrC,wCAAwC;oCAPtD,qCAAqC;4BAC7C,gCAAgC;uCAOrB,iDAAiD;uCATjD,wCAAwC"}
+{"version":3,"file":"GPUSceneContext.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/GPUSceneContext.js"],"names":[],"mappings":"AA4DA;;GAEG;AACH;IAkJI;;;;OAIG;IACH,8CAFW,KAAK,EAiCf;IApLD;;;OAGG;IACH,aAFU,MAAM,CAEE;IAElB;;OAEG;IACH,+BAAW;IAEX;;OAEG;IACH,8BAAU;IAGV;;OAEG;IACH,sBAFU,cAAc,CAEH;IASrB;;;OAGG;IACH,mBAEC;IAOD,uCAEC;IAQD;;;OAGG;IACH,iCAEC;IAOD;;;OAGG;IACH,8CAEC;IAOD;;;OAGG;IACH,8CAEC;IAmBD;;;;;;;;;;;;;;OAcG;IACH,YAFU,IAAI,MAAM,EAAE,MAAM,CAAC,CAEN;IAgEvB;;OAEG;IACH,6CAEC;IAeD;;;OAGG;IACH,kCAEC;IAED;;;;;OAKG;IACH,uCAEC;IAED;;;;;;;;;;;;OAYG;IACH,uCAUC;IAED,+BAUC;IAkKD;;;;;;;;;;OAUG;IACH,2BAFa,MAAM,CAMlB;IAED;;;;;;;OAOG;IACH,gCAEC;IA+QD;;;;;;OAMG;IACH,cA4DC;IAED;;;OAGG;IACH,mCAuBC;IAED;;;;;;;;;;;;;OAaG;IACH,cAHW,sBAAsB,cACtB,MAAM,QAIhB;IAED,gBAQC;IAIL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C;+BAr4B8B,iDAAiD;sBAI1D,YAAY;oCADE,uCAAuC;mCADxC,gCAAgC;oCAD/B,mDAAmD;kDAIrC,wCAAwC;oCAPtD,qCAAqC;4BAC7C,gCAAgC;uCAOrB,iDAAiD;uCATjD,wCAAwC"}

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

@@ -223,7 +223,7 @@ export class GPUSceneContext {
         this.#device = device;
         this.#graphics = graphics;
 
-        this.#tlas = new GPUInstancesAccelerationStructure(device);
+        this.#tlas = new GPUInstancesAccelerationStructure(graphics);
 
         // Pass `this` so the light collection (and its child shadow context) can use
         // this scene's GPUSceneContext when building its own ViewManager — avoids
@@ -457,6 +457,17 @@ export class GPUSceneContext {
      * @returns {object} the module-static record, valid until the next call
      */
     #write_mesh_record(mesh, transform_row) {
+        // A skinned mesh's world bounds are a property of its *skeleton*, and the skeleton is not
+        // in the mesh's own subtree — Michelle's joint root is the mesh node's next sibling, which
+        // is the shape every glTF character has. `Node3D.updateMatrices` walks pre-order, so when
+        // the mesh's own bounds pass ran the joints it reads had not been visited yet and it
+        // described where the character stood before the move; a second walk would catch up, and
+        // nothing calls one. Re-deriving here costs a matrix per joint on a mesh that just moved,
+        // and here every walk is over — which is the only point at which the answer is knowable.
+        if (mesh.isSkinnedMesh === true) {
+            mesh.updateBoundsBasic();
+        }
+
         // SkinnedMesh routes to its per-instance clone (allocated + cached by the skinning
         // context); regular meshes get the source's id. obtain_geometry_index handles both,
         // idempotent.
@@ -860,8 +871,9 @@ export class GPUSceneContext {
 
         this.build();
 
-        // After the build, which is what feeds the TLAS this frame's arrivals, departures and moves.
-        this.#tlas.update();
+        // After the build, which is what feeds the TLAS this frame's arrivals, departures and moves —
+        // and, for the GPU build, writes the world AABBs it reads out of the `meshes` table.
+        this.#tlas.update(this.scene_database_buffer);
     }
 
     /**

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

@@ -20,25 +20,71 @@
  * vertex region — leaving every other instance pointed at the source
  * untouched. The skin matrices are computed per the glTF spec formula
  * `inverse(meshNode.worldMatrix) × jointNode.worldMatrix ×
- * inverseBindMatrix` so the SkinnedMesh's own `transform_global` is
- * the natural placement point in the scene graph — moving it (or
- * parenting it) moves the rendered character, exactly like a regular
- * Mesh. The `inverse(meshNode.worldMatrix)` factor is precomputed
- * CPU-side at skin registration; see {@link GPUAnimationManager#register_skin}.
+ * inverseBindMatrix`, and the rasterizer re-applies
+ * `mesh.transform_global` to the result — so the mesh node's own
+ * transform cancels out of the rendered position exactly, which is what
+ * the glTF spec asks for. The leftmost factor is taken live from the
+ * mesh's own transforms row inside {@link shader_meshlet_apply_skinning};
+ * see {@link chunk_skin_blend_mesh_local} for why it goes into each
+ * matrix rather than onto the blended position.
  *
- * The mesh's skin association lives in {@link GPUMeshSkinningContext} —
- * `SkinnedMesh` itself carries no GPU-side state. Bind the mesh to a
- * skin via `gpu_scene.skinning.bind(mesh, skin_id)`, or rely on
+ * The mesh's **skin id** — a row in a GPU table — lives in
+ * {@link GPUMeshSkinningContext} and nowhere else. The CPU-side
+ * {@link Skin} it was registered with is a different thing, pure data
+ * that knows nothing about the GPU, and this mesh holds a reference to
+ * it in {@link skin} so its bounds can be worked out without asking the
+ * GPU anything. Bind the mesh to a skin via
+ * `gpu_scene.skinning.bind(mesh, skin_id)`, or rely on
  * {@link GPUAnimationManager#register_skin} to do it for every entry
- * in `Skin.meshes`. Until bound, the clone routes through the
- * rendering path but its vertices stay at the source's bind-pose
- * values — useful as an intermediate verification state.
+ * in `Skin.meshes` — which is also what populates {@link skin}. Until
+ * bound, the clone routes through the rendering path but its vertices
+ * stay at the source's bind-pose values — useful as an intermediate
+ * verification state, and the state in which this mesh bounds itself
+ * exactly like a regular {@link Mesh}.
+ *
+ * A note on which bounds to believe. {@link Mesh#bounding_box} here is
+ * derived from whatever pose the *CPU* can see, and for a character
+ * animated by the pose accumulator that is the rest pose — the joints
+ * are {@link TransformAuthority.GPU} and their `transform_global` is
+ * never advanced. It is the right size and in the right place, and it
+ * is what seeds the scene database's `meshes` row. The deformed world
+ * box, refreshed every frame from the vertices the skinning pass just
+ * moved, is that row — read it from there when the silhouette is what
+ * matters.
  */
 export class SkinnedMesh extends Mesh {
+    /**
+     * The skin whose formula places this mesh's vertices, or `null` while none does.
+     *
+     * Not "is the deformation running" — {@link GPUMeshSkinningContext#unbind} can stop the
+     * skinning pass without this changing, and a mesh whose pass has stopped still holds vertices
+     * the skin put there. So {@link GPUAnimationManager#register_skin} writes it and nothing
+     * clears it: once a skin has taken a mesh over, its formula stays the right basis for
+     * {@link updateBoundsBasic} whether or not a pass runs this frame. Clear it by hand to hand
+     * the mesh back to {@link Mesh}'s composition.
+     *
+     * CPU data throughout (see {@link Skin}). The GPU-side skin *id* is a table row and lives in
+     * {@link GPUMeshSkinningContext}; this does not expose it.
+     *
+     * Nothing refreshes derived state on assignment — set this and the bounds go on describing
+     * the previous basis until {@link updateMatrices} or {@link updateBoundsBasic} runs.
+     *
+     * A clone shares the reference, exactly as {@link Skin#copy} shares its joint and mesh
+     * references: retargeting a cloned character means replacing this alongside the skin's own
+     * arrays, which {@link instantiate_scene_bundle} gets for free by re-registering the
+     * corresponded skin.
+     *
+     * @type {Skin|null}
+     */
+    skin: Skin | null;
     /**
      * @returns {SkinnedMesh}
      */
     clone(): SkinnedMesh;
+    /**
+     * @param {SkinnedMesh} other
+     */
+    copy(other: SkinnedMesh): void;
     /**
      * @readonly
      * @type {boolean}

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

@@ -1 +1 @@
-{"version":3,"file":"SkinnedMesh.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/SkinnedMesh.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH;IAEI;;OAEG;IACH,SAFa,WAAW,CAMvB;IAGL;;;OAGG;IACH,wBAFU,OAAO,CAEkB;CANlC;qBAhDoB,WAAW"}
+{"version":3,"file":"SkinnedMesh.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/SkinnedMesh.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH;IAEI;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAFU,OAAK,IAAI,CAEP;IAEZ;;OAEG;IACH,SAFa,WAAW,CAMvB;IAED;;OAEG;IACH,YAFW,WAAW,QAYrB;IA4CL;;;OAGG;IACH,wBAFU,OAAO,CAEkB;CANlC;qBAnJoB,WAAW"}

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

@@ -1,3 +1,4 @@
+import { compute_skin_world_bounds } from "../animation/compute_skin_world_bounds.js";
 import { Mesh } from "./Mesh.js";
 
 /**
@@ -22,22 +23,65 @@ import { Mesh } from "./Mesh.js";
  * vertex region — leaving every other instance pointed at the source
  * untouched. The skin matrices are computed per the glTF spec formula
  * `inverse(meshNode.worldMatrix) × jointNode.worldMatrix ×
- * inverseBindMatrix` so the SkinnedMesh's own `transform_global` is
- * the natural placement point in the scene graph — moving it (or
- * parenting it) moves the rendered character, exactly like a regular
- * Mesh. The `inverse(meshNode.worldMatrix)` factor is precomputed
- * CPU-side at skin registration; see {@link GPUAnimationManager#register_skin}.
+ * inverseBindMatrix`, and the rasterizer re-applies
+ * `mesh.transform_global` to the result — so the mesh node's own
+ * transform cancels out of the rendered position exactly, which is what
+ * the glTF spec asks for. The leftmost factor is taken live from the
+ * mesh's own transforms row inside {@link shader_meshlet_apply_skinning};
+ * see {@link chunk_skin_blend_mesh_local} for why it goes into each
+ * matrix rather than onto the blended position.
  *
- * The mesh's skin association lives in {@link GPUMeshSkinningContext} —
- * `SkinnedMesh` itself carries no GPU-side state. Bind the mesh to a
- * skin via `gpu_scene.skinning.bind(mesh, skin_id)`, or rely on
+ * The mesh's **skin id** — a row in a GPU table — lives in
+ * {@link GPUMeshSkinningContext} and nowhere else. The CPU-side
+ * {@link Skin} it was registered with is a different thing, pure data
+ * that knows nothing about the GPU, and this mesh holds a reference to
+ * it in {@link skin} so its bounds can be worked out without asking the
+ * GPU anything. Bind the mesh to a skin via
+ * `gpu_scene.skinning.bind(mesh, skin_id)`, or rely on
  * {@link GPUAnimationManager#register_skin} to do it for every entry
- * in `Skin.meshes`. Until bound, the clone routes through the
- * rendering path but its vertices stay at the source's bind-pose
- * values — useful as an intermediate verification state.
+ * in `Skin.meshes` — which is also what populates {@link skin}. Until
+ * bound, the clone routes through the rendering path but its vertices
+ * stay at the source's bind-pose values — useful as an intermediate
+ * verification state, and the state in which this mesh bounds itself
+ * exactly like a regular {@link Mesh}.
+ *
+ * A note on which bounds to believe. {@link Mesh#bounding_box} here is
+ * derived from whatever pose the *CPU* can see, and for a character
+ * animated by the pose accumulator that is the rest pose — the joints
+ * are {@link TransformAuthority.GPU} and their `transform_global` is
+ * never advanced. It is the right size and in the right place, and it
+ * is what seeds the scene database's `meshes` row. The deformed world
+ * box, refreshed every frame from the vertices the skinning pass just
+ * moved, is that row — read it from there when the silhouette is what
+ * matters.
  */
 export class SkinnedMesh extends Mesh {
 
+    /**
+     * The skin whose formula places this mesh's vertices, or `null` while none does.
+     *
+     * Not "is the deformation running" — {@link GPUMeshSkinningContext#unbind} can stop the
+     * skinning pass without this changing, and a mesh whose pass has stopped still holds vertices
+     * the skin put there. So {@link GPUAnimationManager#register_skin} writes it and nothing
+     * clears it: once a skin has taken a mesh over, its formula stays the right basis for
+     * {@link updateBoundsBasic} whether or not a pass runs this frame. Clear it by hand to hand
+     * the mesh back to {@link Mesh}'s composition.
+     *
+     * CPU data throughout (see {@link Skin}). The GPU-side skin *id* is a table row and lives in
+     * {@link GPUMeshSkinningContext}; this does not expose it.
+     *
+     * Nothing refreshes derived state on assignment — set this and the bounds go on describing
+     * the previous basis until {@link updateMatrices} or {@link updateBoundsBasic} runs.
+     *
+     * A clone shares the reference, exactly as {@link Skin#copy} shares its joint and mesh
+     * references: retargeting a cloned character means replacing this alongside the skin's own
+     * arrays, which {@link instantiate_scene_bundle} gets for free by re-registering the
+     * corresponded skin.
+     *
+     * @type {Skin|null}
+     */
+    skin = null;
+
     /**
      * @returns {SkinnedMesh}
      */
@@ -46,6 +90,62 @@ export class SkinnedMesh extends Mesh {
         r.copy(this);
         return r;
     }
+
+    /**
+     * @param {SkinnedMesh} other
+     */
+    copy(other) {
+
+        if (this === other) {
+            // special case
+            return;
+        }
+
+        super.copy(other);
+
+        this.skin = other.skin;
+    }
+
+    /**
+     * World bounds of the deformed mesh, in whatever pose {@link skin}'s joints currently hold.
+     *
+     * `Mesh`'s version puts the rest-pose geometry under `transform_global`, and for a skinned mesh
+     * that is the wrong composition rather than an imprecise one: the renderer *cancels*
+     * `transform_global` out of a skinned vertex's position (see the class docs), so applying it to
+     * the bounds applies a transform the vertices never see. On a glTF character whose root node
+     * carries the file's centimetre→metre scale — the shape every FBX-derived asset has, with
+     * vertex positions in metres and inverse-bind matrices in centimetres — the result is a box
+     * 100× too small, small enough that frustum culling and TLAS extraction see a point where a
+     * character stands.
+     *
+     * So a bound mesh goes through {@link compute_skin_world_bounds}, which composes the bound the
+     * same way the renderer composes the vertex. An unbound one keeps `Mesh`'s composition, because
+     * an unbound clone really is drawn as `transform_global × source vertices`. A skin with no
+     * joints deforms nothing and is treated the same way.
+     *
+     * **Reads the skeleton, so call it when the skeleton is settled.** The joints are outside this
+     * mesh's own subtree — a glTF character's joint root is the mesh node's sibling — and
+     * {@link Node3D#updateMatrices} walks pre-order, so the inherited call this gets mid-walk can
+     * read joints that have not been visited yet and land the mesh where the character was before
+     * the move. That is why {@link GPUSceneContext} re-derives it on the way to writing the
+     * `meshes` row, which is where the value is actually consumed and where every walk is over.
+     */
+    updateBoundsBasic() {
+        const skin = this.skin;
+
+        if (skin === null || skin.joints.length === 0) {
+            super.updateBoundsBasic();
+            return;
+        }
+
+        const geometry = this.geometry;
+
+        compute_skin_world_bounds(
+            skin,
+            geometry.bounding_box, geometry.bounding_sphere,
+            this.bounding_box, this.bounding_sphere
+        );
+    }
 }
 
 /**

package/src/shade/renderer/scene/optimization/geometry/internal/anchor_grow_topological.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"anchor_grow_topological.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/scene/optimization/geometry/internal/anchor_grow_topological.js"],"names":[],"mappings":"AAWA;;;;;;;;;GASG;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAX0B,UAAU;IACV,UAAU;IACJ,UAAU;IACV,UAAU;IACL,6BAA6B,EAAvD,IAAI,MAAM,EAAE,MAAM,CAAC;IACN,WAAW,EAAxB,MAAM;IACO,WAAW,EAAxB,MAAM;IACO,gBAAgB,EAA7B,MAAM;IACQ,cAAc,GAA5B,MAAM;IACJ,UAAU,GAAG,IAAI,CAsI7B;;;;;;;;aAhKa,MAAM,EAAE;;;;aACR,MAAM,EAAE;;;;2BACR,IAAI,MAAM,EAAE,MAAM,CAAC;;;;yBACnB,IAAI,MAAM,EAAE,MAAM,CAAC;;;;eACnB,OAAO,qDAAqD,EAAE,SAAS"}
+{"version":3,"file":"anchor_grow_topological.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/scene/optimization/geometry/internal/anchor_grow_topological.js"],"names":[],"mappings":"AAYA;;;;;;;;;GASG;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAX0B,UAAU;IACV,UAAU;IACJ,UAAU;IACV,UAAU;IACL,6BAA6B,EAAvD,IAAI,MAAM,EAAE,MAAM,CAAC;IACN,WAAW,EAAxB,MAAM;IACO,WAAW,EAAxB,MAAM;IACO,gBAAgB,EAA7B,MAAM;IACQ,cAAc,GAA5B,MAAM;IACJ,UAAU,GAAG,IAAI,CA8I7B;;;;;;;;aAxKa,MAAM,EAAE;;;;aACR,MAAM,EAAE;;;;2BACR,IAAI,MAAM,EAAE,MAAM,CAAC;;;;yBACnB,IAAI,MAAM,EAAE,MAAM,CAAC;;;;eACnB,OAAO,qDAAqD,EAAE,SAAS"}

package/src/shade/renderer/scene/optimization/geometry/internal/anchor_grow_topological.js

@@ -1,9 +1,10 @@
 import { NULL_POINTER } from "../../../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
+import { bt_edge_get } from "../../../../../../core/geom/3d/topology/struct/binary/query/bt_edge_get.js";
+import { bt_edge_other_face } from "../../../../../../core/geom/3d/topology/struct/binary/query/bt_edge_other_face.js";
+import { bt_face_third_vertex } from "../../../../../../core/geom/3d/topology/struct/binary/query/bt_face_third_vertex.js";
 import Vector3 from "../../../../../../core/geom/Vector3.js";
 import { Transform } from "../../../../../../engine/ecs/transform/Transform.js";
 import { StandardAttributes } from "../../../../geometry/StandardAttributes.js";
-import { bt_edge_other_face, bt_face_third_vertex } from "./bt_face_loop_helpers.js";
-import { bt_find_edge_between } from "./bt_find_edge_between.js";
 import { apply_match_transform, match_solve_transform } from "./match_solve_transform.js";
 import { vertex_attribute_pairs, vertex_attributes_match } from "./vertex_attributes_equal.js";
 
@@ -98,6 +99,14 @@ export function anchor_grow_topological(args) {
             continue;
         }
 
+        if (ev1_b === ev2_b) {
+            // Nothing constrains the correspondence to be injective, so an edge of A can arrive with
+            // both of its endpoints mapped onto a single vertex of B. There is no edge to cross
+            // there, and bt_edge_get asked for an edge between a vertex and itself answers with an
+            // arbitrary edge of that vertex's disk rather than with NULL_POINTER.
+            continue;
+        }
+
         // Identify face_a' on the other side of edge_a from any matched face on this edge
         // Find a matched face on this edge
         const loop_a = topology_a.edge_read_loop(edge_a);
@@ -121,7 +130,7 @@ export function anchor_grow_topological(args) {
         if (matched_faces_a.has(face_a_prime)) continue;
 
         // Find edge_b connecting (ev1_b, ev2_b)
-        const edge_b = bt_find_edge_between(topology_b, ev1_b, ev2_b);
+        const edge_b = bt_edge_get(topology_b, ev1_b, ev2_b);
         if (edge_b === NULL_POINTER) continue;
 
         const face_b_inside = f_b_for_a.get(any_matched_face_a);