@woosh/meep-engine 3.11.2 → 3.12.0

package/src/engine/graphics3/animation/ClipPlayback.js

@@ -1,84 +1,84 @@
-/**
- * One entry of an {@link Animation} component's clip list, while it is being played.
- *
- * The `Animation` component says *what* to play — a name, a repeat count, a weight, a time scale —
- * and holds no clock of its own, because it is data that a level authors and a save round-trips.
- * This is the running half: where that clip is, how strongly it is contributing, and whether it has
- * run out. {@link AnimationSystem3} owns one per clip in the list and hands them out, because the
- * pose a gameplay query has to answer from is exactly this (I-4) — never a readback.
- */
-export class ClipPlayback {
-    /**
-     * The list entry being played. Its `weight`, `timeScale` and `repeatCount` are read every
-     * frame, so changing one takes effect without removing and re-adding the clip.
-     *
-     * @type {AnimationClip}
-     */
-    clip = null;
-
-    /**
-     * Which of the model instance's clips this is, by index — the same order the animation
-     * manager's registration uses, which is what makes it the lookup for both.
-     *
-     * @type {number}
-     */
-    slot = -1;
-
-    /**
-     * Seconds the clip runs for, taken from the model when the playback was created rather than
-     * read per frame: `ShadeAnimationClip.duration` walks every channel and every curve.
-     *
-     * @type {number}
-     */
-    duration = 0;
-
-    /**
-     * Time played since the clip was added to the list, scaled by {@link clip}'s time scale and
-     * **not** folded into the clip's own span — this is what says how many repeats have gone by.
-     *
-     * @type {number}
-     */
-    elapsed = 0;
-
-    /**
-     * Where the clip is playing, in seconds from its own start: wrapped while it is repeating and
-     * held at the end once it has run out. Directly what the renderer's clip record wants.
-     *
-     * @type {number}
-     */
-    time = 0;
-
-    /**
-     * The share of the pose this clip is contributing, normalized across every clip in the list —
-     * see {@link AnimationSystem3}.
-     *
-     * @type {number}
-     */
-    weight = 0;
-
-    /**
-     * Whether the clip has played out its repeat count. A looping clip never does.
-     *
-     * The clip goes on contributing afterwards, holding its last frame; what this marks is the
-     * moment `animation-event-clip-ended` was fired for it.
-     *
-     * @type {boolean}
-     */
-    finished = false;
-
-    /**
-     * @param {AnimationClip} clip
-     * @param {number} slot
-     * @param {number} duration
-     * @returns {ClipPlayback}
-     */
-    static from(clip, slot, duration) {
-        const r = new ClipPlayback();
-
-        r.clip = clip;
-        r.slot = slot;
-        r.duration = duration;
-
-        return r;
-    }
-}
+/**
+ * One entry of an {@link Animation} component's clip list, while it is being played.
+ *
+ * The `Animation` component says *what* to play — a name, a repeat count, a weight, a time scale —
+ * and holds no clock of its own, because it is data that a level authors and a save round-trips.
+ * This is the running half: where that clip is, how strongly it is contributing, and whether it has
+ * run out. {@link AnimationSystem} owns one per clip in the list and hands them out, because the
+ * pose a gameplay query has to answer from is exactly this (I-4) — never a readback.
+ */
+export class ClipPlayback {
+    /**
+     * The list entry being played. Its `weight`, `timeScale` and `repeatCount` are read every
+     * frame, so changing one takes effect without removing and re-adding the clip.
+     *
+     * @type {AnimationClip}
+     */
+    clip = null;
+
+    /**
+     * Which of the model instance's clips this is, by index — the same order the animation
+     * manager's registration uses, which is what makes it the lookup for both.
+     *
+     * @type {number}
+     */
+    slot = -1;
+
+    /**
+     * Seconds the clip runs for, taken from the model when the playback was created rather than
+     * read per frame: `ShadeAnimationClip.duration` walks every channel and every curve.
+     *
+     * @type {number}
+     */
+    duration = 0;
+
+    /**
+     * Time played since the clip was added to the list, scaled by {@link clip}'s time scale and
+     * **not** folded into the clip's own span — this is what says how many repeats have gone by.
+     *
+     * @type {number}
+     */
+    elapsed = 0;
+
+    /**
+     * Where the clip is playing, in seconds from its own start: wrapped while it is repeating and
+     * held at the end once it has run out. Directly what the renderer's clip record wants.
+     *
+     * @type {number}
+     */
+    time = 0;
+
+    /**
+     * The share of the pose this clip is contributing, normalized across every clip in the list —
+     * see {@link AnimationSystem}.
+     *
+     * @type {number}
+     */
+    weight = 0;
+
+    /**
+     * Whether the clip has played out its repeat count. A looping clip never does.
+     *
+     * The clip goes on contributing afterwards, holding its last frame; what this marks is the
+     * moment `animation-event-clip-ended` was fired for it.
+     *
+     * @type {boolean}
+     */
+    finished = false;
+
+    /**
+     * @param {AnimationClip} clip
+     * @param {number} slot
+     * @param {number} duration
+     * @returns {ClipPlayback}
+     */
+    static from(clip, slot, duration) {
+        const r = new ClipPlayback();
+
+        r.clip = clip;
+        r.slot = slot;
+        r.duration = duration;
+
+        return r;
+    }
+}

