@woosh/meep-engine 3.1.0 → 3.3.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 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;
+    }
+}

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

@@ -1,23 +1,23 @@
-/**
- * Fold a monotonically advancing clock into the span a clip covers.
- *
- * The same arithmetic Shade's own tick shader does, and on the same side of the wrap: a looping clip
- * wraps by positive modulo, a one-shot clamps at its end and stays there. The result is directly
- * what the renderer's clip record wants, and what a pose query has to be asked at.
- *
- * @param {number} time
- * @param {number} duration
- * @param {boolean} repeat
- * @returns {number}
- */
-export function wrap_clip_time(time, duration, repeat) {
-    if (duration <= 0) {
-        return 0;
-    }
-
-    if (!repeat) {
-        return Math.min(time, duration);
-    }
-
-    return time - Math.floor(time / duration) * duration;
-}
+/**
+ * Fold a monotonically advancing clock into the span a clip covers.
+ *
+ * The same arithmetic Shade's own tick shader does, and on the same side of the wrap: a looping clip
+ * wraps by positive modulo, a one-shot clamps at its end and stays there. The result is directly
+ * what the renderer's clip record wants, and what a pose query has to be asked at.
+ *
+ * @param {number} time
+ * @param {number} duration
+ * @param {boolean} repeat
+ * @returns {number}
+ */
+export function wrap_clip_time(time, duration, repeat) {
+    if (duration <= 0) {
+        return 0;
+    }
+
+    if (!repeat) {
+        return Math.min(time, duration);
+    }
+
+    return time - Math.floor(time / duration) * duration;
+}

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

@@ -1,48 +1,48 @@
-import { assert } from "../../../core/assert.js";
-
-/**
- * Hand one graph's blend down to the renderer: what each of its clips weighs, and where each of the
- * audible ones is playing.
- *
- * **Time is written every frame and weight only when it moves.** The clock is the reason this
- * function exists — Shade can advance a clip itself and is never asked to, because the pose gameplay
- * reads and the pose on the screen have to be the same one (I-4) — while a graph sitting in one
- * state has the same weights it had last frame and there is nothing to say. `set_playback_weight`
- * and `set_time` both go through the clip table's upload dedupe, so a repeated value costs a
- * comparison rather than a transfer; skipping the unchanged weights is about not doing the read
- * either.
- *
- * A clip at zero weight has its time left alone. It contributes nothing wherever it is, and where it
- * is, is where the state that owns it stopped.
- *
- * @param {GPUAnimationManager} manager
- * @param {AnimationGraphController} controller
- * @param {Int32Array} clip_ids the manager's id for each of `controller.def.clipIndex`, in order
- * @param {Float32Array} written the weight each of those clips was last given; updated in place.
- * A value no weight can take — `-1` — is how a caller says it does not know, which is the case
- * after a renderer restart
- */
-export function write_graph_playback(manager, controller, clip_ids, written) {
-    assert.defined(manager, 'manager');
-    assert.defined(controller, 'controller');
-
-    const weights = controller.blendState.weights;
-
-    assert.equal(clip_ids.length, weights.length, 'clip_ids.length');
-    assert.equal(written.length, weights.length, 'written.length');
-
-    for (let i = 0; i < weights.length; i++) {
-        const clip_id = clip_ids[i];
-        const weight = weights[i];
-
-        if (weight !== written[i]) {
-            manager.set_playback_weight(clip_id, weight);
-
-            written[i] = weight;
-        }
-
-        if (weight > 0) {
-            manager.set_time(clip_id, controller.clip_time(i));
-        }
-    }
-}
+import { assert } from "../../../core/assert.js";
+
+/**
+ * Hand one graph's blend down to the renderer: what each of its clips weighs, and where each of the
+ * audible ones is playing.
+ *
+ * **Time is written every frame and weight only when it moves.** The clock is the reason this
+ * function exists — Shade can advance a clip itself and is never asked to, because the pose gameplay
+ * reads and the pose on the screen have to be the same one (I-4) — while a graph sitting in one
+ * state has the same weights it had last frame and there is nothing to say. `set_playback_weight`
+ * and `set_time` both go through the clip table's upload dedupe, so a repeated value costs a
+ * comparison rather than a transfer; skipping the unchanged weights is about not doing the read
+ * either.
+ *
+ * A clip at zero weight has its time left alone. It contributes nothing wherever it is, and where it
+ * is, is where the state that owns it stopped.
+ *
+ * @param {GPUAnimationManager} manager
+ * @param {AnimationGraphController} controller
+ * @param {Int32Array} clip_ids the manager's id for each of `controller.def.clipIndex`, in order
+ * @param {Float32Array} written the weight each of those clips was last given; updated in place.
+ * A value no weight can take — `-1` — is how a caller says it does not know, which is the case
+ * after a renderer restart
+ */
+export function write_graph_playback(manager, controller, clip_ids, written) {
+    assert.defined(manager, 'manager');
+    assert.defined(controller, 'controller');
+
+    const weights = controller.blendState.weights;
+
+    assert.equal(clip_ids.length, weights.length, 'clip_ids.length');
+    assert.equal(written.length, weights.length, 'written.length');
+
+    for (let i = 0; i < weights.length; i++) {
+        const clip_id = clip_ids[i];
+        const weight = weights[i];
+
+        if (weight !== written[i]) {
+            manager.set_playback_weight(clip_id, weight);
+
+            written[i] = weight;
+        }
+
+        if (weight > 0) {
+            manager.set_time(clip_id, controller.clip_time(i));
+        }
+    }
+}

