@woosh/meep-engine 3.23.0 → 3.25.0

package/src/shade/RENDERER_CONTRACT.md

@@ -23,8 +23,9 @@ applied deferred; and the result is temporally resolved, upscaled, tonemapped an
 
 Three consequences that shape everything below:
 
-- **A mesh is a small GPU-resident record, not a draw call you own.** You add a `Mesh` to a `Scene`;
-  what is drawn, in what order, and whether it is culled is the renderer's.
+- **A mesh is a small GPU-resident record, not a draw call you own.** You place a model at entities
+  of the scene's dataset and each primitive is a row; what is drawn, in what order, and whether it
+  is culled is the renderer's.
 - **Preparing geometry is a precompute.** Meshlet building, encoding and BVH construction happen
   once per geometry. Content that rewrites its vertices every frame goes down a separate path (§8).
 - **The frame is a closed sequence with declared injection points.** You do not insert a pass
@@ -95,6 +96,11 @@ import { Renderer } from "./renderer/Renderer.js";
 import { Scene } from "./renderer/scene/Scene.js";
 import { PerspectiveCamera } from "./renderer/camera/PerspectiveCamera.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 { Transform64 } from "../engine/ecs/transform/Transform64.js";
+import { prefab_compile } from "../engine/graphics3/prefab/prefab_compile.js";
+import { prefab_place } from "../engine/graphics3/prefab/prefab_place.js";
 import { load_gltf } from "./renderer/loader/gltf/load_gltf.js";
 import { create_frame_loop } from "./renderer/create_frame_loop.js";
 import { DEG_TO_RAD } from "../core/math/DEG_TO_RAD.js";
@@ -117,12 +123,19 @@ camera.aspect = renderer.aspect_ratio;
 
 const scene = new Scene();
 
+// everything in a scene stands at an entity, so the scene names a dataset — a map of components,
+// no systems
+scene.dataset = new EntityComponentDataset();
+
 // nothing is lit without one, and the deferred shading pass has no default light
-scene.lights.add(make_sunlight({ intensity: 2.2 }));
+place_light(scene, make_sunlight({ intensity: 2.2 }));
 
 const bundle = await load_gltf("model.glb", { assetManager });
 
-scene.add(bundle.scenes);
+// the model as loaded is compiled once; a placement of it is entities of the dataset, one per node
+// of the file, each with a row of the scene's GPU database — the scene's context is where the rows
+// live
+prefab_place(renderer.scenes.obtain(scene), scene.dataset, prefab_compile(bundle), new Transform64());
 
 create_frame_loop(dt => renderer.render(camera, scene, dt));
 ```
@@ -157,68 +170,82 @@ has a configured manager on it and should use that one.
 directly, which is §4 in the other direction and needs no asset manager at all:
 
 ```js
-const mesh = new Mesh();
-
-mesh.geometry = meshlet_geometry_build_from_geometry(make_torus_knot_geometry(1, 0.3, 128, 16));
-mesh.material = new StandardShadeMaterial();
+const transform = new Transform64();
 
-mesh.transform_local.setTranslation(0, 1, 0);
-mesh.updateMatrices();
+transform.setTranslation(0, 1, 0);
+transform.updateMatrix();
 
