@woosh/meep-engine 3.23.0 → 3.25.0

package/src/shade/playground/particle_system/particle_scene.d.ts

@@ -1,6 +1,6 @@
 /**
- * The five emitters, and the node one of them rides. Pure data: no device, no scene, nothing
- * uploaded — {@link build_particle_scene} is what places them.
+ * The five emitters. Pure data: no device, no scene, no place — {@link build_particle_scene} is
+ * what gives each an entity to stand at, and {@link configure_particles} what registers it there.
  *
  * None of them carries bounds. The box the culling and occupancy passes use is measured from the
  * live particles on the GPU and published into the emitter state table every tick, so an effect
@@ -8,7 +8,7 @@
  * what these emitters, with their long-lived jittered plumes, would otherwise be a standing
  * invitation to get wrong.
  *
- * @returns {{fire: ParticleEmitter, smoke: ParticleEmitter, sparks: ParticleEmitter, dust: ParticleEmitter, torch: ParticleEmitter, orbit: Node3D}}
+ * @returns {{fire: ParticleEmitter, smoke: ParticleEmitter, sparks: ParticleEmitter, dust: ParticleEmitter, torch: ParticleEmitter}}
  */
 export function create_particle_emitters(): {
     fire: ParticleEmitter;
@@ -16,46 +16,50 @@ export function create_particle_emitters(): {
     sparks: ParticleEmitter;
     dust: ParticleEmitter;
     torch: ParticleEmitter;
-    orbit: Node3D;
 };
 /**
- * Build the scene: geometry, a light, and the emitters as nodes of it.
+ * What {@link build_particle_scene} returns: the scene, the dataset its entities live in, the
+ * emitters, and the entity each stands at — plus the orbit the torch's rides.
+ *
+ * @typedef {object} ParticleWorld
+ * @property {Scene} scene
+ * @property {EntityComponentDataset} dataset
+ * @property {ReturnType<create_particle_emitters>} emitters
+ * @property {{fire: number, smoke: number, sparks: number, dust: number, torch: number, orbit: number}} entities
+ * @property {{floor: Mesh, pillar: Mesh, block: Mesh, pane: Mesh}} meshes
+ */
+/**
+ * Build the world: geometry, a light, and an entity per emitter — the torch's riding an orbit.
  *
  * Async because the meshlet builder runs on a WASM instance that instantiates asynchronously at
  * import; building geometry before it is ready reads an instance that is not there yet.
  *
- * @returns {Promise<{scene: Scene, emitters: ReturnType<create_particle_emitters>, meshes: {floor: Mesh, pillar: Mesh, block: Mesh, pane: Mesh}}>}
+ * @returns {Promise<ParticleWorld>}
  */
-export function build_particle_scene(): Promise<{
-    scene: Scene;
-    emitters: ReturnType<typeof create_particle_emitters>;
-    meshes: {
-        floor: Mesh;
-        pillar: Mesh;
-        block: Mesh;
-        pane: Mesh;
-    };
-}>;
+export function build_particle_scene(): Promise<ParticleWorld>;
 /**
- * Turn the particles on for this scene and give the system its sprite.
+ * Turn the particles on for this scene, place its emitters, and give the system its sprite.
  *
- * This is the whole integration. The emitters are already scene nodes, so there is nothing to
- * register: the system finds them the next time it sweeps, gives each a row pointed at the node's
- * `transforms` row, and the renderer records the simulation and the three AVBOIT contributions.
+ * This is the whole integration. Each entity gets its row in the renderer's context for the scene,
+ * each emitter is registered at its entity's row, and the renderer records the simulation and the
+ * three AVBOIT contributions from there. The torch's entity hangs off the orbit's, so the GPU
+ * composes the orbit's motion into every particle it spawns with nothing copied through the CPU.
  *
  * @param {import("../../renderer/Renderer.js").Renderer} renderer initialized
- * @param {Scene} scene the one {@link build_particle_scene} returned
+ * @param {ParticleWorld} world the one {@link build_particle_scene} returned
  * @returns {import("../../renderer/particles/GPUParticleSystem.js").GPUParticleSystem}
  */
-export function configure_particles(renderer: import("../../renderer/Renderer.js").Renderer, scene: Scene): import("../../renderer/particles/GPUParticleSystem.js").GPUParticleSystem;
+export function configure_particles(renderer: import("../../renderer/Renderer.js").Renderer, world: ParticleWorld): import("../../renderer/particles/GPUParticleSystem.js").GPUParticleSystem;
 /**
  * Move what moves. One call, so the page's frame loop stays three lines and the motion is here
  * with the scene it belongs to.
  *
- * @param {ReturnType<create_particle_emitters>} emitters
+ * @param {ParticleWorld} world
+ * @param {import("../../renderer/particles/GPUParticleSystem.js").GPUParticleSystem} system the
+ *        one {@link configure_particles} returned; its scene context holds the orbit's row
  * @param {number} time seconds since start
  */
-export function animate_particle_scene(emitters: ReturnType<typeof create_particle_emitters>, time: number): void;
+export function animate_particle_scene(world: ParticleWorld, system: import("../../renderer/particles/GPUParticleSystem.js").GPUParticleSystem, time: number): void;
 /**
  * A 64x64 radial-falloff sprite (white, alpha falloff) for soft additive and alpha blobs.
  *
@@ -84,8 +88,8 @@ export function make_sprite_texture(device: GPUDevice): GPUTexture;
  * - opaque geometry (a floor, a pillar, a block) and one transparent pane, so the particles have
  *   both something to be occluded by and something to composite with,
  * - five emitters sharing one pool, each set up to exercise a different path: additive billboards,
- *   an alpha soft-depth column, velocity-stretched sparks, a wide alpha drift, and one riding a
- *   node that orbits, so a moving emitter is on screen,
+ *   an alpha soft-depth column, velocity-stretched sparks, a wide alpha drift, and one riding an
+ *   entity that orbits, so a moving emitter is on screen,
  * - a sunlight and (from the page) the default environment, because the meshes are lit.
  */
 /**
@@ -105,8 +109,44 @@ export const PARTICLE_EMITTER_MOTION: {
         color: number[];
     };
 };
+/**
+ * The five emitters by name, in the order they are placed.
+ *
+ * @type {ReadonlyArray<"fire"|"smoke"|"sparks"|"dust"|"torch">}
+ */
+export const PARTICLE_EMITTER_NAMES: ReadonlyArray<"fire" | "smoke" | "sparks" | "dust" | "torch">;
+/**
+ * Where each emitter's entity stands — the torch's in the orbit's frame, the rest in the world.
+ *
+ * @type {Object<string, number[]>}
+ */
+export const PARTICLE_EMITTER_PLACEMENT: {
+    [x: string]: number[];
+};
+/**
+ * What {@link build_particle_scene } returns: the scene, the dataset its entities live in, the
+ * emitters, and the entity each stands at — plus the orbit the torch's rides.
+ */
+export type ParticleWorld = {
+    scene: Scene;
+    dataset: EntityComponentDataset;
+    emitters: ReturnType<typeof create_particle_emitters>;
+    entities: {
+        fire: number;
+        smoke: number;
+        sparks: number;
+        dust: number;
+        torch: number;
+        orbit: number;
+    };
+    meshes: {
+        floor: Mesh;
+        pillar: Mesh;
+        block: Mesh;
+        pane: Mesh;
+    };
+};
 import { ParticleEmitter } from "../../renderer/particles/runtime/ParticleEmitter.js";
-import { Node3D } from "../../renderer/scene/Node3D.js";
 import { Scene } from "../../renderer/scene/Scene.js";
-import { Mesh } from "../../renderer/scene/Mesh.js";
+import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
 //# sourceMappingURL=particle_scene.d.ts.map

package/src/shade/playground/particle_system/particle_scene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"particle_scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_system/particle_scene.js"],"names":[],"mappings":"AAoEA;;;;;;;;;;;GAWG;AACH,4CAFa;IAAC,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CA+DlJ;AAED;;;;;;;GAOG;AACH,wCAFa,QAAQ;IAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,2CAAoC,CAAC;IAAC,MAAM,EAAE;QAAC,KAAK,EAAE,IAAI,CAAC;QAAC,MAAM,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,IAAI,CAAA;KAAC,CAAA;CAAC,CAAC,CAuDjJ;AAED;;;;;;;;;;GAUG;AACH,8CAJW,OAAO,4BAA4B,EAAE,QAAQ,SAC7C,KAAK,GACH,OAAO,+CAA+C,EAAE,iBAAiB,CAmBrF;AAED;;;;;;GAMG;AACH,iDAHW,2CAAoC,QACpC,MAAM,QAWhB;AAED;;;;;GAKG;AACH,mEA4BC;AAnQD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;GAKG;AACH;QAFiB,MAAM,GAAE;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAC;EAOpJ;gCA5C8B,qDAAqD;uBAE9D,gCAAgC;sBACjC,+BAA+B;qBAFhC,8BAA8B"}
+{"version":3,"file":"particle_scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_system/particle_scene.js"],"names":[],"mappings":"AAqGA;;;;;;;;;;;GAWG;AACH,4CAFa;IAAC,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,eAAe,CAAA;CAAC,CAkDnI;AAED;;;;;;;;;;GAUG;AAEH;;;;;;;GAOG;AACH,wCAFa,QAAQ,aAAa,CAAC,CAwFlC;AAED;;;;;;;;;;;GAWG;AACH,8CAJW,OAAO,4BAA4B,EAAE,QAAQ,SAC7C,aAAa,GACX,OAAO,+CAA+C,EAAE,iBAAiB,CAiCrF;AAED;;;;;;;;GAQG;AACH,8CALW,aAAa,UACb,OAAO,+CAA+C,EAAE,iBAAiB,QAEzE,MAAM,QAehB;AAED;;;;;GAKG;AACH,mEA4BC;AAjVD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;GAKG;AACH;QAFiB,MAAM,GAAE;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAC;EAOpJ;AAEF;;;;GAIG;AACH,qCAFU,cAAc,MAAM,GAAC,OAAO,GAAC,QAAQ,GAAC,MAAM,GAAC,OAAO,CAAC,CAEmC;AAElG;;;;GAIG;AACH;QAFiB,MAAM,GAAE,MAAM,EAAE;EAa/B;;;;;;WAqEY,KAAK;aACL,sBAAsB;cACtB,2CAAoC;cACpC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC;YACzF;QAAC,KAAK,OAAO;QAAC,MAAM,OAAO;QAAC,KAAK,OAAO;QAAC,IAAI,OAAM;KAAC;;gCArJlC,qDAAqD;sBAG/D,+BAA+B;uCACd,+CAA+C"}