package/src/engine/graphics3/decal/graph_build_decal_clusters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_build_decal_clusters.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/decal/graph_build_decal_clusters.js"],"names":[],"mappings":"AAiGA;;;;;;;;;;;;;;;GAeG;AACH;YAFsB,MAAM;UAAQ,MAAM;gBAAc,MAAM;EAoG7D"}
+{"version":3,"file":"graph_build_decal_clusters.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/decal/graph_build_decal_clusters.js"],"names":[],"mappings":"AA+FA;;;;;;;;;;;;;;;GAeG;AACH;YAFsB,MAAM;UAAQ,MAAM;gBAAc,MAAM;EAoG7D"}

package/src/engine/graphics3/decal/graph_build_decal_clusters.js

@@ -16,12 +16,10 @@ import {
 } from "./DECAL_CLUSTER.js";
 import {
     DECAL_CLUSTER_ASSIGNMENT_SETTINGS,
-    DECAL_CLUSTER_WORKGROUP_SIZE,
     shader_cluster_assign_decals
 } from "./shader_cluster_assign_decals.js";
 import {
     DECAL_CULL_SETTINGS,
-    SHADER_CULL_DECALS_WORKGROUP_SIZE,
     shader_cull_decals_frustum
 } from "./shader_cull_decals_frustum.js";
 