-scene.add(mesh);
+place_primitive(
+    renderer.scenes.obtain(scene),
+    meshlet_geometry_build_from_geometry(make_torus_knot_geometry(1, 0.3, 128, 16)),
+    new StandardShadeMaterial(),
+    transform
+);
 ```
 
 **`render` returns a boolean.** `false` means the previous frame has not finished and this one was
 not submitted. It is not an error.
 
-**`scene.add` takes a node or an array of them, and it recurses.** Nodes tagged `isLight` are routed
-to `scene.lights`, everything else into `scene.instances`; `scene.remove` mirrors it exactly.
+**Everything drawn or posed is an entity of the scene's dataset, holding a row of the scene's GPU
+database.** `prefab_place` answers what it placed — the root entity, the instance, its animation
+registration — and `prefab_unplace` takes it all back; `place_primitive` answers the entity,
+`move_primitive` moves it and `remove_primitive` takes it back. A game calls none of them: its
+systems take rows as components appear. A light is the same shape — it stands at an entity, and
+`scene.lights.add(light, entity)` — `place_light(scene, light)`, for a caller with no entity of its
+own — is what puts it in the scene. Its record's pose is that entity's row, read on the GPU every
+frame.
 
 ---
 
 ## 4. The type model
 
-Everything in a scene is a **`Node3D`**: a TRS transform, a parent and children, and a row in the GPU
-scene-graph. `Scene` is itself a `Node3D` and occupies row 0, so posing the scene world-shifts
-everything under it.
-
-**A node is placed through `transform_local`, and everything else about where it is, is derived.**
-`transform_global` is recomputed from the local transform and the parent chain by `updateMatrices()`,
-which is also what refreshes a `Mesh`'s world-space bounds — so writing `transform_global` directly is
-undone the moment anything refreshes, and mutating `transform_local` without calling
-`updateMatrices()` leaves both the global transform and the bounds stale. A version counter on the
-node records the refresh, and the renderer compares against it.
-
-**A node's transform and a camera's are different types, deliberately, and this is the one place a
-newcomer will trip.** `Node3D.transform_local` is a `Transform64`: a flat `Float64Array` holding its
-own matrix, posed through `setTranslation(x, y, z)` / `setRotation(x, y, z, w)` / `setScale(x, y, z)`,
-with the buffer layout part of its contract so hot code can write it directly. A `Camera` is **not**
-a `Node3D` — it carries meep's ECS `Transform`, whose `position`, `rotation` and `scale` are
-observable vectors you assign into. The two keep distinct shapes on purpose and neither has the
-other's accessors: `node.transform_local.position` is `undefined`, and so is
+Everything in a scene is an **entity** of the scene's dataset, and what the renderer knows about it
+is **a row** of the scene's GPU database, at `entity + 1` in two tables: `transforms` — its local TRS
+and the row of its parent — and, for a primitive, `meshes` — which geometry, which material, and the
+world bounds. Row 0 is the scene root, identity. There is no CPU object per node, no parent pointer
+to follow and no world matrix to recompose: the GPU composes every chain each frame, from the rows,
+and derives every mesh row's bounds under the composed matrix.
+
+**An entity is placed through its `Transform64`, and what the GPU holds is derived from it.** A
+root entity's row carries its world pose; an entity attached under another (`TransformAttachment`)
+carries its local offset and names its parent's row. A game's systems write these as components
+change; a scene with no systems places through `prefab_place` and `place_primitive`, and moves a
+primitive through `move_primitive`, which marks the row for the next build. The box that is drawn
+is the GPU's — `GPUSceneContext.bounds` reads it back, a frame or two behind — and nothing on the
+CPU keeps a copy of it.
+
+**An entity's transform and a camera's are different types, deliberately, and this is the one place
+a newcomer will trip.** `Transform64` is a flat `Float64Array` holding its own matrix, posed through
+`setTranslation(x, y, z)` / `setRotation(x, y, z, w)` / `setScale(x, y, z)` and refreshed with
+`updateMatrix()`, with the buffer layout part of its contract so hot code can write it directly. A
+`Camera` is **not** an entity — it carries meep's ECS `Transform`, whose `position`, `rotation` and
+`scale` are observable vectors you assign into. The two keep distinct shapes on purpose and neither
+has the other's accessors: `transform.position` is `undefined` on a `Transform64`, and so is
 `camera.transform.translation`.
 
 ```js
-node.transform_local.setTranslation(0, 1, 0);   // Transform64 — then updateMatrices()
-camera.transform.position.set(0, 2, -5);        // Transform    — reactive, no refresh call
+transform.setTranslation(0, 1, 0);         // Transform64 — then updateMatrix()
+camera.transform.position.set(0, 2, -5);   // Transform    — reactive, no refresh call
 ```
 
 ```
