@woosh/meep-engine 3.23.0 → 3.24.0

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

@@ -9,13 +9,17 @@ import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraCont
 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 { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
+import { prefab_compile } from "../../../engine/graphics3/prefab/prefab_compile.js";
 import { load_gltf } from "../../renderer/loader/gltf/load_gltf.js";
+import { row_of_entity } from "../../renderer/scene/rows/GPUSceneRows.js";
 import { Renderer } from "../../renderer/Renderer.js";
 import { Scene } from "../../renderer/scene/Scene.js";
 import { load_default_environment } from "../load_default_environment.js";
 import { make_playground_asset_manager } from "../make_playground_asset_manager.js";
 import { add_floor } from "./add_floor.js";
-import { grid_position, place_character } from "./place_character.js";
+import { geometry_of, grid_position, place_character } from "./place_character.js";
 
 /**
  * A dancing character under the path tracer — the browser tier for the per-frame BLAS refit.
@@ -157,19 +161,19 @@ class FrameTimer {
 }
 
 /**
- * Every {@link SkinnedMesh} a bundle's skins deform.
+ * Every skinned mesh entity an instance's skins deform.
  *
- * Off the skins rather than by walking the scene roots: a skin already lists exactly the meshes
- * that bind to it, which is what `register_skin` uses, so this cannot disagree with what actually
- * gets deformed.
+ * 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, so this cannot disagree with what actually gets
+ * deformed.
  *
- * @param {SceneBundle} bundle
- * @returns {SkinnedMesh[]}
+ * @param {PrefabInstance} instance
+ * @returns {number[]}
  */
-function skinned_meshes_of(bundle) {
+function skinned_meshes_of(instance) {
     const meshes = new Set();
 
-    for (const skin of bundle.skins) {
+    for (const skin of instance.skins) {
         for (const mesh of skin.meshes) {
             meshes.add(mesh);
         }
@@ -179,47 +183,39 @@ function skinned_meshes_of(bundle) {
 }
 
 /**
- * Load one dancer, place it, and set it going.
+ * Spawn one dancer, place it, and set it going.
  *
- * A whole load per dancer rather than one load and N instances: a second dancer needs a second
- * joint hierarchy to pose, and those are scene nodes. The asset framework caches the bytes, so the
- * repeat is parse work rather than transfer.
+ * One prefab and N instances: a second dancer is a second set of entities under a second placement,
+ * sharing the geometry, the inverse-bind matrices and the curves with the first.
  *
- * @param {Scene} scene
  * @param {GPUSceneContext} scene_context
- * @param {AssetManager} asset_manager
+ * @param {EntityComponentDataset} dataset
+ * @param {Prefab} prefab the character, compiled once
  * @param {number} index which dancer this is, used to place it
  * @param {number} count how many there are in total
- * @returns {Promise<SkinnedMesh[]>}
+ * @returns {number[]} the dancer's skinned mesh entities
  */
-async function add_dancer(scene, scene_context, asset_manager, index, count) {
-    const bundle = await load_gltf(CHARACTER_URL, { assetManager: asset_manager });
+function add_dancer(scene_context, dataset, prefab, index, count) {
+    // A grid, centred on the origin. The offset is the placement entity's whole transform, above
+    // the character's own root: the joints are entities whose rows compose under it, and they are
+    // what has to move. See `place_character`.
+    const { x, z } = grid_position(index, count, SPACING);
+
+    const { instance } = place_character(scene_context, dataset, prefab, x, z);
 
-    const meshes = skinned_meshes_of(bundle);
+    const meshes = skinned_meshes_of(instance);
 
     if (meshes.length === 0) {
         throw new Error(`${CHARACTER_URL} has no skinned mesh — nothing here has a BLAS to refit`);
     }
 
-    // A grid, centred on the origin. The offset goes on a fresh parent above the character's own
-    // roots rather than on the mesh node: a skinned mesh's own transform cancels out of both the
-    // vertex the renderer draws and the box it publishes, so the joints are what has to move. See
-    // `place_character`.
-    const { x, z } = grid_position(index, count, SPACING);
-
-    place_character(scene, bundle, x, z);
-
     const animations = scene_context.animation_manager;
 
-    for (const skin of bundle.skins) {
-        animations.register_skin(skin);
-    }
-
     // 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 two rather than leave the
     // dance alone — only what should play is registered.
-    const clip = bundle.clips.find(candidate => /samba|dance/i.test(candidate.name ?? ''))
-        ?? bundle.clips[0];
+    const clip = instance.clips.find(candidate => /samba|dance/i.test(candidate.name ?? ''))
+        ?? instance.clips[0];
 
     if (clip !== undefined) {
         const clip_id = animations.register_clip(clip);
@@ -246,11 +242,11 @@ async function add_dancer(scene, scene_context, asset_manager, index, count) {
  * is worth nothing before a few frames have gone by.
  *
  * @param {GPUSceneContext} scene_context
- * @param {Mesh} mesh
+ * @param {number} entity a mesh entity
  * @returns {Promise<{low: Vector3, high: Vector3, radius: number}>}
  */
-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);
 
@@ -316,6 +312,11 @@ export async function start() {
 
     const scene = new Scene();
 
+    // the dancers 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 can receive key events — body carries tabindex for exactly that.
     const controller = new OrbitalCameraController(camera, document.body);
@@ -333,7 +334,7 @@ export async function start() {
     globalThis.verify = async () => paused(async () => {
         const { verify_skinned_blas_refit } = await import('./verify_skinned_blas_refit.js');
 
-        return verify_skinned_blas_refit({ renderer, camera, scene, mesh: globalThis.dancers[0] });
+        return verify_skinned_blas_refit({ renderer, camera, scene, entity: globalThis.dancers[0] });
     });
 
     // The half `verify()` is blind to: whether each leaf's box belongs to the triangle that leaf
@@ -343,7 +344,7 @@ export async function start() {
     globalThis.verify_leaves = async () => {
         const { verify_leaf_correspondence } = await import('./verify_skinned_blas_refit.js');
 
-        return verify_leaf_correspondence({ renderer, geometry: globalThis.dancers[0].geometry });
+        return verify_leaf_correspondence({ renderer, geometry: geometry_of(dataset, globalThis.dancers[0]) });
     };
 
     // The same question of the *clone*, live: after the frame's refit, does every leaf of the
@@ -352,7 +353,7 @@ export async function start() {
     globalThis.verify_clone_leaves = async () => paused(async () => {
         const { verify_clone_leaves } = await import('./verify_clone_leaves.js');
 
-        return verify_clone_leaves({ renderer, scene, mesh: globalThis.dancers[0] });
+        return verify_clone_leaves({ renderer, scene, entity: globalThis.dancers[0] });
     });
 
     const frame_timer = new FrameTimer();
@@ -488,29 +489,36 @@ export async function start() {
 
     const scene_context = renderer.scenes.obtain(scene);
 
-    /** @type {SkinnedMesh[]} */
+    /** @type {number[]} the skinned mesh entities */
     const dancers = [];
 
     /**
-     * Where the load's time goes, for the console: one parse per dancer — the glTF decoded, its
-     * meshlets built and compressed, its BLAS built on the CPU, every time — then the first frames
-     * that upload every clone and tree, then one bounds readback per dancer.
+     * Where the load's time goes, for the console: one parse — the glTF decoded, its meshlets built
+     * and compressed, its BLAS built on the CPU — and one compile into a prefab, then a spawn per
+     * dancer, then the first frames that upload every clone and tree, then one bounds readback per
+     * dancer.
      */
-    const load_timing = { parses: [], first_frames_ms: 0, bounds_ms: 0 };
+    const load_timing = { parse_ms: 0, spawns: [], first_frames_ms: 0, bounds_ms: 0 };
 
     try {
         const asset_manager = await make_playground_asset_manager();
 
-        for (let i = 0; i < count; i++) {
-            // One parse per dancer, in sequence: at a few hundred this is the better part of a
-            // minute, and a status that does not move looks like a page that has stopped.
-            set_status(`loading ${i + 1} / ${count} × ${CHARACTER_URL} …`);
+        const parse_started = performance.now();
+
+        const bundle = await load_gltf(CHARACTER_URL, { assetManager: asset_manager });
+
+        const prefab = prefab_compile(bundle);
 
+        load_timing.parse_ms = performance.now() - parse_started;
+
+        set_status(`spawning ${count} × ${CHARACTER_URL} …`);
+
+        for (let i = 0; i < count; i++) {
             const started = performance.now();
 
-            dancers.push(...await add_dancer(scene, scene_context, asset_manager, i, count));
+            dancers.push(...add_dancer(scene_context, dataset, prefab, i, count));
 
-            load_timing.parses.push(performance.now() - started);
+            load_timing.spawns.push(performance.now() - started);
         }
     } catch (error) {
         set_status(
@@ -524,7 +532,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 skinning to run and its bounds-refresh chain to publish a deformed box,
@@ -565,20 +573,21 @@ export async function start() {
     load_timing.bounds_ms = performance.now() - bounds_started;
 
     {
-        const parses = load_timing.parses;
-        const total = parses.reduce((sum, ms) => sum + ms, 0);
+        const spawns = load_timing.spawns;
+        const total = spawns.reduce((sum, ms) => sum + ms, 0);
 
         console.log(
-            `load: ${parses.length} parses in ${(total / 1000).toFixed(1)} s `
-            + `(mean ${(total / parses.length).toFixed(0)} ms, max ${Math.max(...parses).toFixed(0)} ms, `
-            + `first ${parses[0].toFixed(0)} ms) · first frames ${(load_timing.first_frames_ms / 1000).toFixed(1)} s `
+            `load: parse + compile ${load_timing.parse_ms.toFixed(0)} ms · ${spawns.length} spawns in `
+            + `${total.toFixed(0)} ms (mean ${(total / spawns.length).toFixed(2)} ms, max `
+            + `${Math.max(...spawns).toFixed(2)} ms, first ${spawns[0].toFixed(2)} ms) `
+            + `· first frames ${(load_timing.first_frames_ms / 1000).toFixed(1)} s `
             + `· bounds readback ${(load_timing.bounds_ms / 1000).toFixed(1)} s`
         );
     }
 
     const span = new Vector3(high.x - low.x, high.y - low.y, high.z - low.z);
 
-    globalThis.floor = add_floor(scene, Math.max(span.x, span.z) * 6, low.y);
+    globalThis.floor = add_floor(scene_context, Math.max(span.x, span.z) * 6, low.y);
 
     const radius = Math.hypot(span.x, span.y, span.z) * 0.5;
 
@@ -605,7 +614,7 @@ export async function start() {
 
     globalThis.dancers = dancers;
 
-    set_status(`loaded — ${count} dancing, ${scene.instances.instances.length} instances`, 'pass');
+    set_status(`loaded — ${count} dancing, ${dancers.length} skinned meshes`, 'pass');
 
     renderer.indicate_view_change();
 

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

@@ -1,66 +1,53 @@
 /**
- * Stand one loaded character on the floor at `(x, 0, z)`.
+ * Stand one character on the floor at `(x, 0, z)`, the way the engine stands one: as entities.
  *
- * ## Why the mesh node is not the placement point
+ * ## What a placed character is
  *
- * It is tempting, and it is what this page used to do: the mesh is the visible thing, so move the
- * mesh. For a {@link SkinnedMesh} that is a no-op, and the reason is the glTF skinning formula
- * itself. A skinned vertex lands at
+ * A prefab instance under a placement entity. The placement's `Transform64` is the offset and
+ * nothing else; every node the file had is an entity below it, holding its own offset from its
+ * parent in a `TransformAttachment`, and the file's own transform — the centimetre scale and the
+ * up-axis rotation an FBX-derived glTF carries on its root — stays where the prefab put it, on the
+ * entity that stands for that root. "Compose, do not replace": a `Transform64` composes as
+ * `T · R · S`, so a translation written into the file's root would not be the world offset but one
+ * the rotation and scale then act on.
  *
- * ```
- * mesh.global × inverse(mesh.global) × joint.global × inverse_bind × v
- * ```
+ * ## Where the GPU reads it
  *
- * — `chunk_skin_blend_mesh_local` folds the leftmost inverse into each joint matrix and the
- * rasterizer re-applies `mesh.global` afterwards, so the mesh node's own transform **cancels
- * exactly** and the vertex is at `joint.global × inverse_bind × v`. `compute_skin_world_bounds`
- * composes the published box the same way and does not read the mesh node either. So a skinned
- * character is placed by its **joints**, and the only thing that moves them is an ancestor they
- * actually sit under.
+ * Every entity of the instance holds a row of the `transforms` table, at `entity + 1`, and the
+ * hierarchy pass composes each row's `global` from its offset and its parent's row — so the joints
+ * the pose accumulator drives are carried by the placement without anyone writing to them. The
+ * primitives hold a row of the `meshes` table too, over a clone of their geometry when the mesh is
+ * skinned, which is the region the skinning pass deforms and the BLAS refit follows.
  *
- * Michelle is the shape that makes this concrete. Her file is one root carrying the centimetre
- * scale and the up-axis rotation (+90° about x, the file's Z-up into the renderer's Y-up), with the
- * mesh node and the joint root as *siblings* beneath it:
+ * This is what `MeshSystem` and `ShadedGeometrySystem` do between them for a game; a playground
+ * has no systems, so `prefab_place` does the same by hand and in one place — this is it, at a
+ * grid position.
  *
- * ```
- * "Character"            R=(0.70711, 0, 0, 0.70711)  S=(0.01, 0.01, 0.01)
- * ├── "Ch03"             mesh 0, skin 0 — no local transform of its own
- * └── "mixamorig:Hips"   the joint root
- * ```
- *
- * Nothing under `Ch03` drives a joint, so writing a grid offset there — to either transform —
- * moves nothing at all.
- *
- * ## Why a placement node rather than the character's own root
- *
- * `"Character"`'s local transform is the file's, and it is load-bearing twice over: the 0.01 scale
- * is what makes the inverse-bind matrices agree with the vertex positions, and a `Transform64`
- * composes as `T · R · S`, so a translation written there is *not* the world offset — it is an
- * offset the file's own rotation and scale then act on. A fresh parent keeps the two apart: the
- * grid offset is this node's whole transform, the file's is untouched below it, and the
- * composition happens where it always happens.
- *
- * A node under {@link TransformAuthority.GPU} still follows a CPU-driven parent — the hierarchy
- * pass composes `global` from the node's own TRS and the parent chain — so the joints the pose
- * accumulator owns are carried by this without anyone writing to their rows.
- *
- * ## Why the local transform
- *
- * The same reason the floor is placed that way, and it is worth restating because this page has
- * now been bitten by it twice. `Node3D.transform_global` is **derived** — its doc comment says so
- * — and `updateMatrices` recomputes it from the local transform and the parent chain. The GPU is
- * handed the node's local TRS and composes `node.global` from it, so a placement that only ever
- * reached `transform_global` is discarded at both ends. See `add_floor` for the version of this
- * where the two ends disagreed and produced two different pictures; here they agreed on the wrong
- * answer, which is quieter and took longer to see.
- *
- * @param {Scene} scene
- * @param {SceneBundle} bundle a freshly loaded character — its roots must not be parented yet
+ * @param {GPUSceneContext} scene_context the scene's context — its rows are where the instance goes
+ * @param {EntityComponentDataset} dataset the dataset the scene is bound to
+ * @param {Prefab} prefab the character, compiled once
  * @param {number} x
  * @param {number} z
- * @returns {Node3D} the placement node, now the parent of every root in `bundle.scenes`
+ * @param {object} [options]
+ * @param {boolean} [options.register_animation] whether the instance's skins are registered; off
+ *        leaves a skinned mesh's clone undeformed, which is a question of its own
+ * @returns {{root: number, instance: PrefabInstance, animation: InstanceAnimationRegistration|null}}
+ */
+export function place_character(scene_context: GPUSceneContext, dataset: EntityComponentDataset, prefab: Prefab, x: number, z: number, { register_animation }?: {
+    register_animation?: boolean;
+}): {
+    root: number;
+    instance: PrefabInstance;
+    animation: InstanceAnimationRegistration | null;
+};
+/**
+ * The source geometry a mesh entity draws — for a skinned one, what its clone is a clone of.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @returns {MeshletGeometry}
  */
-export function place_character(scene: Scene, bundle: SceneBundle, x: number, z: number): Node3D;
+export function geometry_of(dataset: EntityComponentDataset, entity: number): MeshletGeometry;
 /**
  * Where the `index`-th of `count` characters stands: a square-ish grid centred on the origin, laid
  * out in rows along +x.
@@ -78,5 +65,4 @@ export function grid_position(index: number, count: number, spacing: number): {
     x: number;
     z: number;
 };
-import { Node3D } from "../../renderer/scene/Node3D.js";
 //# sourceMappingURL=place_character.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"place_character.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/place_character.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,sEAJW,MAAM,KACN,MAAM,GACJ,MAAM,CA+BlB;AAED;;;;;;;;;;;;GAYG;AACH,qCALW,MAAM,SACN,MAAM,WACN,MAAM,GACJ;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAC,CAUlC;uBApHsB,gCAAgC"}
+{"version":3,"file":"place_character.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/place_character.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,oHAPW,MAAM,KACN,MAAM;IAEY,kBAAkB,GAApC,OAAO;IAEL;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,iBAAiB;IAAC,SAAS,EAAE,gCAA8B,IAAI,CAAA;CAAC,CAanG;AAED;;;;;;GAMG;AACH,qEAHW,MAAM,mBAShB;AAED;;;;;;;;;;;;GAYG;AACH,qCALW,MAAM,SACN,MAAM,WACN,MAAM,GACJ;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAC,CAUlC"}

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

@@ -1,96 +1,69 @@
-import { Node3D } from "../../renderer/scene/Node3D.js";
+import { assert } from "../../../core/assert.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { ShadedGeometry } from "../../../engine/graphics/ecs/mesh-v2/ShadedGeometry.js";
+import { prefab_place } from "../../../engine/graphics3/prefab/prefab_place.js";
 
 /**
- * Stand one loaded character on the floor at `(x, 0, z)`.
+ * Stand one character on the floor at `(x, 0, z)`, the way the engine stands one: as entities.
  *
- * ## Why the mesh node is not the placement point
+ * ## What a placed character is
  *
- * It is tempting, and it is what this page used to do: the mesh is the visible thing, so move the
- * mesh. For a {@link SkinnedMesh} that is a no-op, and the reason is the glTF skinning formula
- * itself. A skinned vertex lands at
+ * A prefab instance under a placement entity. The placement's `Transform64` is the offset and
+ * nothing else; every node the file had is an entity below it, holding its own offset from its
+ * parent in a `TransformAttachment`, and the file's own transform — the centimetre scale and the
+ * up-axis rotation an FBX-derived glTF carries on its root — stays where the prefab put it, on the
+ * entity that stands for that root. "Compose, do not replace": a `Transform64` composes as
+ * `T · R · S`, so a translation written into the file's root would not be the world offset but one
+ * the rotation and scale then act on.
  *
- * ```
- * mesh.global × inverse(mesh.global) × joint.global × inverse_bind × v
- * ```
+ * ## Where the GPU reads it
  *
- * — `chunk_skin_blend_mesh_local` folds the leftmost inverse into each joint matrix and the
- * rasterizer re-applies `mesh.global` afterwards, so the mesh node's own transform **cancels
- * exactly** and the vertex is at `joint.global × inverse_bind × v`. `compute_skin_world_bounds`
- * composes the published box the same way and does not read the mesh node either. So a skinned
- * character is placed by its **joints**, and the only thing that moves them is an ancestor they
- * actually sit under.
+ * Every entity of the instance holds a row of the `transforms` table, at `entity + 1`, and the
+ * hierarchy pass composes each row's `global` from its offset and its parent's row — so the joints
+ * the pose accumulator drives are carried by the placement without anyone writing to them. The
+ * primitives hold a row of the `meshes` table too, over a clone of their geometry when the mesh is
+ * skinned, which is the region the skinning pass deforms and the BLAS refit follows.
  *
- * Michelle is the shape that makes this concrete. Her file is one root carrying the centimetre
- * scale and the up-axis rotation (+90° about x, the file's Z-up into the renderer's Y-up), with the
- * mesh node and the joint root as *siblings* beneath it:
+ * This is what `MeshSystem` and `ShadedGeometrySystem` do between them for a game; a playground
+ * has no systems, so `prefab_place` does the same by hand and in one place — this is it, at a
+ * grid position.
  *
- * ```
- * "Character"            R=(0.70711, 0, 0, 0.70711)  S=(0.01, 0.01, 0.01)
- * ├── "Ch03"             mesh 0, skin 0 — no local transform of its own
- * └── "mixamorig:Hips"   the joint root
- * ```
- *
- * Nothing under `Ch03` drives a joint, so writing a grid offset there — to either transform —
- * moves nothing at all.
- *
- * ## Why a placement node rather than the character's own root
- *
- * `"Character"`'s local transform is the file's, and it is load-bearing twice over: the 0.01 scale
- * is what makes the inverse-bind matrices agree with the vertex positions, and a `Transform64`
- * composes as `T · R · S`, so a translation written there is *not* the world offset — it is an
- * offset the file's own rotation and scale then act on. A fresh parent keeps the two apart: the
- * grid offset is this node's whole transform, the file's is untouched below it, and the
- * composition happens where it always happens.
- *
- * A node under {@link TransformAuthority.GPU} still follows a CPU-driven parent — the hierarchy
- * pass composes `global` from the node's own TRS and the parent chain — so the joints the pose
- * accumulator owns are carried by this without anyone writing to their rows.
- *
- * ## Why the local transform
- *
- * The same reason the floor is placed that way, and it is worth restating because this page has
- * now been bitten by it twice. `Node3D.transform_global` is **derived** — its doc comment says so
- * — and `updateMatrices` recomputes it from the local transform and the parent chain. The GPU is
- * handed the node's local TRS and composes `node.global` from it, so a placement that only ever
- * reached `transform_global` is discarded at both ends. See `add_floor` for the version of this
- * where the two ends disagreed and produced two different pictures; here they agreed on the wrong
- * answer, which is quieter and took longer to see.
- *
- * @param {Scene} scene
- * @param {SceneBundle} bundle a freshly loaded character — its roots must not be parented yet
+ * @param {GPUSceneContext} scene_context the scene's context — its rows are where the instance goes
+ * @param {EntityComponentDataset} dataset the dataset the scene is bound to
+ * @param {Prefab} prefab the character, compiled once
  * @param {number} x
  * @param {number} z
- * @returns {Node3D} the placement node, now the parent of every root in `bundle.scenes`
+ * @param {object} [options]
+ * @param {boolean} [options.register_animation] whether the instance's skins are registered; off
+ *        leaves a skinned mesh's clone undeformed, which is a question of its own
+ * @returns {{root: number, instance: PrefabInstance, animation: InstanceAnimationRegistration|null}}
  */
-export function place_character(scene, bundle, x, z) {
-    const placement = new Node3D();
-
-    placement.name = `placement(${x}, ${z})`;
+export function place_character(scene_context, dataset, prefab, x, z, { register_animation = true } = {}) {
+    const placement = new Transform64();
 
     // `Transform64` keeps its matrix by hand: setting a component leaves the matrix holding what it
     // held before, so the write is only real after `updateMatrix`.
-    placement.transform_local.setTranslation(x, 0, z);
-    placement.transform_local.updateMatrix();
+    placement.setTranslation(x, 0, z);
+    placement.updateMatrix();
 
-    placement.addChildren(bundle.scenes);
+    const { root, instance, animation } = prefab_place(scene_context, dataset, prefab, placement, { register_animation });
 
-    placement.updateMatrices();
+    return { root, instance, animation };
+}
 
-    // `updateMatrices` walks pre-order, and a glTF character's joint root is the mesh node's
-    // sibling — so the `updateBoundsBasic` a SkinnedMesh inherits mid-walk reads joints the walk
-    // has not reached yet, and bounds the mesh where the character stood before the move. The walk
-    // is over by here, so this pass reads a settled skeleton. `GPUSceneContext` re-derives the box
-    // again on its way to the `meshes` row for exactly this reason; this is so the mesh is not
-    // carrying a stale one in the meantime.
-    placement.traverse(node => {
-        if (node.isMesh === true) {
-            node.updateBoundsBasic();
-        }
-    });
+/**
+ * The source geometry a mesh entity draws — for a skinned one, what its clone is a clone of.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @returns {MeshletGeometry}
+ */
+export function geometry_of(dataset, entity) {
+    const geometry = dataset.getComponent(entity, ShadedGeometry);
 
-    scene.add(placement);
+    assert.defined(geometry, `entity ${entity} carries no ShadedGeometry`);
 
-    return placement;
+    return geometry.geometry;
 }
 
 /**

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

@@ -18,7 +18,7 @@
  * @param {Renderer} options.renderer
  * @param {PerspectiveCamera} options.camera
  * @param {Scene} options.scene
- * @param {Mesh} options.mesh the instance to orbit and to frame on
+ * @param {number} options.entity the mesh entity to orbit and to frame on
  * @param {function(boolean): void} [options.suspend]
  * @param {number} [options.azimuths]
  * @param {number[]} [options.elevations] radians; negative looks up from below
@@ -26,11 +26,11 @@
  * @param {number} [options.samples] samples per pixel at each view
  * @returns {Promise<object>}
  */
-export function sweep_views({ renderer, camera, scene, mesh, suspend, azimuths, elevations, distance, samples, }: {
+export function sweep_views({ renderer, camera, scene, entity, suspend, azimuths, elevations, distance, samples, }: {
     renderer: Renderer;
     camera: PerspectiveCamera;
     scene: Scene;
-    mesh: Mesh;
+    entity: number;
     suspend?: (arg0: boolean) => void;
     azimuths?: number;
     elevations?: number[];

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

@@ -1 +1 @@
-{"version":3,"file":"sweep_views.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/sweep_views.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;GAYG;AACH;IAX6B,QAAQ;IACC,MAAM;IAClB,KAAK;IACN,IAAI;IACgB,OAAO,UAAhC,OAAO,KAAG,IAAI;IACN,QAAQ,GAAzB,MAAM;IACa,UAAU,GAA7B,MAAM,EAAE;IACS,QAAQ,GAAzB,MAAM;IACW,OAAO,GAAxB,MAAM;IACJ,QAAQ,MAAM,CAAC,CAwG3B"}
+{"version":3,"file":"sweep_views.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/sweep_views.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;GAYG;AACH;IAX6B,QAAQ;IACC,MAAM;IAClB,KAAK;IACJ,MAAM,EAAtB,MAAM;IAC4B,OAAO,UAAhC,OAAO,KAAG,IAAI;IACN,QAAQ,GAAzB,MAAM;IACa,UAAU,GAA7B,MAAM,EAAE;IACS,QAAQ,GAAzB,MAAM;IACW,OAAO,GAAxB,MAAM;IACJ,QAAQ,MAAM,CAAC,CAwG3B"}

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

@@ -1,4 +1,5 @@
 import Vector3 from "../../../core/geom/Vector3.js";
+import { row_of_entity } from "../../renderer/scene/rows/GPUSceneRows.js";
 import { diff_traced_against_rasterized } from "./diff_traced_against_rasterized.js";
 
 /**
@@ -22,7 +23,7 @@ import { diff_traced_against_rasterized } from "./diff_traced_against_rasterized
  * @param {Renderer} options.renderer
  * @param {PerspectiveCamera} options.camera
  * @param {Scene} options.scene
- * @param {Mesh} options.mesh the instance to orbit and to frame on
+ * @param {number} options.entity the mesh entity to orbit and to frame on
  * @param {function(boolean): void} [options.suspend]
  * @param {number} [options.azimuths]
  * @param {number[]} [options.elevations] radians; negative looks up from below
@@ -34,7 +35,7 @@ export async function sweep_views({
                                       renderer,
                                       camera,
                                       scene,
-                                      mesh,
+                                      entity,
                                       suspend = () => undefined,
                                       azimuths = 8,
                                       elevations = [-0.9, -0.3, 0.3, 0.9],
@@ -45,7 +46,7 @@ export async function sweep_views({
 
     const record = await scene_context.scene_database.debug_table_read_element(
         'meshes',
-        scene_context.mesh_row_of(mesh)
+        row_of_entity(entity)
     );
 
     const box = record.bounding_box;

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

@@ -14,14 +14,14 @@
  * @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 function verify_clone_leaves({ renderer, scene, mesh, tolerance }: {
+export function verify_clone_leaves({ renderer, scene, entity, tolerance }: {
     renderer: Renderer;
     scene: Scene;
-    mesh: SkinnedMesh;
+    entity: number;
     tolerance?: number;
 }): Promise<object>;
 //# sourceMappingURL=verify_clone_leaves.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"verify_clone_leaves.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/verify_clone_leaves.js"],"names":[],"mappings":"AAsDA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAN6B,QAAQ;IACX,KAAK;IACC,IAAI;IACR,SAAS,GAA1B,MAAM;IACJ,QAAQ,MAAM,CAAC,CAsD3B"}
+{"version":3,"file":"verify_clone_leaves.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/verify_clone_leaves.js"],"names":[],"mappings":"AAuDA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAN6B,QAAQ;IACX,KAAK;IACJ,MAAM,EAAtB,MAAM;IACW,SAAS,GAA1B,MAAM;IACJ,QAAQ,MAAM,CAAC,CA4D3B"}