package/src/engine/graphics3/camera_sync_from_transform.js

@@ -1,29 +1,29 @@
-import { assert } from "../../core/assert.js";
-
-/**
- * Point a Shade camera at whatever an entity's transform says.
- *
- * **There is no inversion here, and that is the whole content of this function.** Driving a three
- * camera required one — the legacy camera system inverted the orientation, on the grounds that
- * three's camera points the opposite way to a normal object. Shade takes the object
- * convention instead: forward *is* the viewing direction. Phase 1.5 measured that rather than
- * assuming it — with the orientation `Transform.lookAt` produces, 64 of 64 instances landed inside
- * Shade's frustum, and inverted, 0 of 64.
- *
- * So the sync is a copy. What makes it worth a named function is that copying is the *surprising*
- * answer: anyone porting camera code from the three path will arrive carrying an inversion, and
- * this is where they find out not to.
- *
- * The camera's matrices are refreshed, so what is read afterwards is this pose and not the last.
- *
- * @param {Camera} camera
- * @param {Transform} transform
- */
-export function camera_sync_from_transform(camera, transform) {
-    assert.defined(camera, 'camera');
-    assert.defined(transform, 'transform');
-
-    camera.transform.copy(transform);
-
-    camera.update();
-}
+import { assert } from "../../core/assert.js";
+
+/**
+ * Point a Shade camera at whatever an entity's transform says.
+ *
+ * **There is no inversion here, and that is the whole content of this function.** Driving a three
+ * camera required one — the legacy camera system inverted the orientation, on the grounds that
+ * three's camera points the opposite way to a normal object. Shade takes the object
+ * convention instead: forward *is* the viewing direction. Phase 1.5 measured that rather than
+ * assuming it — with the orientation `Transform.lookAt` produces, 64 of 64 instances landed inside
+ * Shade's frustum, and inverted, 0 of 64.
+ *
+ * So the sync is a copy. What makes it worth a named function is that copying is the *surprising*
+ * answer: anyone porting camera code from the three path will arrive carrying an inversion, and
+ * this is where they find out not to.
+ *
+ * The camera's matrices are refreshed, so what is read afterwards is this pose and not the last.
+ *
+ * @param {Camera} camera
+ * @param {Transform} transform
+ */
+export function camera_sync_from_transform(camera, transform) {
+    assert.defined(camera, 'camera');
+    assert.defined(transform, 'transform');
+
+    camera.transform.copy(transform);
+
+    camera.update();
+}

package/src/engine/graphics3/debug/gizmo_view_from_camera.js