-Scene  (Node3D, row 0)
-├── lights        LightCollection   — their own pipeline, not in the instance batch
-└── instances     InstanceBatch
-    ├── nodes     every Node3D ever added, in insertion order
-    └── instances the Mesh-bearing subset, which is what the rasterizer iterates
+Scene
+├── dataset             EntityComponentDataset — every entity the scene draws or poses; its rows
+├── lights              LightCollection        — each at an entity; their own pipeline, not a mesh row
+├── light_probe_volume
+└── volumetrics
 ```
 
-A **`Mesh`** is a `Node3D` plus two fields:
+A **primitive** is an entity holding a `meshes` row. Its `ShadedGeometry` component names what the
+row draws, so a tool can read it back:
 
 ```js
-mesh.geometry  // MeshletGeometry — what to draw
-mesh.material  // ShadeMaterial   — how to draw it
+geometry  // MeshletGeometry — what to draw
+material  // ShadeMaterial   — how to draw it
 ```
 
-and a world-space `bounding_box` / `bounding_sphere` the renderer keeps for culling.
+and the row carries the world-space `bounding_box` / `bounding_sphere` the renderer derives for
+culling.
 
 ### Geometry: two types, one of which is a precompute
 
@@ -236,7 +263,7 @@ Seven generators ship, all returning a `Geometry`, in `renderer/geometry/primiti
 `make_torus_geometry`, `make_cylinder_geometry`, `make_torus_knot_geometry`.
 
 **`MeshletGeometry`** is the GPU form: triangles clustered into meshlets, attributes encoded, and a
-BVH over the clusters. This is what a `Mesh` carries, and it is what buys cluster culling and a
+BVH over the clusters. This is what a mesh row names, and it is what buys cluster culling and a
 compact residency.
 
 ```js
@@ -297,15 +324,17 @@ types answer `equals`/`hash`, which is what lets the renderer de-duplicate uploa
 `load_gltf` returns a **`SceneBundle`** — three arrays out of the one file:
 
 ```js
-bundle.scenes   // Node3D[]           — the scene roots, ready for scene.add
-bundle.skins    // Skin[]             — for GPUAnimationManager.register_skin
-bundle.clips    // ShadeAnimationClip[] — for register_clip
+bundle.nodes    // SceneNode[]          — the file's nodes in pre-order: name, parent, local TRS, geometry, material
+bundle.skins    // Skin[]               — joints and meshes as indices into nodes
+bundle.clips    // ShadeAnimationClip[] — each channel targets an index into nodes
+bundle.lights   // {light, node}[]      — anchored by index
 ```
 
-The bundle is **the model as loaded, not a placement of it.** Adding one bundle's roots to two
-scenes, or twice to one scene, shares nodes. meep's ECS layer provides
-`instantiate_scene_bundle(bundle)` for the copy a second placement needs — its own nodes, its own
-skin and its own retargeted clips — which is what makes two of one model possible.
+The bundle is **the model as loaded, not a placement of it** — records, with no transform state
+anyone could pose. It is compiled once into a `Prefab` (`prefab_compile`), and every placement is
+spawned from that — `prefab_place` in a scene with no systems, `prefab_instantiate` under a game's
+own root entity — with its own entities, its own skins and its own retargeted clips, addressed by
+entity, which is what makes two of one model possible.
 
 ---
 
@@ -523,8 +552,8 @@ geometry.needsUpdate = true;   // you say when the vertices changed; nothing wat
 ```
 
 This is **a separate path, not a variant of the standard one.** A `DynamicMesh` holds a plain