package/src/shade/playground/particle_system/particle_scene.js

@@ -8,6 +8,7 @@ import { meshlet_geometry_build_from_geometry } from "../../renderer/geometry/me
 import { make_box_geometry } from "../../renderer/geometry/primitives/make_box_geometry.js";
 import { make_plane_geometry } from "../../renderer/geometry/primitives/make_plane_geometry.js";
 import { make_sunlight } from "../../renderer/light/make_sunlight.js";
+import { place_light } from "../../renderer/light/place_light.js";
 import { ShadeDrawSide } from "../../renderer/material/ShadeDrawSide.js";
 import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.js";
 import { TransparencyMode } from "../../renderer/material/TransparencyMode.js";
@@ -21,9 +22,16 @@ import { VM_BUILTIN } from "../../renderer/particles/isa/ParticleVMISA.js";
 import { ParticleLayout } from "../../renderer/particles/layout/ParticleLayout.js";
 import { create_particle_effect } from "../../renderer/particles/runtime/create_particle_effect.js";
 import { ParticleEmitter } from "../../renderer/particles/runtime/ParticleEmitter.js";
-import { Mesh } from "../../renderer/scene/Mesh.js";
-import { Node3D } from "../../renderer/scene/Node3D.js";
+import { place_primitive } from "../../renderer/scene/rows/place_primitive.js";
+import { row_of_entity } from "../../renderer/scene/rows/GPUSceneRows.js";
 import { Scene } from "../../renderer/scene/Scene.js";
