@woosh/meep-engine 3.23.0 → 3.25.0

package/src/shade/renderer/light/LIGHT_DATABASE_SPEC.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LIGHT_DATABASE_SPEC.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/light/LIGHT_DATABASE_SPEC.js"],"names":[],"mappings":"AASA,wDAYG;sCAnBmC,0CAA0C"}
+{"version":3,"file":"LIGHT_DATABASE_SPEC.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/light/LIGHT_DATABASE_SPEC.js"],"names":[],"mappings":"AAUA,wDAiBG;sCAzBmC,0CAA0C"}

package/src/shade/renderer/light/LIGHT_DATABASE_SPEC.js

@@ -4,6 +4,7 @@ import { GPUDatabaseDefinition } from "../buffer/table/GPUDatabaseDefinition.js"
 import { DIRECTIONAL_LIGHT_STRUCT } from "../shader/chunk/light/DIRECTIONAL_LIGHT_STRUCT.js";
 import { POINT_LIGHT_STRUCT } from "../shader/chunk/light/POINT_LIGHT_STRUCT.js";
 import { SPOT_LIGHT_STRUCT } from "../shader/chunk/light/SPOT_LIGHT_STRUCT.js";
+import { CSM_CASTER_RANGE_STRUCT } from "../shadow/map/csm/CSM_CASTER_RANGE_STRUCT.js";
 import { SHADOWMAP_CSM_CASCADE_COUNT } from "../shadow/map/csm/SHADOWMAP_CSM_CASCADE_COUNT.js";
 import { SHADOWMAP_VIEW_METADATA_STRUCT } from "../shadow/map/shader/SHADOWMAP_VIEW_METADATA_STRUCT.js";
 
@@ -18,5 +19,10 @@ export const LIGHT_DATABASE_SPEC = GPUDatabaseDefinition.from({
     // SHADOWMAP_CSM_CASCADE_COUNT cascades for directional).
     shadow_point: vec4f,
     shadow_spot: SHADOWMAP_VIEW_METADATA_STRUCT,
-    shadow_directional: WebGPUArray.from(SHADOWMAP_VIEW_METADATA_STRUCT, SHADOWMAP_CSM_CASCADE_COUNT)
+    shadow_directional: WebGPUArray.from(SHADOWMAP_VIEW_METADATA_STRUCT, SHADOWMAP_CSM_CASCADE_COUNT),
+
+    // per directional shadow map, what the GPU measured of the casters in front of each cascade —
+    // written by the caster-range pass, read back to fit the next frame's near planes; one row per
+    // map, claimed and released by the shadow context
+    shadow_csm_caster_range: CSM_CASTER_RANGE_STRUCT,
 });

package/src/shade/renderer/light/LightCollection.d.ts

@@ -2,6 +2,15 @@
  * @typedef {import("../texture/ShadeTexture.js").ShadeTexture} ShadeTexture
  * @typedef {import("./model/Light.js").Light} Light
  */
+/**
+ * The lights of a scene, each at an entity, and the environment they indirect from.
+ *
+ * A light is placed by naming the entity it stands at: the entity's `transforms` row is where the
+ * GPU reads the light's pose from, and the scene's GPU context holds that row on the collection's
+ * behalf for as long as the light is here. The collection itself is CPU data — the renderer's
+ * mirror of it (`GPULightCollection`) is rebuilt whenever {@link version} moves, which adding and
+ * removing do on their own and a change in place does through {@link needsUpdate}.
+ */
 export class LightCollection {
     /**
      *
@@ -29,10 +38,17 @@ export class LightCollection {
      */
     set needsUpdate(v: boolean);
     /**
+     * Put a light in the scene, at an entity.
+     *
+     * The entity is where the light is: its `transforms` row is what the GPU reads the light's pose
+     * from. The light's own {@link Light#transform} is the CPU's copy, and is the entity's
+     * `Transform64` when the two were placed together — `place_light` does that for a caller with
+     * no ECS.
      *
      * @param {Light} light
+     * @param {number} entity
      */
-    add(light: Light): void;
+    add(light: Light, entity: number): void;
     /**
      * Remove a light. Returns true if it was found and dropped.
      *
@@ -40,6 +56,18 @@ export class LightCollection {
      * @returns {boolean}
      */
     remove(light: Light): boolean;
+    /**
+     * @param {Light} light
+     * @returns {boolean}
+     */
+    has(light: Light): boolean;
+    /**
+     * The entity a light stands at.
+     *
+     * @param {Light} light
+     * @returns {number|undefined} undefined for a light that is not here
+     */
+    entity_of(light: Light): number | undefined;
     #private;
 }
 export type ShadeTexture = import("../texture/ShadeTexture.js").ShadeTexture;