-`Geometry`, is never in the scene's instance batch, gets no row in the scene database, and is drawn
-by a pipeline of its own after the standard geometry path has finished with the frame.
+`Geometry` and its own `transform`, is no entity of the scene, gets no row in the scene database,
+and is drawn by a pipeline of its own after the standard geometry path has finished with the frame.
 
 Drawing it is a `GPUDynamicMeshRenderer` inside an extension of yours (§6). Two things to know:
 
@@ -566,7 +595,7 @@ frame or is removed and re-added keeps its buffers.
 ```
 shade/renderer/
 ├── Renderer.js               the whole surface in §2, §7, §9
-├── scene/                    Scene, Node3D, Mesh, SkinnedMesh, DynamicMesh, InstanceBatch
+├── scene/                    Scene, GPUSceneContext, rows/ — GPUSceneRows, place_primitive; DynamicMesh
 ├── geometry/                 Geometry, MeshletGeometry, the builders, primitives/
 ├── material/                 ShadeMaterial, StandardShadeMaterial
 ├── texture/                  ShadeTexture, GPUTextureContext, source/ShadeImage
@@ -578,6 +607,9 @@ shade/renderer/
 └── animation/                GPUAnimationManager — skins and clips
 ```
 
+`prefab_compile` and `prefab_place` live with the ECS, in `engine/graphics3/prefab/`, because a
+placement is entities.
+
 `shade/device/mock/` holds a **validating software device**: no shader execution, but real validation
 of bindings, passes, resources and texture copies. It is how the renderer's own tests run without a
 GPU, and it is available to yours. Specs must never acquire a real device — see `vitest.config.mjs`,

package/src/shade/device/ShadeGPUCommandContext.d.ts