+import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
+import { GPUStateAuthority } from "../../../engine/ecs/gpu/GPUStateAuthority.js";
+import { GPUStateAuthorityFlags } from "../../../engine/ecs/gpu/GPUStateAuthorityFlags.js";
+import { gpu_authority_declare } from "../../../engine/ecs/gpu/gpu_authority_declare.js";
+import { gpu_authority_grant } from "../../../engine/ecs/gpu/gpu_authority_grant.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { TransformAttachment } from "../../../engine/ecs/transform-attachment/TransformAttachment.js";
 import { ShadeTransparencyMode } from "../../renderer/ShadeTransparencyMode.js";
 import { fire_effect } from "./particle_prototype.js";
 
@@ -48,8 +56,8 @@ import { fire_effect } from "./particle_prototype.js";
  * - opaque geometry (a floor, a pillar, a block) and one transparent pane, so the particles have
  *   both something to be occluded by and something to composite with,
  * - five emitters sharing one pool, each set up to exercise a different path: additive billboards,
- *   an alpha soft-depth column, velocity-stretched sparks, a wide alpha drift, and one riding a
- *   node that orbits, so a moving emitter is on screen,
+ *   an alpha soft-depth column, velocity-stretched sparks, a wide alpha drift, and one riding an
+ *   entity that orbits, so a moving emitter is on screen,
  * - a sunlight and (from the page) the default environment, because the meshes are lit.
  */
 