package/src/shade/renderer/light/LightCollection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LightCollection.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/light/LightCollection.js"],"names":[],"mappings":"AAGA;;;GAGG;AAEH;IAQI;;;OAGG;IACH,mDAEC;IAgBD;;;OAGG;IACH,sEAMC;IAlBD;;;OAGG;IACH,qEAEC;IAiBD;;;OAGG;IACH,sBAEC;IAED;;;OAGG;IACH,4BAIC;IAED;;;OAGG;IACH,WAFW,KAAK,QAMf;IAED;;;;;OAKG;IACH,cAHW,KAAK,GACH,OAAO,CAUnB;;CACJ;2BA5FY,OAAO,4BAA4B,EAAE,YAAY;oBACjD,OAAO,kBAAkB,EAAE,KAAK"}
+{"version":3,"file":"LightCollection.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/light/LightCollection.js"],"names":[],"mappings":"AAGA;;;GAGG;AAEH;;;;;;;;GAQG;AACH;IAeI;;;OAGG;IACH,mDAEC;IAgBD;;;OAGG;IACH,sEAMC;IAlBD;;;OAGG;IACH,qEAEC;IAiBD;;;OAGG;IACH,sBAEC;IAED;;;OAGG;IACH,4BAIC;IAED;;;;;;;;;;OAUG;IACH,WAHW,KAAK,UACL,MAAM,QAYhB;IAED;;;;;OAKG;IACH,cAHW,KAAK,GACH,OAAO,CAYnB;IAED;;;OAGG;IACH,WAHW,KAAK,GACH,OAAO,CAInB;IAED;;;;;OAKG;IACH,iBAHW,KAAK,GACH,MAAM,GAAC,SAAS,CAI5B;;CACJ;2BA7IY,OAAO,4BAA4B,EAAE,YAAY;oBACjD,OAAO,kBAAkB,EAAE,KAAK"}

package/src/shade/renderer/light/LightCollection.js

@@ -6,6 +6,15 @@ import { array_remove_first } from "../../../core/collection/array/array_remove_
  * @typedef {import("./model/Light.js").Light} Light
  */
 