@@ -30,6 +30,21 @@ export class ShadeGPUCommandContext {
      * @returns {GPUCommandEncoder}
      */
     get gpu_encoder(): GPUCommandEncoder;
+    /**
+     * The graphics context this was created against, whose allocators the commands recorded here
+     * draw on.
+     *
+     * @returns {GraphicsContext}
+     */
+    get graphics(): import("../renderer/GraphicsContext.js").GraphicsContext;
+    /**
+     * Whether {@link finish} has run — which is the moment the commands recorded here were
+     * submitted. Anything that must not happen before submission, such as mapping a buffer one of
+     * those commands copies into, checks this rather than counting frames.
+     *
+     * @returns {boolean}
+     */
+    get finished(): boolean;
     /**
      * Resolves after this context's timings have been read back and handed to its recorder.
      *
@@ -114,6 +129,14 @@ export class ShadeGPUCommandContext {
      * @param {GPUExtent3DStrict} copySize
      */
     copyTextureToTexture(source: GPUImageCopyTexture, destination: GPUImageCopyTexture, copySize: GPUExtent3DStrict): void;
+    /**
+     * Texels out of a texture into a buffer — what a readback of a rendered image starts with.
+     *
+     * @param {GPUImageCopyTexture} source
+     * @param {GPUImageCopyBuffer} destination
+     * @param {GPUExtent3DStrict} copySize
+     */
+    copyTextureToBuffer(source: GPUImageCopyTexture, destination: GPUImageCopyBuffer, copySize: GPUExtent3DStrict): void;
     /**
      *
      * @param {GPUComputePassDescriptor} [descriptor]

package/src/shade/device/ShadeGPUCommandContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShadeGPUCommandContext.d.ts","sourceRoot":"","sources":["../../../../src/shade/device/ShadeGPUCommandContext.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"ShadeGPUCommandContext.d.ts","sourceRoot":"","sources":["../../../../src/shade/device/ShadeGPUCommandContext.js"],"names":[],"mappings":"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"}

package/src/shade/device/ShadeGPUCommandContext.js

@@ -88,6 +88,27 @@ export class ShadeGPUCommandContext {
         return this.#gpu_encoder;
     }
 
+    /**
+     * The graphics context this was created against, whose allocators the commands recorded here
+     * draw on.
+     *
+     * @returns {GraphicsContext}
+     */
+    get graphics() {
+        return this.#graphics;
+    }
+
+    /**
+     * Whether {@link finish} has run — which is the moment the commands recorded here were
+     * submitted. Anything that must not happen before submission, such as mapping a buffer one of
+     * those commands copies into, checks this rather than counting frames.
+     *
+     * @returns {boolean}
+     */
+    get finished() {
+        return this.#finished;
+    }
+
     /**
      * This context's profiling attachment, or null when nothing is profiling — which is the
      * ordinary case and costs one null check per pass.
@@ -357,6 +378,21 @@ export class ShadeGPUCommandContext {
         this.#gpu_encoder.copyTextureToTexture(source, destination, copySize);
     }
 
+    /**
+     * Texels out of a texture into a buffer — what a readback of a rendered image starts with.
+     *
+     * @param {GPUImageCopyTexture} source
+     * @param {GPUImageCopyBuffer} destination
+     * @param {GPUExtent3DStrict} copySize
+     */
+    copyTextureToBuffer(source, destination, copySize) {
+        assert.defined(source, 'source');
+        assert.defined(destination, 'destination');
+        assert.notEqual(destination.buffer.usage & GPUBufferUsage.COPY_DST, 0, 'destination must include COPY_DST usage flag');
+
+        this.#gpu_encoder.copyTextureToBuffer(source, destination, copySize);
+    }
+
     /**
      *
      * @param {GPUComputePassDescriptor} [descriptor]

package/src/shade/device/mock/texture_copy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"texture_copy.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/texture_copy.js"],"names":[],"mappings":"AAiLA;;;;;;;;;;;;;GAaG;AACH;IAP0C,cAAc;IACf,aAAa;IACZ,mBAAmB;IACpB,kBAAkB;IAC9B,IAAI;IACpB,MAAM,GAAC,IAAI,CA4DvB;AAiED;;;;;GAKG;AACH,uHAHW,MAAM,GACJ,IAAI,CA8BhB;;;;;;UA5Fa,WAAW;;;;YACX,MAAM;gBACN,MAAM;kBACN,MAAM"}
+{"version":3,"file":"texture_copy.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/texture_copy.js"],"names":[],"mappings":"AA6MA;;;;;;;;;;;;;GAaG;AACH;IAP0C,cAAc;IACf,aAAa;IACZ,mBAAmB;IACpB,kBAAkB;IAC9B,IAAI;IACpB,MAAM,GAAC,IAAI,CA4DvB;AAiED;;;;;GAKG;AACH,uHAHW,MAAM,GACJ,IAAI,CA8BhB;;;;;;UA5Fa,WAAW;;;;YACX,MAAM;gBACN,MAAM;kBACN,MAAM"}

package/src/shade/device/mock/texture_copy.js

@@ -104,6 +104,34 @@ function texture_endpoint_refusal(info, role, required_usage, required_usage_nam
         return `${role} copySize.height (${extent.height}) is not a multiple of the ${format.block_height}-texel block height of ${texture.format}`;
     }
 
+    /*
+     WebGPU's rule for `copyTextureToBuffer`/`copyBufferToTexture`/`writeTexture`: "if the
+     GPUTexture.format is a depth-or-stencil format or GPUTexture.sampleCount is more than 1, the
+     subresource size is equal to size". A depth buffer is copied whole or not at all — there is no
+     reading one texel of one, and the one-pixel read that looks like the obvious way to pick an
+     entity off the frame's depth is the thing this forbids. The restriction comes from D3D12, so
+     it is enforced everywhere rather than being a Windows-only surprise.
+
+     Only the two axes a region is named in: this does not also require a layered copy to take every
+     layer, which WebGPU's definition of a subresource's size does.
+    */
+    const depth_or_stencil = !format.aspects.includes("all");
+
+    if (depth_or_stencil || texture.sampleCount > 1) {
+        const full_width = texture.mip_width(mip);
+        const full_height = texture.mip_height(mip);
+
+        if (origin.x !== 0 || origin.y !== 0 || extent.width !== full_width || extent.height !== full_height) {
+            const why = depth_or_stencil
+                ? `is ${texture.format}, a depth-or-stencil format`
+                : `has sampleCount ${texture.sampleCount}`;
+
+            return `${role} texture '${texture.label}' ${why}, so a copy must cover the whole`
+                + ` subresource; mip ${mip} is ${full_width}x${full_height} and the region asked for`
+                + ` is ${extent.width}x${extent.height} at (${origin.x}, ${origin.y})`;
+        }
+    }
+
     return null;
 }
 