@@ -67,8 +75,33 @@ export const PARTICLE_EMITTER_MOTION = {
 };
 
 /**
- * The five emitters, and the node one of them rides. Pure data: no device, no scene, nothing
- * uploaded — {@link build_particle_scene} is what places them.
+ * The five emitters by name, in the order they are placed.
+ *
+ * @type {ReadonlyArray<"fire"|"smoke"|"sparks"|"dust"|"torch">}
+ */
+export const PARTICLE_EMITTER_NAMES = Object.freeze(["fire", "smoke", "sparks", "dust", "torch"]);
+
+/**
+ * Where each emitter's entity stands — the torch's in the orbit's frame, the rest in the world.
+ *
+ * @type {Object<string, number[]>}
+ */
+export const PARTICLE_EMITTER_PLACEMENT = {
+    // at the foot of the pillar
+    fire: [-1, 0, 0],
+    // rising at 1.3 m/s for 3 to 5 s, with the buoyancy adding a couple of metres on top
+    smoke: [-1, 2.5, 0],
+    // thrown a few metres up and out, and pulled back down inside a second; by the block
+    sparks: [2, 1.9, -1],
+    // emitted across a 6 m disk, then drifting slowly for up to 7 s
+    dust: [0, 0.3, 0],
+    // riding the orbit, out at its radius
+    torch: [4, 1.2, 0],
+};
+
+/**
+ * The five emitters. Pure data: no device, no scene, no place — {@link build_particle_scene} is
+ * what gives each an entity to stand at, and {@link configure_particles} what registers it there.
  *
  * None of them carries bounds. The box the culling and occupancy passes use is measured from the
  * live particles on the GPU and published into the emitter state table every tick, so an effect
@@ -76,17 +109,16 @@ export const PARTICLE_EMITTER_MOTION = {
  * what these emitters, with their long-lived jittered plumes, would otherwise be a standing
  * invitation to get wrong.
  *
- * @returns {{fire: ParticleEmitter, smoke: ParticleEmitter, sparks: ParticleEmitter, dust: ParticleEmitter, torch: ParticleEmitter, orbit: Node3D}}
+ * @returns {{fire: ParticleEmitter, smoke: ParticleEmitter, sparks: ParticleEmitter, dust: ParticleEmitter, torch: ParticleEmitter}}
  */
 export function create_particle_emitters() {
-    // fire — additive, billboard, flipbook, at the foot of the pillar. The effect is the worked
-    // example from particle_prototype.js next door, unchanged.
+    // fire — additive, billboard, flipbook. The effect is the worked example from
+    // particle_prototype.js next door, unchanged.
     const fire = ParticleEmitter.from({
         ...fire_effect().emitter,
         name: "fire",
         spawn_rate: 500,
         flags: { blend: EMITTER_BLEND.ADDITIVE, projection: EMITTER_PROJECTION.BILLBOARD },
-        position: [-1, 0, 0],
     });
 
     // smoke — alpha, soft-depth, a rising column above the fire
@@ -96,19 +128,15 @@ export function create_particle_emitters() {
         spawn_rate: 60,
         flags: { blend: EMITTER_BLEND.ALPHA, projection: EMITTER_PROJECTION.BILLBOARD, soft_depth: true },
         render: { position: "position", size: "size", color: "color" },
-        // rising at 1.3 m/s for 3 to 5 s, with the buoyancy adding a couple of metres on top
-        position: [-1, 2.5, 0],
     });
 
