@woosh/meep-engine 3.23.0 → 3.25.0

package/src/shade/playground/skinned_blas_refit/verify_clone_leaves.js

@@ -1,3 +1,4 @@
+import { geometry_of } from "./place_character.js";
 import { verify_leaf_triangles } from "./verify_leaf_triangles.js";
 
 /**
@@ -68,11 +69,11 @@ function runs_of(values) {
  * @param {object} options
  * @param {Renderer} options.renderer
  * @param {Scene} options.scene
- * @param {SkinnedMesh} options.mesh a mesh whose clone is being deformed
+ * @param {number} options.entity a skinned mesh entity, whose clone is being deformed
  * @param {number} [options.tolerance]
  * @returns {Promise<object>}
  */
-export async function verify_clone_leaves({ renderer, scene, mesh, tolerance = 1e-3 }) {
+export async function verify_clone_leaves({ renderer, scene, entity, tolerance = 1e-3 }) {
     const graphics = renderer.graphics;
     const device = graphics.device;
     const geometries = graphics.geometries;
@@ -80,9 +81,15 @@ export async function verify_clone_leaves({ renderer, scene, mesh, tolerance = 1
 
     const scene_context = renderer.scenes.obtain(scene);
 
-    const geometry_index = scene_context.skinning.obtain_geometry_index(mesh);
+    const clone = scene_context.skinning.clone_of(entity);
 
-    const source_target = blas.get_refit_target(geometries.get_metadata(mesh.geometry));
+    if (clone === undefined) {
+        throw new Error(`entity ${entity} has no clone — is it a skinned mesh entity holding a row?`);
+    }
+
+    const geometry_index = clone.index;
+
+    const source_target = blas.get_refit_target(geometries.get_metadata(geometry_of(scene.dataset, entity)));
 
     if (source_target === undefined) {
         throw new Error('the source geometry has no resident tree');

package/src/shade/playground/skinned_blas_refit/verify_instance_bounds.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify_instance_bounds.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/verify_instance_bounds.js"],"names":[],"mappings":"AAqFA;;;;;;;;;;;GAWG;AACH,qCAJW,UAAU,MAAM,CAAC,UACjB,UAAU,MAAM,CAAC,GACf,MAAM,EAAE,CAqBpB;AAuCD;;;;;;;;;;GAUG;AACH;IAP6B,QAAQ;IACX,KAAK;IACQ,MAAM;IAEjB,SAAS,GAA1B,MAAM;IACJ,QAAQ,MAAM,CAAC,CA4E3B"}
+{"version":3,"file":"verify_instance_bounds.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/verify_instance_bounds.js"],"names":[],"mappings":"AA0FA;;;;;;;;;;;GAWG;AACH,qCAJW,UAAU,MAAM,CAAC,UACjB,UAAU,MAAM,CAAC,GACf,MAAM,EAAE,CAqBpB;AAuCD;;;;;;;;;;GAUG;AACH;IAP6B,QAAQ;IACX,KAAK;IACQ,MAAM;IAEjB,SAAS,GAA1B,MAAM;IACJ,QAAQ,MAAM,CAAC,CAoG3B"}

package/src/shade/playground/skinned_blas_refit/verify_instance_bounds.js

@@ -1,4 +1,9 @@
+import { Name } from "../../../engine/ecs/name/Name.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { ShadedGeometry } from "../../../engine/graphics/ecs/mesh-v2/ShadedGeometry.js";
+import { ShadedGeometryFlags } from "../../../engine/graphics/ecs/mesh-v2/ShadedGeometryFlags.js";
 import { GEOMETRY_METADATA_STRUCT } from "../../renderer/geometry/GEOMETRY_METADATA_STRUCT.js";
+import { row_of_entity } from "../../renderer/scene/rows/GPUSceneRows.js";
 import { align_4 } from "../../../core/binary/align_4.js";
 
 /**
@@ -184,14 +189,38 @@ export async function verify_instance_bounds({ renderer, scene, camera, toleranc
 
     const box_offset = GEOMETRY_METADATA_STRUCT.fields.find(f => f.name === 'bounding_box').offset;
 
-    const rows = [];
+    /**
+     * Every mesh row in the scene, with the matrix the GPU composes it under: the entities that
+     * draw — a character's primitives, and the floor.
+     *
+     * @type {{name: string, skinned: boolean, row: number, world: ArrayLike<number>}[]}
+     */
+    const instances = [];
+
+    const dataset = scene.dataset;
+
+    if (dataset !== null && dataset !== undefined) {
+        dataset.traverseComponents(ShadedGeometry, (geometry, entity) => {
+            if (!scene_context.rows.has_mesh(entity)) {
+                return;
+            }
+
+            const name = dataset.getComponent(entity, Name);
+
+            instances.push({
+                name: name === undefined ? `entity ${entity}` : name.getValue(),
+                skinned: geometry.getFlag(ShadedGeometryFlags.Skinned),
+                row: row_of_entity(entity),
+                world: dataset.getComponent(entity, Transform64).matrix,
+            });
+        });
+    }
 
-    for (const mesh of scene.instances.instances) {
-        const row = scene_context.mesh_row_of(mesh);
 
-        if (row === undefined) {
-            continue;
-        }
+    const rows = [];
+
+    for (const instance of instances) {
+        const row = instance.row;
 
         const record = await scene_context.scene_database.debug_table_read_element('meshes', row);
 
@@ -205,13 +234,13 @@ export async function verify_instance_bounds({ renderer, scene, camera, toleranc
         ))];
 
         // the same matrix `chunk_ray_query_nearest` inverts to put the ray in geometry space
-        const world_box = transformed_box(geometry_box, mesh.transform_global.matrix);
+        const world_box = transformed_box(geometry_box, instance.world);
 
         const error = containment_error(world_box, record.bounding_box);
 
         rows.push({
-            name: mesh.name ?? mesh.constructor.name,
-            skinned: mesh.isSkinnedMesh === true,
+            name: instance.name,
+            skinned: instance.skinned,
             row,
             geometry_index,
             geometry_box: geometry_box.map(v => +v.toFixed(3)),

package/src/shade/playground/skinned_blas_refit/verify_skinned_blas_refit.d.ts

@@ -10,15 +10,15 @@
  * @param {Renderer} options.renderer
  * @param {PerspectiveCamera} options.camera
  * @param {Scene} options.scene
- * @param {SkinnedMesh} options.mesh a mesh whose clone is being deformed
+ * @param {number} options.entity a skinned mesh entity, whose clone is being deformed
  * @param {number} [options.tolerance] relative box disagreement to accept
  * @returns {Promise<object>} the samples and the verdict
  */
-export function verify_skinned_blas_refit({ renderer, camera, scene, mesh, tolerance, }: {
+export function verify_skinned_blas_refit({ renderer, camera, scene, entity, tolerance, }: {
     renderer: Renderer;
     camera: PerspectiveCamera;
     scene: Scene;
-    mesh: SkinnedMesh;
+    entity: number;
     tolerance?: number;
 }): Promise<object>;
 /**

package/src/shade/playground/skinned_blas_refit/verify_skinned_blas_refit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify_skinned_blas_refit.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/verify_skinned_blas_refit.js"],"names":[],"mappings":"AA4JA;;;;;;;;;;;;;;;GAeG;AACH;IAP6B,QAAQ;IACC,MAAM;IAClB,KAAK;IACC,IAAI;IACR,SAAS,GAA1B,MAAM;IACJ,QAAQ,MAAM,CAAC,CAkF3B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAJ6B,QAAQ;IACD,QAAQ;IAC/B,QAAQ,MAAM,CAAC,CA8F3B"}
+{"version":3,"file":"verify_skinned_blas_refit.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/verify_skinned_blas_refit.js"],"names":[],"mappings":"AA6JA;;;;;;;;;;;;;;;GAeG;AACH;IAP6B,QAAQ;IACC,MAAM;IAClB,KAAK;IACJ,MAAM,EAAtB,MAAM;IACW,SAAS,GAA1B,MAAM;IACJ,QAAQ,MAAM,CAAC,CAoF3B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAJ6B,QAAQ;IACD,QAAQ;IAC/B,QAAQ,MAAM,CAAC,CA8F3B"}

package/src/shade/playground/skinned_blas_refit/verify_skinned_blas_refit.js

@@ -10,6 +10,7 @@ import { bvh2_check_containment } from "../../renderer/geometry/bvh/bvh2_check_b
 import { GPUBLASRefitBatch } from "../../renderer/geometry/bvh/GPUBLASRefitBatch.js";
 import { BVH2_NODE_STRUCT } from "../../renderer/shader/chunk/bvh/BVH2_NODE_STRUCT.js";
 import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
+import { geometry_of } from "./place_character.js";
 
 /**
  * @type {number}
@@ -166,7 +167,7 @@ async function advance(renderer, camera, scene, frames, dt = 1 / 60) {
  * @param {Renderer} options.renderer
  * @param {PerspectiveCamera} options.camera
  * @param {Scene} options.scene
- * @param {SkinnedMesh} options.mesh a mesh whose clone is being deformed
+ * @param {number} options.entity a skinned mesh entity, whose clone is being deformed
  * @param {number} [options.tolerance] relative box disagreement to accept
  * @returns {Promise<object>} the samples and the verdict
  */
@@ -174,7 +175,7 @@ export async function verify_skinned_blas_refit({
                                                     renderer,
                                                     camera,
                                                     scene,
-                                                    mesh,
+                                                    entity,
                                                     tolerance = 1e-3,
                                                 }) {
     const graphics = renderer.graphics;
@@ -187,12 +188,14 @@ export async function verify_skinned_blas_refit({
     // settle: the first frames register the clone, upload its tree and run the first refit
     await advance(renderer, camera, scene, 8);
 
-    const geometry_index = scene_context.skinning.obtain_geometry_index(mesh);
+    const clone = scene_context.skinning.clone_of(entity);
 
-    if (geometry_index === undefined) {
-        throw new Error('the mesh has no clone — is it a SkinnedMesh, bound to a skin, and in the scene?');
+    if (clone === undefined) {
+        throw new Error(`entity ${entity} has no clone — is it a skinned mesh entity holding a row?`);
     }
 
+    const geometry_index = clone.index;
+
     const address = new Uint32Array(
         await read_back(device, geometries.blas.buffer_metadata, geometry_index * 4, 4)
     )[0];
@@ -217,7 +220,7 @@ export async function verify_skinned_blas_refit({
         device,
         geometries.blas.buffer_data,
         address * BVH2_NODE_STRUCT.size,
-        (mesh.geometry.bvh.byteLength / BVH2_NODE_STRUCT.size | 0) * BVH2_NODE_STRUCT.size
+        (geometry_of(scene.dataset, entity).bvh.byteLength / BVH2_NODE_STRUCT.size | 0) * BVH2_NODE_STRUCT.size
     );
 
     // the same checker the spec asserts with, so the browser tier and CI ask one question

package/src/shade/playground/skinned_blas_refit/verify_traversal_reachability.d.ts

@@ -2,15 +2,15 @@
  * @param {object} options
  * @param {Renderer} options.renderer
  * @param {PerspectiveCamera} options.camera whose position the rays start from
- * @param {Mesh} options.mesh the instance whose transform puts the camera into geometry space
+ * @param {Transform64} options.world the instance's world transform, which puts the camera into geometry space
  * @param {object} options.target refit target of the tree to audit
  * @param {number} options.geometry_index
  * @returns {Promise<object>}
  */
-export function verify_traversal_reachability({ renderer, camera, mesh, target, geometry_index, }: {
+export function verify_traversal_reachability({ renderer, camera, world, target, geometry_index, }: {
     renderer: Renderer;
     camera: PerspectiveCamera;
-    mesh: Mesh;
+    world: Transform64;
     target: object;
     geometry_index: number;
 }): Promise<object>;

package/src/shade/playground/skinned_blas_refit/verify_traversal_reachability.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify_traversal_reachability.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/verify_traversal_reachability.js"],"names":[],"mappings":"AAoHA;;;;;;;;GAQG;AACH;IAP6B,QAAQ;IACC,MAAM;IACnB,IAAI;IACF,MAAM,EAAtB,MAAM;IACU,cAAc,EAA9B,MAAM;IACJ,QAAQ,MAAM,CAAC,CA6H3B"}
+{"version":3,"file":"verify_traversal_reachability.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/verify_traversal_reachability.js"],"names":[],"mappings":"AAoHA;;;;;;;;GAQG;AACH;IAP6B,QAAQ;IACC,MAAM;IACZ,KAAK;IACV,MAAM,EAAtB,MAAM;IACU,cAAc,EAA9B,MAAM;IACJ,QAAQ,MAAM,CAAC,CA6H3B"}

package/src/shade/playground/skinned_blas_refit/verify_traversal_reachability.js

@@ -118,7 +118,7 @@ function inverse_transform_point(m, point) {
  * @param {object} options
  * @param {Renderer} options.renderer
  * @param {PerspectiveCamera} options.camera whose position the rays start from
- * @param {Mesh} options.mesh the instance whose transform puts the camera into geometry space
+ * @param {Transform64} options.world the instance's world transform, which puts the camera into geometry space
  * @param {object} options.target refit target of the tree to audit
  * @param {number} options.geometry_index
  * @returns {Promise<object>}
@@ -126,7 +126,7 @@ function inverse_transform_point(m, point) {
 export async function verify_traversal_reachability({
                                                         renderer,
                                                         camera,
-                                                        mesh,
+                                                        world,
                                                         target,
                                                         geometry_index,
                                                     }) {
@@ -140,7 +140,7 @@ export async function verify_traversal_reachability({
     const { leaf_count, node_word_offset, leaf_nodes_offset } = target;
 
     const origin = inverse_transform_point(
-        mesh.transform_global.matrix,
+        world,
         [...camera.transform.translation]
     );
 

package/src/shade/playground/skinned_mesh_soup/README.md

@@ -75,7 +75,7 @@ picture are consistent.
 
 `renderer/animation/SKINNING_FRAME_PLAN.md`. The short version: glTF says a skinned mesh's node
 transform is ignored, so the frame is not the asset's to choose — it is the engine's.
-`register_skin` now sets it to the skin's own bind transform (`skin_normalize_mesh_frame`), which
+compiling the model now sets it to the skin's own bind transform (`prefab_normalize_skin_frames`), which
 makes the fold the identity at bind and a rigid displacement under a clip, for **both** shapes a
 glTF file arrives in. One matrix per skin, once, at registration. No shader change and no
 per-vertex cost, and a file that was already right is not touched.
@@ -110,8 +110,8 @@ So the modes now read the other way round:
 
 ## The switches
 
-- **`?skin=off`** — no skin registered. A `SkinnedMesh` still gets a vertex clone
-  (`GPUMeshSkinningContext#obtain_geometry_index` allocates one for every skinned mesh), but nothing
+- **`?skin=off`** — no skin registered. A skinned mesh entity still gets a vertex clone
+  (`GPUMeshSkinningContext#obtain_clone` allocates one when its mesh row is written), but nothing
   deforms it, so what is drawn is the memcpy of the source: the rest pose under the mesh node's own
   transform. For Michelle a *correct* result is a 1.7 cm figure on her side. Soup here would be the
   geometry upload — the meshlet copy or its address patch — and nothing to do with skinning.
@@ -132,9 +132,9 @@ So the modes now read the other way round:
 
 `skinned_blas_refit` calls `load_gltf` directly and parses the file once per character. The asset
 loader is what the game and the editor register, and it hands out **the same bundle** to every
-caller — so a second character is not a second parse, it is `instantiate_scene_bundle`: its own node
-tree, its own skins bound to that tree's joints, its own clips retargeted onto it, sharing the
-geometry and the inverse-bind matrices. Running the repro on that path is what makes a fix found
+caller — so a second character is not a second parse, it is `prefab_instantiate`: its own
+entities, its own skins bound to those entities' joints, its own clips retargeted onto them, sharing
+the geometry and the inverse-bind matrices. Running the repro on that path is what makes a fix found
 here a fix for the engine rather than for one prototype page.
 
 ## Assets

package/src/shade/playground/skinned_mesh_soup/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_mesh_soup/main.js"],"names":[],"mappings":"AAiQA;;;;GAIG;AACH,yBAFa,QAAQ,IAAI,CAAC,CAkTzB"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_mesh_soup/main.js"],"names":[],"mappings":"AAsMA;;;;GAIG;AACH,yBAFa,QAAQ,IAAI,CAAC,CAmTzB"}

package/src/shade/playground/skinned_mesh_soup/main.js

@@ -9,17 +9,20 @@ import {
 } from "../../../engine/asset/loaders/GLTFSceneBundleAssetLoader.js";
 import { ImageBitmapAssetLoader } from "../../../engine/asset/loaders/image/ImageBitmapAssetLoader.js";
 import { load_model_scene_bundle } from "../../../engine/asset/load_model_scene_bundle.js";
-import { instantiate_scene_bundle } from "../../../engine/graphics3/instantiate_scene_bundle.js";
+import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
+import { prefab_compile } from "../../../engine/graphics3/prefab/prefab_compile.js";
 import { AnimationClipFlags } from "../../renderer/animation/AnimationClipFlags.js";
 import { camera_frame_sphere } from "../../renderer/camera/camera_frame_sphere.js";
 import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraController.js";
 import { PerspectiveCamera } from "../../renderer/camera/PerspectiveCamera.js";
 import { create_frame_loop } from "../../renderer/create_frame_loop.js";
 import { make_sunlight } from "../../renderer/light/make_sunlight.js";
+import { place_light } from "../../renderer/light/place_light.js";
 import { Renderer } from "../../renderer/Renderer.js";
-import { Node3D } from "../../renderer/scene/Node3D.js";
+import { row_of_entity } from "../../renderer/scene/rows/GPUSceneRows.js";
 import { Scene } from "../../renderer/scene/Scene.js";
 import { load_default_environment } from "../load_default_environment.js";
+import { grid_position, place_character } from "../skinned_blas_refit/place_character.js";
 
 /**
  * A skinned character, loaded the way the game loads one, with the pieces that could be making soup
@@ -37,12 +40,11 @@ import { load_default_environment } from "../load_default_environment.js";
  *
  * This page is that other question, and it is built to bisect it rather than to look good:
  *
- * - **`?skin=off`** — no skin registered. A {@link SkinnedMesh} still gets a vertex clone (see
- *   {@link GPUMeshSkinningContext#obtain_geometry_index}), but nothing ever deforms it, so what is
- *   drawn is the memcpy of the source: the rest pose, under the mesh node's own transform. For a
- *   Mixamo character that transform carries the file's centimetre scale and its up-axis rotation,
- *   so a *correct* result here is a 1.7 cm figure lying on its side. Soup here is the geometry
- *   upload — the meshlet copy or its address patch — and has nothing to do with skinning.
+ * - **`?skin=off`** — no skin registered. A skinned mesh entity still gets a vertex clone (see
+ *   {@link GPUMeshSkinningContext#obtain_clone}), but nothing ever deforms it, so what is drawn is
+ *   the memcpy of the source: the rest pose, under the mesh entity's row — which the prefab put
+ *   into the skin's own frame. Soup here is the geometry upload — the meshlet copy or its address
+ *   patch — and has nothing to do with skinning.
  * - **`?skin=bind`** — the skin registered, no clip. The skinning pass runs every frame over a pose
  *   that never changes, and the answer it should write is one the CPU knows exactly. `diagnose()`
  *   in the console reads the clone's vertices back and says which of them are wrong and in what
@@ -61,9 +63,10 @@ import { load_default_environment } from "../load_default_environment.js";
  * differently per joint, which is what tore the mesh apart. `?skin=bind` was the right character at
  * 1/100 size (one shared matrix, one shared error) and `?skin=animated` was soup.
  *
- * The frame is now the engine's rather than the asset's: `register_skin` puts each skinned mesh on
- * its skin's own bind transform, so the fold is the identity at bind and a rigid displacement under
- * a clip, for every shape a glTF file arrives in. See `renderer/animation/SKINNING_FRAME_PLAN.md`.
+ * The frame is now the engine's rather than the asset's: compiling a model puts each skinned mesh
+ * on its skin's own bind transform, so the fold is the identity at bind and a rigid displacement
+ * under a clip, for every shape a glTF file arrives in. See
+ * `renderer/animation/SKINNING_FRAME_PLAN.md`.
  *
  * All of which was established without a device — `__soup_blend_probe.spec.js` runs the shader's own
  * blend over this character's own matrices, and the emulator tier in
@@ -75,8 +78,9 @@ import { load_default_environment } from "../load_default_environment.js";
  * `skinned_blas_refit` calls `load_gltf` directly and parses the file once per character.
  * {@link GLTFSceneBundleAssetLoader} is what the game and the editor register, and it hands **the
  * same bundle** to every caller — so a second character is not a second parse, it is
- * {@link instantiate_scene_bundle}: its own node tree, its own skins bound to that tree's joints,
- * its own clips retargeted onto it, sharing the geometry and the inverse-bind matrices. That is a
+ * `prefab_instantiate` over the prefab compiled from it once: its own entities, its own skins bound
+ * to those entities' joints, its own clips retargeted onto them, sharing the geometry and the
+ * inverse-bind matrices. That is a
  * materially different path into the renderer, and running the repro on it means a fix found here
  * is a fix for the engine rather than for one prototype page.
  *
@@ -148,75 +152,13 @@ async function make_asset_manager() {
 }
 
 /**
- * Where the `index`-th of `count` characters stands: a square-ish grid centred on the origin.
+ * Every skinned mesh entity an instance's skins deform.
  *
- * @param {number} index
- * @param {number} count
- * @param {number} spacing
- * @returns {{x: number, z: number}}
- */
-function grid_position(index, count, spacing) {
-    const columns = Math.ceil(Math.sqrt(count));
-    const rows = Math.ceil(count / columns);
-
-    return {
-        x: ((index % columns) - (columns - 1) / 2) * spacing,
-        z: (Math.floor(index / columns) - (rows - 1) / 2) * spacing,
-    };
-}
-
-/**
- * Stand one instantiated character at `(x, 0, z)`.
- *
- * The offset goes on a fresh parent above the model's own roots, and on that parent's **local**
- * transform. Both halves of that matter and neither is obvious; `place_character` in
- * `skinned_blas_refit` carries the full argument, which is worth reading once. The short form: a
- * skinned mesh's own node transform cancels exactly out of the vertex the renderer draws, so a
- * skinned character is placed by its *joints* and only an ancestor the joints actually sit under
- * moves them — and `transform_global` is derived, so a placement written there is discarded by the
- * next walk that recomputes it.
- *
- * @param {Scene} scene
- * @param {Node3D[]} roots the instance's roots, not yet parented
- * @param {number} x
- * @param {number} z
- * @returns {Node3D} the placement node
- */
-function place_roots(scene, roots, x, z) {
-    const placement = new Node3D();
-
-    placement.name = `placement(${x}, ${z})`;
-
-    // `Transform64` keeps its matrix by hand: the write is only real after `updateMatrix`.
-    placement.transform_local.setTranslation(x, 0, z);
-    placement.transform_local.updateMatrix();
-
-    placement.addChildren(roots);
-
-    placement.updateMatrices();
-
-    // `updateMatrices` walks pre-order and a glTF character's joint root is the mesh node's
-    // sibling, so the bounds a SkinnedMesh refreshes mid-walk read joints the walk has not reached.
-    // This second pass reads a settled skeleton.
-    placement.traverse(node => {
-        if (node.isMesh === true) {
-            node.updateBoundsBasic();
-        }
-    });
-
-    scene.add(placement);
-
-    return placement;
-}
-
-/**
- * Every {@link SkinnedMesh} an instance's skins deform.
+ * Off the skins rather than by walking the entities: a skin already lists exactly the meshes that
+ * bind to it, which is what `register_skin` uses.
  *
- * Off the skins rather than by walking the roots: a skin already lists exactly the meshes that bind
- * to it, which is what `register_skin` uses.
- *
- * @param {SceneBundleInstance} instance
- * @returns {SkinnedMesh[]}
+ * @param {PrefabInstance} instance
+ * @returns {number[]}
  */
 function skinned_meshes_of(instance) {
     const meshes = new Set();
@@ -234,16 +176,15 @@ function skinned_meshes_of(instance) {
  * The world-space box the renderer culls and traces this mesh by — the `meshes` table row, which
  * the skinning pass's bounds-refresh chain rewrites every frame from the vertices it just moved.
  *
- * Not `mesh.bounding_box`: that is the CPU box of the *source* geometry under the mesh transform,
- * and for a character whose node carries a centimetre scale it is a box a couple of centimetres
- * across. Framing a camera on that puts the camera inside the character.
+ * Not the source geometry's box under the mesh entity's transform: that is the rest pose, and
+ * the dance has moved on from it.
  *
  * @param {GPUSceneContext} scene_context
- * @param {Mesh} mesh
+ * @param {number} entity a mesh entity
  * @returns {Promise<{low: Vector3, high: Vector3}>}
  */
-async function world_bounds_of(scene_context, mesh) {
-    const row = scene_context.mesh_row_of(mesh);
+async function world_bounds_of(scene_context, entity) {
+    const row = row_of_entity(entity);
 
     const record = await scene_context.scene_database.debug_table_read_element('meshes', row);
 
@@ -346,6 +287,11 @@ export async function start() {
 
     const scene = new Scene();
 
+    // the characters are entities, and the scene's rows are theirs
+    const dataset = new EntityComponentDataset();
+
+    scene.dataset = dataset;
+
     // document.body rather than the canvas: the controller starts a keyboard device, and only a
     // focusable element receives key events — body carries tabindex for exactly that.
     const controller = new OrbitalCameraController(camera, document.body);
@@ -371,20 +317,26 @@ export async function start() {
 
     const scene_context = renderer.scenes.obtain(scene);
 
-    /** @type {SkinnedMesh[]} */
+    /** @type {number[]} the skinned mesh entities */
     const characters = [];
 
     try {
         const asset_manager = await make_asset_manager();
 
-        // One load, whatever the count: the asset hands out the model itself, and a placement's
-        // private copy is `instantiate_scene_bundle`.
+        // One load and one compile, whatever the count: the asset hands out the model itself, and
+        // a placement is `prefab_instantiate` over the prefab compiled from it.
         const bundle = await load_model_scene_bundle(asset_manager, CHARACTER_URL);
 
+        const prefab = prefab_compile(bundle);
+
         const animations = scene_context.animation_manager;
 
         for (let i = 0; i < count; i++) {
-            const instance = instantiate_scene_bundle(bundle);
+            const { x, z } = grid_position(i, count, SPACING);
+
+            const { instance } = place_character(scene_context, dataset, prefab, x, z, {
+                register_animation: skin_mode !== SkinMode.Off,
+            });
 
             const meshes = skinned_meshes_of(instance);
 
@@ -392,16 +344,6 @@ export async function start() {
                 throw new Error(`${CHARACTER_URL} has no skinned mesh`);
             }
 
-            const { x, z } = grid_position(i, count, SPACING);
-
-            place_roots(scene, instance.roots, x, z);
-
-            if (skin_mode !== SkinMode.Off) {
-                for (const skin of instance.skins) {
-                    animations.register_skin(skin);
-                }
-            }
-
             if (skin_mode === SkinMode.Animated) {
                 // One clip, looping, at full weight. The pose accumulator sums every *bound* clip
                 // whatever its weight, so binding the T-pose alongside the dance would blend the
@@ -432,7 +374,7 @@ export async function start() {
 
     if (!scene.lights.elements.some(light => light.isDirectionalLight)) {
         // a glTF character carries no light of its own
-        scene.lights.add(make_sunlight({ intensity: 6 }));
+        place_light(scene, make_sunlight({ intensity: 6 }));
     }
 
     // ---- frames enough for the box to be worth framing on ----------------------------------------
@@ -512,7 +454,7 @@ export async function start() {
         animating = false;
 
         try {
-            return await verify_clone_vertices({ renderer, scene, mesh: characters[0] });
+            return await verify_clone_vertices({ renderer, scene, entity: characters[0] });
         } finally {
             animating = was_animating;
         }

package/src/shade/playground/skinned_mesh_soup/verify_clone_vertices.d.ts

@@ -9,9 +9,9 @@
  * @param {object} options
  * @param {Renderer} options.renderer
  * @param {Scene} options.scene
- * @param {SkinnedMesh} options.mesh
- * @param {number} [options.tolerance] in mesh-local units. Since `register_skin` puts the mesh on
- *        the skin's bind transform, mesh-local *is* world scale — a metre is a metre here, and at
+ * @param {number} options.entity a skinned mesh entity
+ * @param {number} [options.tolerance] in mesh-local units. Since compiling the model puts the mesh
+ *        on the skin's bind transform, mesh-local *is* world scale — a metre is a metre here, and at
  *        bind the clone should hold the source's own positions. `1e-4` is f32 headroom over a
  *        chain — a matrix product, a quaternion conversion and a screw motion, all at single
  *        precision — against a smallest real violation of `1.6`, so there are four orders between
@@ -20,10 +20,10 @@
  *        the CPU now reads zero at bind.
  * @returns {Promise<object>}
  */
-export function verify_clone_vertices({ renderer, scene, mesh, tolerance }: {
+export function verify_clone_vertices({ renderer, scene, entity, tolerance }: {
     renderer: Renderer;
     scene: Scene;
-    mesh: SkinnedMesh;
+    entity: number;
     tolerance?: number;
 }): Promise<object>;
 //# sourceMappingURL=verify_clone_vertices.d.ts.map

package/src/shade/playground/skinned_mesh_soup/verify_clone_vertices.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify_clone_vertices.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_mesh_soup/verify_clone_vertices.js"],"names":[],"mappings":"AAyJA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAb6B,QAAQ;IACX,KAAK;IACC,IAAI;IACR,SAAS,GAA1B,MAAM;IAQJ,QAAQ,MAAM,CAAC,CA8P3B"}
+{"version":3,"file":"verify_clone_vertices.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_mesh_soup/verify_clone_vertices.js"],"names":[],"mappings":"AA0JA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAb6B,QAAQ;IACX,KAAK;IACJ,MAAM,EAAtB,MAAM;IACW,SAAS,GAA1B,MAAM;IAQJ,QAAQ,MAAM,CAAC,CAsQ3B"}