package/src/shade/playground/add_random_meshes.d.ts

@@ -13,7 +13,7 @@
  * does not scatter one shape at a hundred times the size of another by accident.
  *
  * @param {Object} options
- * @param {InstanceBatch} options.batch
+ * @param {GPUSceneContext} options.scene_context the scene's context — its rows are where the instances go
  * @param {MeshletGeometry[]} options.geometries not plain `Geometry` — see {@link BoxGeometry} and
  * {@link meshlet_geometry_build_from_geometry}
  * @param {ShadeMaterial[]} [options.materials]
@@ -23,15 +23,15 @@
  * @param {function():number} [options.random] pass one shared generator to keep successive calls from
  * scattering the same instances in the same places
  */
-export function add_random_meshes({ batch, geometries, materials, count, geometry_scale_range, region, random }: {
-    batch: InstanceBatch;
+export function add_random_meshes({ scene_context, geometries, materials, count, geometry_scale_range, region, random }: {
+    scene_context: GPUSceneContext;
     geometries: MeshletGeometry[];
     materials?: ShadeMaterial[];
     count?: number;
     geometry_scale_range?: NumericInterval;
     region?: AABB3;
     random?: () => number;
-}): void;
+}): number[];
 import { NumericInterval } from "../../core/math/interval/NumericInterval.js";
 import { AABB3 } from "../../core/geom/3d/aabb/AABB3.js";
 //# sourceMappingURL=add_random_meshes.d.ts.map