@@ -1,48 +1,48 @@
-import { assert } from "../../../core/assert.js";
-
-/**
- * Fill `view` with how `camera` is looking at the frame, which is everything
- * {@link gizmo_write_geometry} needs to give a line a width in pixels.
- *
- * **The displayed height, not the rendered one.** A width measured on the display is what a caller
- * setting a line width means, and taking the height from there is what makes the internal render
- * resolution cancel out of the arithmetic — so neither the device pixel ratio nor the resolution
- * controller changes how thick a line looks.
- *
- * Written into a view the caller owns rather than returned, because this runs once per frame per
- * pass and the object has no life outside it.
- *
- * @param {GizmoView} view
- * @param {Camera} camera
- * @param {number} viewport_height the height the frame is displayed at, in CSS pixels
- * @param {number} line_width in those same pixels
- */
-export function gizmo_view_from_camera(view, camera, viewport_height, line_width) {
-    assert.defined(view, 'view');
-    assert.defined(camera, 'camera');
-    assert.isNumber(viewport_height, 'viewport_height');
-    assert.isNumber(line_width, 'line_width');
-
-    const position = camera.transform.position;
-
-    view.eye[0] = position.x;
-    view.eye[1] = position.y;
-    view.eye[2] = position.z;
-
-    /*
-     The third row of the view matrix is the direction view depth grows *away* from, whichever way
-     the camera's own basis is wound — so negating it gives the direction the camera looks along
-     without this having to know that convention.
-    */
-    const view_matrix = camera.view_matrix;
-
-    view.forward[0] = -view_matrix[2];
-    view.forward[1] = -view_matrix[6];
-    view.forward[2] = -view_matrix[10];
-
-    // element 5 of a perspective projection is `1 / tan(vertical_fov / 2)`
-    view.projection_scale = camera.projection_matrix[5];
-
-    view.viewport_height = viewport_height;
-    view.line_width = line_width;
-}
+import { assert } from "../../../core/assert.js";
+
+/**
+ * Fill `view` with how `camera` is looking at the frame, which is everything
+ * {@link gizmo_write_geometry} needs to give a line a width in pixels.
+ *
+ * **The displayed height, not the rendered one.** A width measured on the display is what a caller
+ * setting a line width means, and taking the height from there is what makes the internal render
+ * resolution cancel out of the arithmetic — so neither the device pixel ratio nor the resolution
+ * controller changes how thick a line looks.
+ *
+ * Written into a view the caller owns rather than returned, because this runs once per frame per
+ * pass and the object has no life outside it.
+ *
+ * @param {GizmoView} view
+ * @param {Camera} camera
+ * @param {number} viewport_height the height the frame is displayed at, in CSS pixels
+ * @param {number} line_width in those same pixels
+ */
+export function gizmo_view_from_camera(view, camera, viewport_height, line_width) {
+    assert.defined(view, 'view');
+    assert.defined(camera, 'camera');
+    assert.isNumber(viewport_height, 'viewport_height');
+    assert.isNumber(line_width, 'line_width');
+
+    const position = camera.transform.position;
+
+    view.eye[0] = position.x;
+    view.eye[1] = position.y;
+    view.eye[2] = position.z;
+
+    /*
+     The third row of the view matrix is the direction view depth grows *away* from, whichever way
+     the camera's own basis is wound — so negating it gives the direction the camera looks along
+     without this having to know that convention.
+    */
+    const view_matrix = camera.view_matrix;
+
+    view.forward[0] = -view_matrix[2];
+    view.forward[1] = -view_matrix[6];
+    view.forward[2] = -view_matrix[10];
+
+    // element 5 of a perspective projection is `1 / tan(vertical_fov / 2)`
+    view.projection_scale = camera.projection_matrix[5];
+
+    view.viewport_height = viewport_height;
+    view.line_width = line_width;
+}

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