+/**
+ * The lights of a scene, each at an entity, and the environment they indirect from.
+ *
+ * A light is placed by naming the entity it stands at: the entity's `transforms` row is where the
+ * GPU reads the light's pose from, and the scene's GPU context holds that row on the collection's
+ * behalf for as long as the light is here. The collection itself is CPU data — the renderer's
+ * mirror of it (`GPULightCollection`) is rebuilt whenever {@link version} moves, which adding and
+ * removing do on their own and a change in place does through {@link needsUpdate}.
+ */
 export class LightCollection {
 
     /**
@@ -14,6 +23,13 @@ export class LightCollection {
      */
     #elements = [];
 
+    /**
+     * The entity each light stands at.
+     *
+     * @type {Map<Light, number>}
+     */
+    #entities = new Map();
+
     /**
      *
      * @returns {Light[]}
@@ -70,11 +86,24 @@ export class LightCollection {
     }
 
     /**
+     * Put a light in the scene, at an entity.
+     *
+     * The entity is where the light is: its `transforms` row is what the GPU reads the light's pose
+     * from. The light's own {@link Light#transform} is the CPU's copy, and is the entity's
+     * `Transform64` when the two were placed together — `place_light` does that for a caller with
+     * no ECS.
      *
      * @param {Light} light
+     * @param {number} entity
      */
-    add(light) {
+    add(light, entity) {
+        assert.defined(light, 'light');
+        assert.equal(light.isLight, true, 'light.isLight !== true');
+        assert.isNonNegativeInteger(entity, 'entity');
+        assert.equal(this.#entities.has(light), false, 'the light is already in the scene');
+
         this.#elements.push(light);
+        this.#entities.set(light, entity);
 
         this.#version++;
     }
@@ -89,9 +118,29 @@ export class LightCollection {
         const removed = array_remove_first(this.#elements, light);
 
         if (removed) {
+            this.#entities.delete(light);
+
             this.#version++;
         }
 
         return removed;
     }
+
+    /**
+     * @param {Light} light
+     * @returns {boolean}
+     */
+    has(light) {
+        return this.#entities.has(light);
+    }
+
+    /**
+     * The entity a light stands at.
+     *
+     * @param {Light} light
+     * @returns {number|undefined} undefined for a light that is not here
+     */
+    entity_of(light) {
+        return this.#entities.get(light);
+    }
 }

package/src/shade/renderer/light/make_sunlight.js

@@ -23,8 +23,8 @@ export function make_sunlight({
     q.fromUnitVectors(Vector3.forward, direction.clone().normalize());
     q.normalize();
 
-    light.transform_local.setRotation(q.x, q.y, q.z, q.w);
-    light.updateMatrices();
+    light.transform.setRotation(q.x, q.y, q.z, q.w);
+    light.transform.updateMatrix();
 
     // light.color is treated as chromaticity — its luminance is normalized away
     // at GPU upload (see light_pack_color), so we just hand it the kelvin RGB

package/src/shade/renderer/light/model/Light.d.ts

@@ -1,4 +1,31 @@
-export class Light extends Node3D {
+/**
+ * A light: what it is and how bright, not where.
+ *
+ * Where it is comes from the entity it is placed at — {@link ../LightCollection.js#add} takes the
+ * light and the entity, and the GPU reads the light's pose from that entity's `transforms` row
+ * every frame (`shader_refresh_light_poses`), so a light under an animated joint follows it with
+ * nothing copied through the CPU. {@link transform} is the CPU's copy of that pose — the entity's
+ * own `Transform64`, the one object, when the light was placed by `LightSystem` or
+ * `place_light` — read by what the CPU builds from a light: the shadow cameras, the serializer.
+ */
+export class Light {
+    /**
+     * For a debugger, a serializer, and a shadow map's label; nothing draws differently for it.
+     *
+     * @type {string}
+     */
+    name: string;
+    /**
+     * The light's world pose: its position, and the rotation whose +Z it shines along.
+     *
+     * The entity's own `Transform64` when the light is placed at an entity that has one, so that
+     * the row and this are written from one object and there is no copy to fall behind. Exact for
+     * an entity the CPU composes; for one the GPU composes it is what the CPU last knew, which the
+     * row is not — the GPU reads the row.
+     *
+     * @type {Transform64}
+     */
+    transform: Transform64;
     /**
      * Chromaticity of the light, in linear Rec.709 RGB. Only the relative
      * R:G:B ratio is meaningful — the absolute scale (luminance) is normalized
@@ -52,6 +79,6 @@ export class Light extends Node3D {
      */
     readonly isLight: boolean;
 }
-import { Node3D } from "../../scene/Node3D.js";
+import { Transform64 } from "../../../../engine/ecs/transform/Transform64.js";
 import { Color } from "../../../../core/color/Color.js";
 //# sourceMappingURL=Light.d.ts.map

package/src/shade/renderer/light/model/Light.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Light.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/model/Light.js"],"names":[],"mappings":"AAGA;IAEI;;;;;;;;;OASG;IACH,OAFU,KAAK,CAEY;IAE3B;;;;;;;;;;;;OAYG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX;;;;OAIG;IACH,oBAFU,MAAM,CAEO;IAEvB;;;OAGG;IACH,cAFU,OAAO,CAEG;IAEpB;;;OAGG;IACH,mBAFU,MAAM,CAEO;IAEvB,mBAEC;IAGL;;;OAGG;IACH,kBAFU,OAAO,CAEM;CANtB;uBA3DsB,uBAAuB;sBADxB,iCAAiC"}
+{"version":3,"file":"Light.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/model/Light.js"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH;IACI;;;;OAIG;IACH,MAFU,MAAM,CAEN;IAEV;;;;;;;;;OASG;IACH,WAFU,WAAW,CAES;IAE9B;;;;;;;;;OASG;IACH,OAFU,KAAK,CAEY;IAE3B;;;;;;;;;;;;OAYG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX;;;;OAIG;IACH,oBAFU,MAAM,CAEO;IAEvB;;;OAGG;IACH,cAFU,OAAO,CAEG;IAEpB;;;OAGG;IACH,mBAFU,MAAM,CAEO;IAEvB,mBAEC;IAGL;;;OAGG;IACH,kBAFU,OAAO,CAEM;CANtB;4BAvF2B,iDAAiD;sBADvD,iCAAiC"}

package/src/shade/renderer/light/model/Light.js

@@ -1,7 +1,35 @@
 import { Color } from "../../../../core/color/Color.js";
-import { Node3D } from "../../scene/Node3D.js";
+import { Transform64 } from "../../../../engine/ecs/transform/Transform64.js";
 
-export class Light extends Node3D {
+/**
+ * A light: what it is and how bright, not where.
+ *
+ * Where it is comes from the entity it is placed at — {@link ../LightCollection.js#add} takes the
+ * light and the entity, and the GPU reads the light's pose from that entity's `transforms` row
+ * every frame (`shader_refresh_light_poses`), so a light under an animated joint follows it with
+ * nothing copied through the CPU. {@link transform} is the CPU's copy of that pose — the entity's
+ * own `Transform64`, the one object, when the light was placed by `LightSystem` or
+ * `place_light` — read by what the CPU builds from a light: the shadow cameras, the serializer.
+ */
+export class Light {
+    /**
+     * For a debugger, a serializer, and a shadow map's label; nothing draws differently for it.
+     *
+     * @type {string}
+     */
+    name = "";
+
+    /**
+     * The light's world pose: its position, and the rotation whose +Z it shines along.
+     *
+     * The entity's own `Transform64` when the light is placed at an entity that has one, so that
+     * the row and this are written from one object and there is no copy to fall behind. Exact for
+     * an entity the CPU composes; for one the GPU composes it is what the CPU last knew, which the
+     * row is not — the GPU reads the row.
+     *
+     * @type {Transform64}
+     */
+    transform = new Transform64();
 
     /**
      * Chromaticity of the light, in linear Rec.709 RGB. Only the relative

package/src/shade/renderer/light/model/io/light_record_directional.d.ts

@@ -7,7 +7,9 @@
  * any other light_record_* helper.
  *
  * @param {DirectionalLight} light
+ * @param {number} transform_row the `transforms` row of the light's entity, one on — where the GPU
+ *        reads the direction from every frame; the one written here is the CPU's copy of it
  * @return {*} DIRECTIONAL_LIGHT_STRUCT-shaped record
  */
-export function light_record_directional(light: DirectionalLight): any;
+export function light_record_directional(light: DirectionalLight, transform_row: number): any;
 //# sourceMappingURL=light_record_directional.d.ts.map

package/src/shade/renderer/light/model/io/light_record_directional.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"light_record_directional.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/model/io/light_record_directional.js"],"names":[],"mappings":"AAMA;;;;;;;;;;GAUG;AACH,uEAoBC"}
+{"version":3,"file":"light_record_directional.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/model/io/light_record_directional.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;GAYG;AACH,iFAJW,MAAM,OAyBhB"}

package/src/shade/renderer/light/model/io/light_record_directional.js

@@ -13,14 +13,16 @@ const _color = new Float32Array(3);
  * any other light_record_* helper.
  *
  * @param {DirectionalLight} light
+ * @param {number} transform_row the `transforms` row of the light's entity, one on — where the GPU
+ *        reads the direction from every frame; the one written here is the CPU's copy of it
  * @return {*} DIRECTIONAL_LIGHT_STRUCT-shaped record
  */
-export function light_record_directional(light) {
-    const d = light.forward;
+export function light_record_directional(light, transform_row) {
+    const d = light.transform.forward;
 
-    _direction[0] = d.x;
-    _direction[1] = d.y;
-    _direction[2] = d.z;
+    _direction[0] = d[0];
+    _direction[1] = d[1];
+    _direction[2] = d[2];
 
     light_pack_color(_color, 0, light.color, light.intensity);
 
@@ -34,5 +36,6 @@ export function light_record_directional(light) {
         flags: light_flags_pack(has_shadow),
         near_clip_distance: light.near_clip_distance,
         shadow_id: has_shadow ? shadowmap_id : 0,
+        node: transform_row,
     };
 }

package/src/shade/renderer/light/model/io/light_record_point.d.ts

@@ -7,7 +7,9 @@
  * any other light_record_* helper.
  *
  * @param {PointLight} light
+ * @param {number} transform_row the `transforms` row of the light's entity, one on — where the GPU
+ *        reads the pose from every frame; the position written here is the CPU's copy of it
  * @return {*} POINT_LIGHT_STRUCT-shaped record
  */
-export function light_record_point(light: PointLight): any;
+export function light_record_point(light: PointLight, transform_row: number): any;
 //# sourceMappingURL=light_record_point.d.ts.map

package/src/shade/renderer/light/model/io/light_record_point.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"light_record_point.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/model/io/light_record_point.js"],"names":[],"mappings":"AAMA;;;;;;;;;;GAUG;AACH,2DAqBC"}
+{"version":3,"file":"light_record_point.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/model/io/light_record_point.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;GAYG;AACH,qEAJW,MAAM,OA0BhB"}

package/src/shade/renderer/light/model/io/light_record_point.js

@@ -13,10 +13,12 @@ const _color = new Float32Array(3);
  * any other light_record_* helper.
  *
  * @param {PointLight} light
+ * @param {number} transform_row the `transforms` row of the light's entity, one on — where the GPU
+ *        reads the pose from every frame; the position written here is the CPU's copy of it
  * @return {*} POINT_LIGHT_STRUCT-shaped record
  */
-export function light_record_point(light) {
-    const t = light.transform_global;
+export function light_record_point(light, transform_row) {
+    const t = light.transform;
 
     _position[0] = t.translation_x;
     _position[1] = t.translation_y;
@@ -35,5 +37,6 @@ export function light_record_point(light) {
         flags: light_flags_pack(has_shadow),
         near_clip_distance: light.near_clip_distance,
         shadow_id: has_shadow ? shadowmap_id : 0,
+        node: transform_row,
     };
 }

package/src/shade/renderer/light/model/io/light_record_spot.d.ts

@@ -7,7 +7,10 @@
  * any other light_record_* helper.
  *
  * @param {SpotLight} light
+ * @param {number} transform_row the `transforms` row of the light's entity, one on — where the GPU
+ *        reads the pose from every frame; the position and direction written here are the CPU's
+ *        copy of it
  * @return {*} SPOT_LIGHT_STRUCT-shaped record
  */
-export function light_record_spot(light: SpotLight): any;
+export function light_record_spot(light: SpotLight, transform_row: number): any;
 //# sourceMappingURL=light_record_spot.d.ts.map

package/src/shade/renderer/light/model/io/light_record_spot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"light_record_spot.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/model/io/light_record_spot.js"],"names":[],"mappings":"AAOA;;;;;;;;;;GAUG;AACH,yDA8BC"}
+{"version":3,"file":"light_record_spot.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/model/io/light_record_spot.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;GAaG;AACH,mEALW,MAAM,OAoChB"}

package/src/shade/renderer/light/model/io/light_record_spot.js

@@ -14,19 +14,22 @@ const _color = new Float32Array(3);
  * any other light_record_* helper.
  *
  * @param {SpotLight} light
+ * @param {number} transform_row the `transforms` row of the light's entity, one on — where the GPU
+ *        reads the pose from every frame; the position and direction written here are the CPU's
+ *        copy of it
  * @return {*} SPOT_LIGHT_STRUCT-shaped record
  */
-export function light_record_spot(light) {
-    const t = light.transform_global;
-    const d = light.forward;
+export function light_record_spot(light, transform_row) {
+    const t = light.transform;
+    const d = t.forward;
 
     _position[0] = t.translation_x;
     _position[1] = t.translation_y;
     _position[2] = t.translation_z;
 
-    _direction[0] = d.x;
-    _direction[1] = d.y;
-    _direction[2] = d.z;
+    _direction[0] = d[0];
+    _direction[1] = d[1];
+    _direction[2] = d[2];
 
     light_pack_color(_color, 0, light.color, light.intensity);
 
@@ -45,5 +48,6 @@ export function light_record_spot(light) {
         flags: light_flags_pack(has_shadow),
         near_clip_distance: light.near_clip_distance,
         shadow_id: has_shadow ? shadowmap_id : 0,
+        node: transform_row,
     };
 }

package/src/shade/renderer/light/place_light.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Give a light an entity to stand at, and put it in the scene's lights there.
+ *
+ * A light is where its entity's `transforms` row says, so a light needs an entity: this makes one
+ * in the scene's dataset, carrying the light's own {@link Light#transform} as its `Transform64` —
+ * the one object, so what the light was aimed with is what the row is written from — and
+ * registers the light at it. For a caller with no ECS of its own: a playground, a preview, a
+ * loader. An engine places its lights through `LightSystem`, which does the same for an entity it
+ * was handed.
+ *
+ * @param {import("../scene/Scene.js").Scene} scene bound to a dataset
+ * @param {import("./model/Light.js").Light} light
+ * @returns {number} the entity
+ */
+export function place_light(scene: import("../scene/Scene.js").Scene, light: import("./model/Light.js").Light): number;
+//# sourceMappingURL=place_light.d.ts.map

package/src/shade/renderer/light/place_light.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"place_light.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/light/place_light.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AACH,mCAJW,OAAO,mBAAmB,EAAE,KAAK,SACjC,OAAO,kBAAkB,EAAE,KAAK,GAC9B,MAAM,CAoBlB"}

package/src/shade/renderer/light/place_light.js

@@ -0,0 +1,36 @@
+import { assert } from "../../../core/assert.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+
+/**
+ * Give a light an entity to stand at, and put it in the scene's lights there.
+ *
+ * A light is where its entity's `transforms` row says, so a light needs an entity: this makes one
+ * in the scene's dataset, carrying the light's own {@link Light#transform} as its `Transform64` —
+ * the one object, so what the light was aimed with is what the row is written from — and
+ * registers the light at it. For a caller with no ECS of its own: a playground, a preview, a
+ * loader. An engine places its lights through `LightSystem`, which does the same for an entity it
+ * was handed.
+ *
+ * @param {import("../scene/Scene.js").Scene} scene bound to a dataset
+ * @param {import("./model/Light.js").Light} light
+ * @returns {number} the entity
+ */
+export function place_light(scene, light) {
+    assert.defined(scene, 'scene');
+    assert.equal(scene.isScene, true, 'scene.isScene !== true');
+    assert.equal(light.isLight, true, 'light.isLight !== true');
+
+    const dataset = scene.dataset;
+
+    assert.ok(dataset !== null && dataset !== undefined, 'the scene names no dataset, and a light is an entity of one');
+
+    dataset.registerManyComponentTypes([Transform64]);
+
+    const entity = dataset.createEntity();
+
+    dataset.addComponentToEntity(entity, light.transform);
+
+    scene.lights.add(light, entity);
+
+    return entity;
+}

package/src/shade/renderer/light/shader_refresh_light_poses.d.ts

@@ -0,0 +1,44 @@
+export const REFRESH_LIGHT_POSES_WORKGROUP_SIZE: number;
+/**
+ * Which light table a workgroup along `y` of the dispatch walks.
+ */
+export type REFRESH_LIGHT_POSES_TABLE = number;
+/**
+ * Which light table a workgroup along `y` of the dispatch walks.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const REFRESH_LIGHT_POSES_TABLE: Readonly<{
+    POINT: 0;
+    SPOT: 1;
+    DIRECTIONAL: 2;
+}>;
+/** The dispatch is three tables wide. */
+export const REFRESH_LIGHT_POSES_TABLE_COUNT: 3;
+/**
+ * Write every light record's pose from the `transforms` row it names — after the hierarchy pass
+ * has composed that row's `global`.
+ *
+ * **This is what makes a light's pose the GPU's.** A light is an entity, and its record's `node`
+ * is that entity's row. The row's `global` is composed on the GPU from its TRS and its parent
+ * chain, and once an ancestor can be GPU-driven — a torch in an animated hand — nothing on the
+ * CPU holds the world transform the record would need. So the pose is taken where the transform
+ * is: a point light's `position` is the row's translation, a directional light's `direction` is
+ * the row's +Z, a spot light's both; once per light per frame, over each table's pages rather
+ * than over `[0, count)`, because rows are addresses and a live one can sit above any number of
+ * holes.
+ *
+ * The CPU still writes the same fields when it builds a record, from the entity's own transform
+ * — exact for an entity the CPU composes, and what a pass that runs before this one in a frame
+ * reads. This pass is what makes them right for the entity the CPU does not compose, and it runs
+ * every frame because the hierarchy pass does.
+ *
+ * Runs after the hierarchy pass and before anything reads a light. The dispatch is
+ * {@link REFRESH_LIGHT_POSES_TABLE_COUNT} workgroups wide along `y`, one table each, and along
+ * `x` as many as the widest table's {@link GPUTypedTable#dispatch_group_count} at
+ * {@link REFRESH_LIGHT_POSES_WORKGROUP_SIZE}; a workgroup past a table's pages bails at setup.
+ */
+export const shader_refresh_light_poses: ComputeShader;
+import { ComputeShader } from "../shader/ComputeShader.js";
+//# sourceMappingURL=shader_refresh_light_poses.d.ts.map

package/src/shade/renderer/light/shader_refresh_light_poses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_refresh_light_poses.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/light/shader_refresh_light_poses.js"],"names":[],"mappings":"AASA,wDAAoF;;;;wCAM1E,MAAM;AAJhB;;;;;GAKG;AACH;;;;GAIG;AAEH,yCAAyC;AACzC,gDAAiD;AAoBjD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,uDAsFG;8BArJ2B,4BAA4B"}