package/src/shade/playground/add_random_meshes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"add_random_meshes.d.ts","sourceRoot":"","sources":["../../../../src/shade/playground/add_random_meshes.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;IAVkC,KAAK;IACD,UAAU,EAArC,iBAAiB;IAES,SAAS,GAAnC,eAAe;IACE,KAAK,GAAtB,MAAM;IACoB,oBAAoB,GAA9C,eAAe;IACC,MAAM,GAAtB,KAAK;IACuB,MAAM,SAAvB,MAAM;SAuF3B;gCA/H+B,6CAA6C;sBAJvD,kCAAkC"}
+{"version":3,"file":"add_random_meshes.d.ts","sourceRoot":"","sources":["../../../../src/shade/playground/add_random_meshes.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;IAVoC,aAAa;IACX,UAAU,EAArC,iBAAiB;IAES,SAAS,GAAnC,eAAe;IACE,KAAK,GAAtB,MAAM;IACoB,oBAAoB,GAA9C,eAAe;IACC,MAAM,GAAtB,KAAK;IACuB,MAAM,SAAvB,MAAM;aA0F3B;gCAnI+B,6CAA6C;sBAJvD,kCAAkC"}

package/src/shade/playground/add_random_meshes.js

@@ -9,7 +9,8 @@ import { randomFromArray } from "../../core/math/random/randomFromArray.js";
 import { randomIntegerBetween } from "../../core/math/random/randomIntegerBetween.js";
 import { seededRandom } from "../../core/math/random/seededRandom.js";
 import { StandardShadeMaterial } from "../renderer/material/StandardShadeMaterial.js";
-import { Mesh } from "../renderer/scene/Mesh.js";
+import { Transform64 } from "../../engine/ecs/transform/Transform64.js";
+import { place_primitive } from "../renderer/scene/rows/place_primitive.js";
 
 const default_mat = new StandardShadeMaterial();
 
@@ -36,7 +37,7 @@ const DEFAULT_REGION = new AABB3(-200, -200, -200, 200, 200, 200);
  * does not scatter one shape at a hundred times the size of another by accident.
  *
  * @param {Object} options
- * @param {InstanceBatch} options.batch
+ * @param {GPUSceneContext} options.scene_context the scene's context — its rows are where the instances go
  * @param {MeshletGeometry[]} options.geometries not plain `Geometry` — see {@link BoxGeometry} and
  * {@link meshlet_geometry_build_from_geometry}
  * @param {ShadeMaterial[]} [options.materials]
@@ -47,7 +48,7 @@ const DEFAULT_REGION = new AABB3(-200, -200, -200, 200, 200, 200);
  * scattering the same instances in the same places
  */
 export function add_random_meshes({
-                                      batch,
+                                      scene_context,
                                       geometries,
                                       materials = [default_mat],
                                       count = 10000,
@@ -56,7 +57,7 @@ export function add_random_meshes({
                                       random = seededRandom()
                                   }) {
 
-    assert.defined(batch, 'batch');
+    assert.defined(scene_context, 'scene_context');
     assert.isArray(geometries, 'geometries');
     assert.isArray(materials, 'materials');
 
@@ -71,9 +72,10 @@ export function add_random_meshes({
 
         const geometry = geometries[i];
 
-        // Checked up front and by name, because the failure otherwise happens inside `Mesh.from`
-        // once per instance and says only that a flag was false. A plain `Geometry` is the usual
-        // mistake — `make_box_geometry` and friends return one, and the renderer consumes meshlets.
+        // Checked up front and by name, because the failure otherwise happens inside the
+        // placement once per instance and says only that a flag was false. A plain `Geometry` is
+        // the usual mistake — `make_box_geometry` and friends return one, and the renderer consumes
+        // meshlets.
         assert.equal(
             geometry?.isMeshletGeometry, true,
             `geometries[${i}] is not a MeshletGeometry`
@@ -94,6 +96,10 @@ export function add_random_meshes({
 
     const transform_position = new Vector3();
     const transform_rotation = new Quaternion();
+    const transform = new Transform64();
+
+    /** @type {number[]} the entities placed */
+    const placed = [];
 
     const scale_span = geometry_scale_range.max - geometry_scale_range.min;
 
@@ -119,15 +125,13 @@ export function add_random_meshes({
 
         const material = randomFromArray(random, materials);
 
-        const instance = Mesh.from(geometry, material);
-
-        instance.transform_local.setTranslation(transform_position.x, transform_position.y, transform_position.z);
-        instance.transform_local.setRotation(transform_rotation.x, transform_rotation.y, transform_rotation.z, transform_rotation.w);
-        instance.transform_local.setScale(scale, scale, scale);
+        transform.setTranslation(transform_position.x, transform_position.y, transform_position.z);
+        transform.setRotation(transform_rotation.x, transform_rotation.y, transform_rotation.z, transform_rotation.w);
+        transform.setScale(scale, scale, scale);
+        transform.updateMatrix();
 
-        // rebuilds the world-space bounds the transform just invalidated
-        instance.updateMatrices();
-
-        batch.add(instance);
+        placed.push(place_primitive(scene_context, geometry, material, transform));
     }
+
+    return placed;
 }

package/src/shade/playground/avboit/main.d.ts

@@ -1,2 +1,3 @@
 export function start(): Promise<void>;
+export type GPUSceneContext = import("../../renderer/scene/GPUSceneContext.js").GPUSceneContext;
 //# sourceMappingURL=main.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/avboit/main.js"],"names":[],"mappings":"AAoRA,uCAslBC"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/avboit/main.js"],"names":[],"mappings":"AA+RA,uCAonBC;8BA/2BY,OAAO,yCAAyC,EAAE,eAAe"}