-    // sparks — additive, velocity-stretched, fast, short-lived, under gravity, by the block
+    // sparks — additive, velocity-stretched, fast, short-lived, under gravity
     const sparks = ParticleEmitter.from({
         name: "sparks",
         ...make_effect(PARTICLE_EMITTER_MOTION.sparks),
         spawn_rate: 350,
         flags: { blend: EMITTER_BLEND.ADDITIVE, projection: EMITTER_PROJECTION.STRETCHED },
         render: { position: "position", size: "size", color: "color", velocity: "velocity" },
-        // thrown a few metres up and out, and pulled back down inside a second
-        position: [2, 1.9, -1],
     });
 
     // dust — alpha, soft-depth, a slow wide drift across the ground
@@ -118,43 +146,53 @@ export function create_particle_emitters() {
         spawn_rate: 120,
         flags: { blend: EMITTER_BLEND.ALPHA, projection: EMITTER_PROJECTION.BILLBOARD, soft_depth: true },
         render: { position: "position", size: "size", color: "color" },
-        // emitted across a 6 m disk, then drifting slowly for up to 7 s
-        position: [0, 0.3, 0],
     });
 
-    // a torch riding an orbiting node: the emitter has no idea it moves — its parent does, and the
-    // GPU hierarchy pass composes the two, with nothing copied through the CPU
-    const orbit = new Node3D();
-    orbit.name = "orbit";
-
+    // a torch riding an orbiting entity: the emitter has no idea it moves — its entity's parent
+    // does, and the GPU hierarchy pass composes the two, with nothing copied through the CPU
     const torch = ParticleEmitter.from({
         name: "torch",
         ...make_effect(PARTICLE_EMITTER_MOTION.torch),
         spawn_rate: 200,
         flags: { blend: EMITTER_BLEND.ADDITIVE, projection: EMITTER_PROJECTION.BILLBOARD },
         render: { position: "position", size: "size", color: "color" },
-        position: [4, 1.2, 0],
     });
 