@@ -1,61 +1,61 @@
-import { u32 } from "../../../shade/renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUStruct } from "../../../shade/renderer/shader/type/WebGPUStruct.js";
-import {
-    LIGHT_CLUSTER_RESOLUTION_Z,
-    LIGHT_CLUSTER_TILE_RESOLUTION
-} from "../../../shade/renderer/light/cluster/LIGHT_CLUSTER_RESOLUTION.js";
-
-/**
- * The decal froxel grid has **the lighting grid's shape**, and that is forced rather than chosen:
- * `chunk_light_cluster_resolution_xy_from_screen` and `chunk_cluster_from_fragment_coord` bake the
- * tile size and slice count into their WGSL, so reusing them — which is the whole point of decals
- * having froxels at all (D24) — fixes the geometry to match. Separate buffers, identical shape.
- *
- * @type {number}
- */
-export const DECAL_CLUSTER_TILE_RESOLUTION = LIGHT_CLUSTER_TILE_RESOLUTION;
-
-/**
- * @type {number}
- */
-export const DECAL_CLUSTER_RESOLUTION_Z = LIGHT_CLUSTER_RESOLUTION_Z;
-
-/**
- * How many decals one froxel may hold.
- *
- * Smaller than the light limit on purpose. A froxel crowded with lights is a lit scene; a froxel
- * crowded with decals is a pile of surface overrides where all but the last few are invisible, so
- * the tail costs work and changes nothing.
- *
- * @type {number}
- */
-export const DECAL_CLUSTER_LOCAL_LIMIT = 32;
-
-/**
- * What a froxel says about the decals it holds.
- *
- * Its own struct rather than {@link LIGHT_CLUSTER_METADATA}, whose `counts` word packs a count per
- * light type and reserves its upper half for decals sharing that set — which is not the arrangement
- * D24 chose. Decals have one type and their own set, so a count is a count.
- */
-export const DECAL_CLUSTER_METADATA = WebGPUStruct.from({
-    /**
-     * How many decals this froxel holds.
-     */
-    count: u32,
-
-    /**
-     * Where this froxel's run starts in the flat index list.
-     */
-    offset: u32,
-});
-
-/**
- * Most decals in a frame, after culling.
- *
- * The `-1` leaves room for the count word the list carries in front of itself while keeping the
- * whole thing aligned — the same arrangement the light cull uses.
- *
- * @type {number}
- */
-export const DECAL_CULL_LIMIT = 4095;
+import { u32 } from "../../../shade/renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../shade/renderer/shader/type/WebGPUStruct.js";
+import {
+    LIGHT_CLUSTER_RESOLUTION_Z,
+    LIGHT_CLUSTER_TILE_RESOLUTION
+} from "../../../shade/renderer/light/cluster/LIGHT_CLUSTER_RESOLUTION.js";
+
+/**
+ * The decal froxel grid has **the lighting grid's shape**, and that is forced rather than chosen:
+ * `chunk_light_cluster_resolution_xy_from_screen` and `chunk_cluster_from_fragment_coord` bake the
+ * tile size and slice count into their WGSL, so reusing them — which is the whole point of decals
+ * having froxels at all (D24) — fixes the geometry to match. Separate buffers, identical shape.
+ *
+ * @type {number}
+ */
+export const DECAL_CLUSTER_TILE_RESOLUTION = LIGHT_CLUSTER_TILE_RESOLUTION;
+
+/**
+ * @type {number}
+ */
+export const DECAL_CLUSTER_RESOLUTION_Z = LIGHT_CLUSTER_RESOLUTION_Z;
+
+/**
+ * How many decals one froxel may hold.
+ *
+ * Smaller than the light limit on purpose. A froxel crowded with lights is a lit scene; a froxel
+ * crowded with decals is a pile of surface overrides where all but the last few are invisible, so
+ * the tail costs work and changes nothing.
+ *
+ * @type {number}
+ */
+export const DECAL_CLUSTER_LOCAL_LIMIT = 32;
+
+/**
+ * What a froxel says about the decals it holds.
+ *
+ * Its own struct rather than {@link LIGHT_CLUSTER_METADATA}, whose `counts` word packs a count per
+ * light type and reserves its upper half for decals sharing that set — which is not the arrangement
+ * D24 chose. Decals have one type and their own set, so a count is a count.
+ */
+export const DECAL_CLUSTER_METADATA = WebGPUStruct.from({
+    /**
+     * How many decals this froxel holds.
+     */
+    count: u32,
+
+    /**
+     * Where this froxel's run starts in the flat index list.
+     */
+    offset: u32,
+});
+
+/**
+ * Most decals in a frame, after culling.
+ *
+ * The `-1` leaves room for the count word the list carries in front of itself while keeping the
+ * whole thing aligned — the same arrangement the light cull uses.
+ *
+ * @type {number}
+ */
+export const DECAL_CULL_LIMIT = 4095;