@@ -75,7 +73,7 @@ function graph_cull_decals({ graph, camera, decals, decal_count }) {
         const output = resources.get(data.output);
         const settings = resources.get(data.settings);
 
-        shader_cull_decals_frustum.dispatch({
+        shader_cull_decals_frustum.dispatchThreads({
             encoder: context.encoder,
             bindings: {
                 camera: camera.buffer,
@@ -83,7 +81,7 @@ function graph_cull_decals({ graph, camera, decals, decal_count }) {
                 decal_data: decals.buffer,
                 output,
             },
-            group_count_x: Math.ceil(decal_count / SHADER_CULL_DECALS_WORKGROUP_SIZE),
+            thread_count_x: decal_count,
         });
     }
 
@@ -170,12 +168,12 @@ export function graph_build_decal_clusters({ graph, camera, decals, decal_count,
         const cluster_data = resources.get(data.cluster_data);
         const settings = resources.get(data.settings);
 
-        shader_cluster_assign_decals.dispatch({
+        shader_cluster_assign_decals.dispatchThreads({
             encoder: context.encoder,
 
-            group_count_x: Math.ceil(cluster_count_x / DECAL_CLUSTER_WORKGROUP_SIZE[0]),
-            group_count_y: Math.ceil(cluster_count_y / DECAL_CLUSTER_WORKGROUP_SIZE[1]),
-            group_count_z: Math.ceil(DECAL_CLUSTER_RESOLUTION_Z / DECAL_CLUSTER_WORKGROUP_SIZE[2]),
+            thread_count_x: cluster_count_x,
+            thread_count_y: cluster_count_y,
+            thread_count_z: DECAL_CLUSTER_RESOLUTION_Z,
 
             bindings: {
                 camera: camera.buffer,

package/src/engine/graphics3/decal/shader_cluster_assign_decals.d.ts

@@ -1,12 +1,5 @@
 export const DECAL_CLUSTER_ASSIGNMENT_SETTINGS: WebGPUStruct;
 export const DECAL_CLUSTER_LOOKUP_STRUCT: WebGPUArray;
-/**
- * Matching the light assignment's own reasoning: this shader uses a great many registers, and larger
- * workgroups mostly fail to get an allocation and sit idle.
- *
- * @type {number[]}
- */
-export const DECAL_CLUSTER_WORKGROUP_SIZE: number[];
 /**
  * Which decals cover which froxel.
  *

package/src/engine/graphics3/decal/shader_cluster_assign_decals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_cluster_assign_decals.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/decal/shader_cluster_assign_decals.js"],"names":[],"mappings":"AAuCA,6DAMG;AAiBH,sDAAoF;AAMpF;;;;;GAKG;AACH,2CAFU,MAAM,EAAE,CAEoC;AAuHtD;;;;;;;;GAQG;AACH,2CAFU,aAAa,CAMpB;6BAjL0B,qDAAqD;4BADtD,oDAAoD;8BALlD,iDAAiD"}
+{"version":3,"file":"shader_cluster_assign_decals.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/decal/shader_cluster_assign_decals.js"],"names":[],"mappings":"AAuCA,6DAMG;AAiBH,sDAAoF;AAmIpF;;;;;;;;GAQG;AACH,2CAFU,aAAa,CAMpB;6BAjL0B,qDAAqD;4BADtD,oDAAoD;8BALlD,iDAAiD"}

package/src/engine/graphics3/decal/shader_cluster_assign_decals.js

@@ -72,7 +72,7 @@ resources.createGroup({ label: "output" })
  *
  * @type {number[]}
  */
-export const DECAL_CLUSTER_WORKGROUP_SIZE = [4, 4, 4];
+const DECAL_CLUSTER_WORKGROUP_SIZE = [4, 4, 4];
 
 const body = CodeChunk.from(
     //language=WGSL

package/src/engine/graphics3/decal/shader_cull_decals_frustum.d.ts

@@ -1,7 +1,3 @@
-/**
- * @type {number}
- */
-export const SHADER_CULL_DECALS_WORKGROUP_SIZE: number;
 /**
  * Which decals are worth binning into froxels at all.
  *

package/src/engine/graphics3/decal/shader_cull_decals_frustum.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_cull_decals_frustum.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/decal/shader_cull_decals_frustum.js"],"names":[],"mappings":"AAeA;;GAEG;AACH,gDAFU,MAAM,CAEmE;AAuEnF;;;;;;;;GAQG;AACH,yCAFU,aAAa,CAMpB;AAEH;;GAEG;AACH,kCAFU,YAAY,CAE6B;8BAtGrB,iDAAiD;6BAMlD,qDAAqD"}
+{"version":3,"file":"shader_cull_decals_frustum.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/decal/shader_cull_decals_frustum.js"],"names":[],"mappings":"AAyFA;;;;;;;;GAQG;AACH,yCAFU,aAAa,CAMpB;AAEH;;GAEG;AACH,kCAFU,YAAY,CAE6B;8BAtGrB,iDAAiD;6BAMlD,qDAAqD"}

package/src/engine/graphics3/decal/shader_cull_decals_frustum.js

@@ -16,7 +16,7 @@ import { DECAL_RECORD_OFFSET_TRANSFORM, DECAL_RECORD_WORD_COUNT } from "./DECAL_
 /**
  * @type {number}
  */
-export const SHADER_CULL_DECALS_WORKGROUP_SIZE = COMPUTE_SHADER_DEFAULT_GROUP_SIZE;
+const SHADER_CULL_DECALS_WORKGROUP_SIZE = COMPUTE_SHADER_DEFAULT_GROUP_SIZE;
 
 const OUTPUT_STRUCT = WebGPUStruct.from({
     offset: atomic_u32,

package/src/engine/graphics3/highlight/pack_highlight_table.d.ts

@@ -13,7 +13,7 @@
  *
  * @param {object} args
  * @param {Array<{entity: number, highlight: Highlight}>} args.entries
- * @param {MeshSystem3} args.meshes resolves an entity to the nodes it has in the scene
+ * @param {MeshSystem} args.meshes resolves an entity to the nodes it has in the scene
  * @param {GPUSceneContext} args.scene resolves a node to its row
  * @param {Uint32Array} args.table reused between frames; replaced when it is too small
  * @returns {{table: Uint32Array, size: number}} `size` is one past the highest row written, and is
@@ -24,7 +24,7 @@ export function pack_highlight_table({ entries, meshes, scene, table }: {
         entity: number;
         highlight: Highlight;
     }>;
-    meshes: MeshSystem3;
+    meshes: MeshSystem;
     scene: GPUSceneContext;
     table: Uint32Array;
 }): {

package/src/engine/graphics3/highlight/pack_highlight_table.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pack_highlight_table.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/highlight/pack_highlight_table.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAP+D,OAAO,EAA3D,MAAM;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,YAAW;KAAC,CAAC;IAC3B,MAAM;IACF,KAAK;IACT,KAAK,EAAvB,WAAW;;WACD,WAAW;UAAQ,MAAM;EAqD7C"}
+{"version":3,"file":"pack_highlight_table.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/highlight/pack_highlight_table.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAP+D,OAAO,EAA3D,MAAM;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,YAAW;KAAC,CAAC;IAC5B,MAAM;IACD,KAAK;IACT,KAAK,EAAvB,WAAW;;WACD,WAAW;UAAQ,MAAM;EAqD7C"}

package/src/engine/graphics3/highlight/pack_highlight_table.js

@@ -1,74 +1,74 @@
-import { pack_highlight_color } from "./pack_highlight_color.js";
-
-/**
- * Build the lookup the outline shader reads: one packed colour per mesh row, addressed by the row
- * the visibility buffer writes.
- *
- * **The scene decides the indices.** A highlight is attached to an entity, an entity's model is
- * several nodes, and each node that carries geometry has a row — so the walk is entity → nodes →
- * rows, and an entity whose model has not loaded contributes none and needs no special case.
- *
- * Rebuilt every frame, which is the cheaper arrangement and not a concession: the game's highlights
- * animate colour and alpha continuously, so nothing is saved by watching for changes — and a
- * `Color`'s change signal does not fire for alpha-only edits, which is precisely what the animation
- * is.
- *
- * @param {object} args
- * @param {Array<{entity: number, highlight: Highlight}>} args.entries
- * @param {MeshSystem3} args.meshes resolves an entity to the nodes it has in the scene
- * @param {GPUSceneContext} args.scene resolves a node to its row
- * @param {Uint32Array} args.table reused between frames; replaced when it is too small
- * @returns {{table: Uint32Array, size: number}} `size` is one past the highest row written, and is
- * zero when nothing highlighted is in the scene
- */
-export function pack_highlight_table({ entries, meshes, scene, table }) {
-    let highest = -1;
-
-    /*
-     Two sweeps, because the table has to be as long as the highest row before anything can be
-     written into it and the rows are not known until the scene is asked. Asking twice is cheaper
-     than growing a typed array mid-walk, and the walk is over the handful of things highlighted
-     rather than over the scene.
-    */
-    for (let i = 0; i < entries.length; i++) {
-        meshes.traverse_meshes(entries[i].entity, node => {
-            const row = scene.mesh_row_of(node);
-
-            if (row > highest) {
-                highest = row;
-            }
-        });
-    }
-
-    const size = highest + 1;
-
-    let result = table;
-
-    if (result.length < size) {
-        result = new Uint32Array(size);
-    } else {
-        result.fill(0, 0, size);
-    }
-
-    for (let i = 0; i < entries.length; i++) {
-        const entry = entries[i];
-
-        const packed = pack_highlight_color(entry.highlight.elements);
-
-        if (packed === 0) {
-            // a highlight faded to nothing is not a highlight, and zero is what the shader reads
-            // as "no outline" anyway
-            continue;
-        }
-
-        meshes.traverse_meshes(entry.entity, node => {
-            const row = scene.mesh_row_of(node);
-
-            if (row >= 0) {
-                result[row] = packed;
-            }
-        });
-    }
-
-    return { table: result, size };
-}
+import { pack_highlight_color } from "./pack_highlight_color.js";
+
+/**
+ * Build the lookup the outline shader reads: one packed colour per mesh row, addressed by the row
+ * the visibility buffer writes.
+ *
+ * **The scene decides the indices.** A highlight is attached to an entity, an entity's model is
+ * several nodes, and each node that carries geometry has a row — so the walk is entity → nodes →
+ * rows, and an entity whose model has not loaded contributes none and needs no special case.
+ *
+ * Rebuilt every frame, which is the cheaper arrangement and not a concession: the game's highlights
+ * animate colour and alpha continuously, so nothing is saved by watching for changes — and a
+ * `Color`'s change signal does not fire for alpha-only edits, which is precisely what the animation
+ * is.
+ *
+ * @param {object} args
+ * @param {Array<{entity: number, highlight: Highlight}>} args.entries
+ * @param {MeshSystem} args.meshes resolves an entity to the nodes it has in the scene
+ * @param {GPUSceneContext} args.scene resolves a node to its row
+ * @param {Uint32Array} args.table reused between frames; replaced when it is too small
+ * @returns {{table: Uint32Array, size: number}} `size` is one past the highest row written, and is
+ * zero when nothing highlighted is in the scene
+ */
+export function pack_highlight_table({ entries, meshes, scene, table }) {
+    let highest = -1;
+
+    /*
+     Two sweeps, because the table has to be as long as the highest row before anything can be
+     written into it and the rows are not known until the scene is asked. Asking twice is cheaper
+     than growing a typed array mid-walk, and the walk is over the handful of things highlighted
+     rather than over the scene.
+    */
+    for (let i = 0; i < entries.length; i++) {
+        meshes.traverse_meshes(entries[i].entity, node => {
+            const row = scene.mesh_row_of(node);
+
+            if (row > highest) {
+                highest = row;
+            }
+        });
+    }
+
+    const size = highest + 1;
+
+    let result = table;
+
+    if (result.length < size) {
+        result = new Uint32Array(size);
+    } else {
+        result.fill(0, 0, size);
+    }
+
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+
+        const packed = pack_highlight_color(entry.highlight.elements);
+
+        if (packed === 0) {
+            // a highlight faded to nothing is not a highlight, and zero is what the shader reads
+            // as "no outline" anyway
+            continue;
+        }
+
+        meshes.traverse_meshes(entry.entity, node => {
+            const row = scene.mesh_row_of(node);
+
+            if (row >= 0) {
+                result[row] = packed;
+            }
+        });
+    }
+
+    return { table: result, size };
+}

package/src/engine/graphics3/pose/query_entity_node_world_pose.d.ts

@@ -5,7 +5,7 @@
  * where does this projectile leave from, where does that effect anchor, where does the floating UI
  * hang. **The answer is computed, never read back** — GPU readback is a frame late and asynchronous,
  * so an outcome that depended on it would depend on frame pacing, and determinism and replay would
- * go with it (`EXECUTION.md` I-4).
+ * go with it: no GPU readback on a gameplay-affecting path.
  *
  * The pose is {@link pose_evaluate_world} over the clips the animation systems are driving: a pure
  * function of (clip set, time, weights), off the same clock the renderer is written from, which is