-    orbit.addChild(torch);
-
-    return { fire, smoke, sparks, dust, torch, orbit };
+    return { fire, smoke, sparks, dust, torch };
 }
 
 /**
- * Build the scene: geometry, a light, and the emitters as nodes of it.
+ * What {@link build_particle_scene} returns: the scene, the dataset its entities live in, the
+ * emitters, and the entity each stands at — plus the orbit the torch's rides.
+ *
+ * @typedef {object} ParticleWorld
+ * @property {Scene} scene
+ * @property {EntityComponentDataset} dataset
+ * @property {ReturnType<create_particle_emitters>} emitters
+ * @property {{fire: number, smoke: number, sparks: number, dust: number, torch: number, orbit: number}} entities
+ * @property {{floor: Mesh, pillar: Mesh, block: Mesh, pane: Mesh}} meshes
+ */
+
+/**
+ * Build the world: geometry, a light, and an entity per emitter — the torch's riding an orbit.
  *
  * Async because the meshlet builder runs on a WASM instance that instantiates asynchronously at
  * import; building geometry before it is ready reads an instance that is not there yet.
  *
- * @returns {Promise<{scene: Scene, emitters: ReturnType<create_particle_emitters>, meshes: {floor: Mesh, pillar: Mesh, block: Mesh, pane: Mesh}}>}
+ * @returns {Promise<ParticleWorld>}
  */
 export async function build_particle_scene() {
     await MeshoptClusterizer.ready;
 
     const scene = new Scene();
+    const dataset = new EntityComponentDataset();
+
+    dataset.registerManyComponentTypes([Transform64, TransformAttachment, GPUStateAuthority]);
 
-    scene.lights.add(make_sunlight({
+    // the scene's rows are this dataset's entities
+    scene.dataset = dataset;
+
+    place_light(scene, make_sunlight({
         intensity: 1.4,
         direction: new Vector3(0.35, -1, -0.4),
         temperature: 5200,
@@ -190,37 +228,79 @@ export async function build_particle_scene() {
         new Vector3(0.5, 2.5, 2.5)
     );
 
-    scene.add(floor);
-    scene.add(pillar);
-    scene.add(block);
-    scene.add(pane);
 
     const emitters = create_particle_emitters();
 
-    for (const node of [emitters.fire, emitters.smoke, emitters.sparks, emitters.dust, emitters.orbit]) {
-        scene.add(node);
+    // the orbit: an entity at the origin that animate_particle_scene moves
+    const orbit = dataset.createEntity();
+
+    dataset.addComponentToEntity(orbit, new Transform64());
+
+    const entities = { orbit };
+
+    for (const name of PARTICLE_EMITTER_NAMES) {
+        const entity = dataset.createEntity();
+        const [x, y, z] = PARTICLE_EMITTER_PLACEMENT[name];
+        const world = new Transform64();
+
+        if (name === "torch") {
+            // riding the orbit: the placement is the attachment's offset, and the world is the
+            // GPU's to compose from the orbit's row — nothing on this side composes it
+            const attachment = new TransformAttachment();
+
+            attachment.parent = orbit;
+            attachment.transform.setTranslation(x, y, z);
+            attachment.transform.updateMatrix();
+
+            dataset.addComponentToEntity(entity, attachment);
+
+            gpu_authority_declare(dataset, entity);
+            gpu_authority_grant(dataset, entity, GPUStateAuthorityFlags.Transform64);
+        } else {
+            world.setTranslation(x, y, z);
+            world.updateMatrix();
+        }
+
+        dataset.addComponentToEntity(entity, world);
+
+        entities[name] = entity;
     }
 
-    return { scene, emitters, meshes: { floor, pillar, block, pane } };
+    return { scene, dataset, emitters, entities, primitives: { floor, pillar, block, pane }, meshes: {} };
 }
 
 /**
- * Turn the particles on for this scene and give the system its sprite.
+ * Turn the particles on for this scene, place its emitters, and give the system its sprite.
  *
- * This is the whole integration. The emitters are already scene nodes, so there is nothing to
- * register: the system finds them the next time it sweeps, gives each a row pointed at the node's
- * `transforms` row, and the renderer records the simulation and the three AVBOIT contributions.
+ * This is the whole integration. Each entity gets its row in the renderer's context for the scene,
+ * each emitter is registered at its entity's row, and the renderer records the simulation and the
+ * three AVBOIT contributions from there. The torch's entity hangs off the orbit's, so the GPU
+ * composes the orbit's motion into every particle it spawns with nothing copied through the CPU.
  *
  * @param {import("../../renderer/Renderer.js").Renderer} renderer initialized
- * @param {Scene} scene the one {@link build_particle_scene} returned
+ * @param {ParticleWorld} world the one {@link build_particle_scene} returned
  * @returns {import("../../renderer/particles/GPUParticleSystem.js").GPUParticleSystem}
  */
-export function configure_particles(renderer, scene) {
+export function configure_particles(renderer, world) {
     renderer.transparency_mode = ShadeTransparencyMode.AVBOIT;
     renderer.feature_particles_enabled = true;
 
     const device = renderer.graphics.device;
-    const system = renderer.particles(renderer.scenes.obtain(scene));
+    const scene_context = renderer.scenes.obtain(world.scene);
+    const system = renderer.particles(scene_context);
+
+    // the set pieces take their rows here, where the context is
+    for (const [name, primitive] of Object.entries(world.primitives)) {
+        world.meshes[name] = place_primitive(scene_context, primitive.geometry, primitive.material, primitive.transform, { name });
+    }
+
+    for (const entity of Object.values(world.entities)) {
+        scene_context.rows.acquire(entity);
+    }
+
+    for (const name of PARTICLE_EMITTER_NAMES) {
+        system.add_emitter(world.emitters[name], row_of_entity(world.entities[name]));
+    }
 
     system.atlas = make_sprite_texture(device).createView();
     system.atlas_sampler = device.createSampler({
@@ -238,18 +318,24 @@ export function configure_particles(renderer, scene) {
  * Move what moves. One call, so the page's frame loop stays three lines and the motion is here
  * with the scene it belongs to.
  *
- * @param {ReturnType<create_particle_emitters>} emitters
+ * @param {ParticleWorld} world
+ * @param {import("../../renderer/particles/GPUParticleSystem.js").GPUParticleSystem} system the
+ *        one {@link configure_particles} returned; its scene context holds the orbit's row
  * @param {number} time seconds since start
  */
-export function animate_particle_scene(emitters, time) {
-    const orbit = emitters.orbit;
+export function animate_particle_scene(world, system, time) {
+    const orbit = world.entities.orbit;
+    const transform = world.dataset.getComponent(orbit, Transform64);
 
-    orbit.transform_local.setTranslation(
+    transform.setTranslation(
         Math.cos(time * 0.9) * 0.5,
         Math.sin(time * 1.7) * 0.4,
         Math.sin(time * 0.9) * 0.5
     );
-    orbit.updateMatrices();
+
+    // the row is rewritten from the transform on the next build; the torch's row, under it, is
+    // the hierarchy pass's
+    system.scene_context.rows.mark_world(orbit);
 }
 
 /**
@@ -348,14 +434,24 @@ function material(diffuse, { transparent = true } = {}) {
  * @param {Quaternion} [rotation]
  * @returns {Mesh}
  */
+/**
+ * A set piece as a description: what it draws and where it stands. It takes a row when
+ * {@link configure_particles} has the context to place it on.
+ *
+ * @param {MeshletGeometry} geometry
+ * @param {StandardShadeMaterial} material_instance
+ * @param {Vector3} position
+ * @param {Quaternion} [rotation]
+ * @returns {{geometry: MeshletGeometry, material: StandardShadeMaterial, transform: Transform64}}
+ */
 function place(geometry, material_instance, position, rotation = new Quaternion()) {
-    const mesh = Mesh.from(geometry, material_instance);
+    const transform = new Transform64();
 
-    mesh.transform_local.setTranslation(position.x, position.y, position.z);
-    mesh.transform_local.setRotation(rotation.x, rotation.y, rotation.z, rotation.w);
-    mesh.updateMatrices();
+    transform.setTranslation(position.x, position.y, position.z);
+    transform.setRotation(rotation.x, rotation.y, rotation.z, rotation.w);
+    transform.updateMatrix();
 
-    return mesh;
+    return { geometry, material: material_instance, transform };
 }
 
 // ---------------------------------------------------------------------------------------------

package/src/shade/playground/readback_crossover/index.html

@@ -0,0 +1,41 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — batched readback crossover</title>
+    <style>
+        :root { color-scheme: dark; }
+        html, body { margin: 0; background: #0d0f12; color: #d6dae0; font: 13px/1.5 ui-monospace, Consolas, monospace; }
+        main { padding: 16px 20px; max-width: 1100px; }
+        h1 { font-size: 15px; margin: 0 0 4px; }
+        p { color: #8b939f; margin: 0 0 12px; max-width: 90ch; }
+        table { border-collapse: collapse; margin-top: 12px; }
+        td, th { padding: 3px 14px 3px 0; text-align: right; white-space: nowrap; }
+        th { color: #8b939f; font-weight: normal; border-bottom: 1px solid #2b3038; }
+        td:first-child, th:first-child { text-align: left; }
+        #status { color: #e5b54a; }
+        .fail { color: #e0573e !important; }
+        .ok { color: #6fbf5b !important; }
+        #summary { margin-top: 14px; white-space: pre; color: #d6dae0; }
+    </style>
+</head>
+<body>
+<main>
+    <h1>Batched readback: where a gather stops being worth its dispatch</h1>
+    <p>
+        <code>GPUDatabaseReadback</code> can pack the ranges a frame asked for with a compute shader and
+        copy the result once, or copy each range straight out of the database. The gather pays a fixed
+        price — a descriptor buffer to fill and upload, a transient allocation, a bind group, a
+        dispatch — and buys a cheaper per-row cost with it. This measures the CPU cost of
+        <b>encoding</b> one batch on each path against a real device, which is the cost the batching
+        argument hides: the request list is itself an upload, and for one row it costs more than the
+        row is worth.
+    </p>
+    <div id="status">loading…</div>
+    <div id="device"></div>
+    <table id="results"></table>
+    <div id="summary"></div>
+</main>
+<script type="module" src="./main.js"></script>
+</body>
+</html>

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=main.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/readback_crossover/main.js"],"names":[],"mappings":""}