@woosh/meep-engine 3.11.3 → 3.13.0

package/README.md

@@ -1,7 +1,7 @@
 # Meep Engine
 **A pure-JavaScript, data-oriented game engine for WebGPU.**
 
-A library you import from and drive in code — no native bindings, no editor-first workflow. Built over 10+ years, shipped in commercial Steam releases, and held to ~13,400 tests across ~2,100 spec files, determinism and adversarial suites among them.
+A library you import from and drive in code - no native bindings, no editor-first workflow. Built over 10+ years, shipped in commercial Steam releases, and held to ~13,400 tests across ~2,100 spec files, determinism and adversarial suites among them.
 
 **Proprietary and source-available.** You get all ~6,000 fine-grained ES modules, unobfuscated, under a licence that lets you ship. Need a lerp function? Import the module that holds it and pay for those four lines.
 
@@ -9,16 +9,12 @@ A library you import from and drive in code — no native bindings, no editor-fi
 
 ---
 
-## Requirements & Installation
-
-**WebGPU**, with `indirect-first-instance`, `float32-blendable`, ≥10 storage buffers per shader stage, and ≥32 colour-attachment bytes per sample. No WebGL fallback and no degradation tiers: hardware below that floor gets a clean failure message rather than a lesser picture.
+## Installation
 
 ```shell
 npm install @woosh/meep-engine
 ```
 
-`dat.gui` is a required peer dependency, `stats.js` an optional one. Node 24+.
-
 **Coming from 2.x?** [Migration guide](MIGRATION_2_TO_3.md) · [Changelog](CHANGELOG.md).
 
 ---
@@ -26,7 +22,7 @@ npm install @woosh/meep-engine
 ## 💎 Architecture: Pure ECS
 
 * **Strict data-oriented design:** one component instance per type per entity. That constraint is what keeps memory layout and query paths predictable.
-* **Hierarchy without a scene graph:** `ParentEntity` and `EntityNode` give you the composability of a scene graph on top of flat component storage — the thing pure-ECS architectures usually punt on.
+* **Hierarchy without a scene graph:** `ParentEntity` and `EntityNode` give you the composability of a scene graph on top of flat component storage - the thing pure-ECS architectures usually punt on.
 * **Tiered access:** abstraction layers for gameplay logic, raw typed arrays underneath. Physics bodies, geometry and transforms are all backed by them; the component store itself is index-addressed rather than a flat typed array.
 * **Allocation-conscious throughout:** pooling, SoA storage and reuse on the hot paths, so frame times stay flat instead of sawtoothing against the collector.
 
@@ -35,7 +31,7 @@ npm install @woosh/meep-engine
 ## ⚡ Rendering: Shade
 GPU-driven and visibility-buffer deferred. Geometry is clustered into meshlets ahead of time and lives GPU-resident in one buffer; culling runs on the GPU; the rasterizer writes a visibility buffer and a G-buffer rather than shading as it draws; lights are binned into froxels and applied deferred; the result is temporally resolved, upscaled, tonemapped and presented.
 
-**→ [The renderer contract](src/shade/RENDERER_CONTRACT.md)** — what it promises, how to put a model on the screen, and how to add your own work to the frame.
+**→ [The renderer contract](src/shade/RENDERER_CONTRACT.md)** - what it promises, how to put a model on the screen, and how to add your own work to the frame.
 
 * **Lighting:** clustered point and spot lights, shadows, ReSTIR DI, brick4 volumetric GI.
 
@@ -51,7 +47,7 @@ GPU-driven and visibility-buffer deferred. Geometry is clustered into meshlets a
 
 * **Path tracing:** a GPU path tracer in Shade, and a separate CPU one that runs off the engine's own BVH.
 
-* **Extensible frames:** your own work goes in as a *render extension* — a declared phase, declared ordering, typed per-frame records — rather than as a patch to the pipeline.
+* **Extensible frames:** your own work goes in as a *render extension* - a declared phase, declared ordering, typed per-frame records - rather than as a patch to the pipeline.
 
 * **Picking** is asynchronous and batched (`PickingQuery`); there is no synchronous entry point.
 
@@ -62,7 +58,7 @@ Deliberately absent: compressed textures (DDS, Draco, Basis), double-sided drawi
 ---
 
 ## ⚙️ Physics
-Deterministic rigid bodies in pure JS — no WASM, no worker threads — built for replay-stable netcode and scenes with millions of mostly-sleeping bodies.
+Deterministic rigid bodies in pure JS - no WASM, no worker threads - built for replay-stable netcode and scenes with millions of mostly-sleeping bodies.
 
 * **At scale:** SoA body pool, two-tree BVH broadphase, sequential-impulse solver with warm starting, island-based atomic sleep/wake.
 
@@ -75,9 +71,9 @@ Deterministic rigid bodies in pure JS — no WASM, no worker threads — built f
 * **Inverse kinematics:** FABRIK and analytic two-joint solvers.
 
 ## 🔊 Audio
-A data-driven sound engine built on Wwise / FMOD concepts — without the opaque middleware banks.
+A data-driven sound engine built on Wwise / FMOD concepts - without the opaque middleware banks.
 
-* **The middleware feature set:** events, a mixer bus tree, RTPC parameters, voice stealing, mixer snapshots and ducking — all authored as serializable engine data.
+* **The middleware feature set:** events, a mixer bus tree, RTPC parameters, voice stealing, mixer snapshots and ducking - all authored as serializable engine data.
 
 * **Two entry points:** `AudioEmitter` puts a sound on an entity; `AudioEventTrigger` fires authored events in response to entity events.
 
@@ -89,7 +85,7 @@ A data-driven sound engine built on Wwise / FMOD concepts — without the opaque
 
 * **Server-authoritative rollback:** client-side prediction and reconciliation over action-log replication and binary snapshots.
 
-* **Pluggable transports:** WebRTC DataChannel, WebTransport, WebSocket and Node UDP — plus loopback and simulated transports for tests — with ack-based reliability, MTU fragmentation and per-peer scope filtering.
+* **Pluggable transports:** WebRTC DataChannel, WebTransport, WebSocket and Node UDP - plus loopback and simulated transports for tests - with ack-based reliability, MTU fragmentation and per-peer scope filtering.
 
 * **Diagnostics:** bandwidth metering, packet record/replay, cross-peer desync detection.
 
@@ -110,9 +106,9 @@ A data-driven sound engine built on Wwise / FMOD concepts — without the opaque
 
 ## 📦 Assets & Codecs
 
-* **Models:** glTF, including `KHR_meshopt_compression`. A model file expands into **entities** — `ShadedGeometry` on the nodes that draw — rather than living as a tree inside one component.
+* **Models:** glTF, including `KHR_meshopt_compression`. A model file expands into **entities** - `ShadedGeometry` on the nodes that draw - rather than living as a tree inside one component.
 
-* **Images, decoded in-engine:** PNG (every bit depth and filter), JPEG, and AVIF — a from-scratch AV1 intra encoder and decoder in pure JavaScript with rate-distortion mode search, and no WebAssembly. `NativeImageDecoder` prefers the browser's own decoder where there is one and falls back to these.
+* **Images, decoded in-engine:** PNG (every bit depth and filter), JPEG, and AVIF - a from-scratch AV1 intra encoder and decoder in pure JavaScript with rate-distortion mode search, and no WebAssembly. `NativeImageDecoder` prefers the browser's own decoder where there is one and falls back to these.
 
 * **Streaming:** web-first asset streaming. The engine runs before assets even load.
 
@@ -124,7 +120,7 @@ A data-driven sound engine built on Wwise / FMOD concepts — without the opaque
 
 * **In-app editor** (`editor/`), opt-in through `enableEditor(engine)`: entity inspection, gizmo tools, particle authoring, docked panels, layout persistence. It attaches to and detaches from a running `Engine`.
 
-* **GPU profile capture:** hand the renderer a `GPUProfileSession` and it writes `.sgpt` captures — pass timings, frame graph structure, dispatch and draw counts. Writer and reader both ship, and the container is specified in [`SGPT_FORMAT.md`](src/shade/device/timing/profile/SGPT_FORMAT.md); a viewer is distributed separately. Nothing reaches the capture code unless you import it, so an application that never profiles does not carry it.
+* **GPU profile capture:** hand the renderer a `GPUProfileSession` and it writes `.sgpt` captures - pass timings, frame graph structure, dispatch and draw counts. Writer and reader both ship, and the container is specified in [`SGPT_FORMAT.md`](src/shade/device/timing/profile/SGPT_FORMAT.md); a viewer is distributed separately. Nothing reaches the capture code unless you import it, so an application that never profiles does not carry it.
 
 * **Software GPU device:** a validating software WebGPU implementation and a WGSL interpreter under `src/shade/device/mock/`, so your own shaders and pipelines can run on a machine with no GPU.
 
@@ -132,7 +128,7 @@ A data-driven sound engine built on Wwise / FMOD concepts — without the opaque
 
 ## 🔬 Shipping a build
 
-The engine carries ~6,000 assertions. They throw while you develop, and [`@rollup/plugin-strip`](https://github.com/rollup/plugins/tree/master/packages/strip) takes them out of a production build — its defaults already cover `assert.*`:
+The engine carries ~6,000 assertions. They throw while you develop, and [`@rollup/plugin-strip`](https://github.com/rollup/plugins/tree/master/packages/strip) takes them out of a production build - its defaults already cover `assert.*`:
 
 ```js
 // vite.config.js
@@ -161,7 +157,7 @@ export default defineConfig({
 ## License & Copyright
 Copyright © 2026 Company Named Limited. All rights reserved.
 
-**Free for small projects.** You can build and ship commercially at no cost for as long as a project stays under US$50,000 in funding and US$50,000 in revenue. Evaluating the engine and building internal prototypes are free whatever your funding. Paid tiers — Indie, Standard, and Enterprise — raise that ceiling for a one-time fee per project, and add 24 months of major-version coverage.
+**Free for small projects.** You can build and ship commercially at no cost for as long as a project stays under US$50,000 in funding and US$50,000 in revenue. Evaluating the engine and building internal prototypes are free whatever your funding. Paid tiers - Indie, Standard, and Enterprise - raise that ceiling for a one-time fee per project, and add 24 months of major-version coverage.
 
 Short version: ship anything you like, just don't redistribute the source and don't build a competing engine.
 

package/editor/SelectionVisualizer.js

@@ -1,127 +1,127 @@
-import { assert } from "../src/core/assert.js";
-import { Gizmo } from "../src/engine/graphics/render/gizmo/Gizmo.js";
-import { entity_world_bounds_reader } from "./entity_world_bounds.js";
-
-/**
- * The colour a selection is drawn in, RGBA. Yellow, which is what the three `BoxHelper` this
- * replaces defaulted to — the editor is not asking for a new language, only for a new backend.
- *
- * @type {number[]}
- */
-const SELECTION_COLOR = [1, 1, 0, 1];
-
-/**
- * @type {Float32Array}
- */
-const scratch_bounds = new Float32Array(6);
-
-/**
- * @type {Float32Array}
- */
-const scratch_center = new Float32Array(3);
-
-/**
- * @type {Float32Array}
- */
-const scratch_size = new Float32Array(3);
-
-/**
- * Draws a box around every selected entity.
- *
- * **It holds nothing per selection, and that is the whole of the rewrite.** The three version built
- * a `BoxHelper` per selected entity, kept it in a `Map`, subscribed to the entity's mesh events to
- * re-fit it and added it to `graphics.scene` — a lifetime to get right for something that is only
- * ever a picture of the current selection. On an immediate-mode surface there is nothing to get
- * right: each frame asks where the selection is and records a box, and a selection whose entity has
- * gone answers nothing and draws nothing. That is also why an entity removed under a live selection
- * cannot leave a box behind — there is no box to leave.
- *
- * **What draws it is whichever backend the engine has registered** — `DebugDrawSystem3` under
- * Shade, `GizmoRenderingPlugin` under three — because {@link Gizmo} is renderer-neutral by
- * construction (V3). The one thing this does have to resolve per renderer is where an entity's
- * bounds live; see {@link entity_world_bounds_reader}.
- *
- * **A box is drawn on the entity's bounds, so it is occluded by what stands in front of it** the
- * same way the debug-draw pass's other shapes are. It survives an occluder wherever the bounds
- * exceed what covers them, which is more than the highlight outline can do — that one can only mark
- * pixels the entity itself wrote (D27), so an entity that is hidden has no outline at all. Whether
- * a selection should instead sit on top of everything is the same question the gizmo handles ask,
- * and V6 answers it for both.
- */
-export class SelectionVisualizer {
-    /**
-     * @type {Editor}
-     */
-    editor;
-
-    /**
-     * Where an entity is, on the renderer this editor attached to. Resolved on {@link startup},
-     * because the engine is not known when the editor is built.
-     *
-     * @type {function(ArrayLike<number>, number): boolean|null}
-     */
-    #bounds = null;
-
-    /**
-     * @type {function}
-     */
-    #draw;
-
-    /**
-     * @param {Editor} editor
-     */
-    constructor(editor) {
-        assert.defined(editor, 'editor');
-
-        this.editor = editor;
-
-        this.#draw = () => this.#record();
-    }
-
-    /**
-     * Record this frame's selection.
-     */
-    #record() {
-        const selection = this.editor.selection;
-        const bounds = this.#bounds;
-
-        Gizmo.color = SELECTION_COLOR;
-
-        for (let i = 0; i < selection.length; i++) {
-            const entity = selection.get(i);
-
-            if (!bounds(scratch_bounds, entity)) {
-                // no model, or one that has not loaded — there is nothing to put a box around
-                continue;
-            }
-
-            scratch_center[0] = (scratch_bounds[0] + scratch_bounds[3]) / 2;
-            scratch_center[1] = (scratch_bounds[1] + scratch_bounds[4]) / 2;
-            scratch_center[2] = (scratch_bounds[2] + scratch_bounds[5]) / 2;
-
-            scratch_size[0] = scratch_bounds[3] - scratch_bounds[0];
-            scratch_size[1] = scratch_bounds[4] - scratch_bounds[1];
-            scratch_size[2] = scratch_bounds[5] - scratch_bounds[2];
-
-            Gizmo.draw_wire_cube(scratch_center, scratch_size);
-        }
-    }
-
-    startup() {
-        const engine = this.editor.engine;
-
-        this.#bounds = entity_world_bounds_reader(engine);
-
-        // per frame rather than per tick: the recording is cleared once the frame that consumed it
-        // has been submitted, and a frame can be drawn more than once between two ticks
-        engine.graphics.on.preRender.add(this.#draw);
-    }
-
-    shutdown() {
-        const engine = this.editor.engine;
-
-        engine.graphics.on.preRender.remove(this.#draw);
-
-        this.#bounds = null;
-    }
-}
+import { assert } from "../src/core/assert.js";
+import { Gizmo } from "../src/engine/graphics/render/gizmo/Gizmo.js";
+import { entity_world_bounds_reader } from "./entity_world_bounds.js";
+
+/**
+ * The colour a selection is drawn in, RGBA. Yellow, which is what the three `BoxHelper` this
+ * replaces defaulted to — the editor is not asking for a new language, only for a new backend.
+ *
+ * @type {number[]}
+ */
+const SELECTION_COLOR = [1, 1, 0, 1];
+
+/**
+ * @type {Float32Array}
+ */
+const scratch_bounds = new Float32Array(6);
+
+/**
+ * @type {Float32Array}
+ */
+const scratch_center = new Float32Array(3);
+
+/**
+ * @type {Float32Array}
+ */
+const scratch_size = new Float32Array(3);
+
+/**
+ * Draws a box around every selected entity.
+ *
+ * **It holds nothing per selection, and that is the whole of the rewrite.** The three version built
+ * a `BoxHelper` per selected entity, kept it in a `Map`, subscribed to the entity's mesh events to
+ * re-fit it and added it to `graphics.scene` — a lifetime to get right for something that is only
+ * ever a picture of the current selection. On an immediate-mode surface there is nothing to get
+ * right: each frame asks where the selection is and records a box, and a selection whose entity has
+ * gone answers nothing and draws nothing. That is also why an entity removed under a live selection
+ * cannot leave a box behind — there is no box to leave.
+ *
+ * **What draws it is whichever backend the engine has registered** — `DebugDrawSystem` under
+ * Shade, `GizmoRenderingPlugin` under three — because {@link Gizmo} is renderer-neutral by
+ * construction (V3). The one thing this does have to resolve per renderer is where an entity's
+ * bounds live; see {@link entity_world_bounds_reader}.
+ *
+ * **A box is drawn on the entity's bounds, so it is occluded by what stands in front of it** the
+ * same way the debug-draw pass's other shapes are. It survives an occluder wherever the bounds
+ * exceed what covers them, which is more than the highlight outline can do — that one can only mark
+ * pixels the entity itself wrote (D27), so an entity that is hidden has no outline at all. Whether
+ * a selection should instead sit on top of everything is the same question the gizmo handles ask,
+ * and V6 answers it for both.
+ */
+export class SelectionVisualizer {
+    /**
+     * @type {Editor}
+     */
+    editor;
+
+    /**
+     * Where an entity is, on the renderer this editor attached to. Resolved on {@link startup},
+     * because the engine is not known when the editor is built.
+     *
+     * @type {function(ArrayLike<number>, number): boolean|null}
+     */
+    #bounds = null;
+
+    /**
+     * @type {function}
+     */
+    #draw;
+
+    /**
+     * @param {Editor} editor
+     */
+    constructor(editor) {
+        assert.defined(editor, 'editor');
+
+        this.editor = editor;
+
+        this.#draw = () => this.#record();
+    }
+
+    /**
+     * Record this frame's selection.
+     */
+    #record() {
+        const selection = this.editor.selection;
+        const bounds = this.#bounds;
+
+        Gizmo.color = SELECTION_COLOR;
+
+        for (let i = 0; i < selection.length; i++) {
+            const entity = selection.get(i);
+
+            if (!bounds(scratch_bounds, entity)) {
+                // no model, or one that has not loaded — there is nothing to put a box around
+                continue;
+            }
+
+            scratch_center[0] = (scratch_bounds[0] + scratch_bounds[3]) / 2;
+            scratch_center[1] = (scratch_bounds[1] + scratch_bounds[4]) / 2;
+            scratch_center[2] = (scratch_bounds[2] + scratch_bounds[5]) / 2;
+
+            scratch_size[0] = scratch_bounds[3] - scratch_bounds[0];
+            scratch_size[1] = scratch_bounds[4] - scratch_bounds[1];
+            scratch_size[2] = scratch_bounds[5] - scratch_bounds[2];
+
+            Gizmo.draw_wire_cube(scratch_center, scratch_size);
+        }
+    }
+
+    startup() {
+        const engine = this.editor.engine;
+
+        this.#bounds = entity_world_bounds_reader(engine);
+
+        // per frame rather than per tick: the recording is cleared once the frame that consumed it
+        // has been submitted, and a frame can be drawn more than once between two ticks
+        engine.graphics.on.preRender.add(this.#draw);
+    }
+
+    shutdown() {
+        const engine = this.editor.engine;
+
+        engine.graphics.on.preRender.remove(this.#draw);
+
+        this.#bounds = null;
+    }
+}

package/editor/entity_world_bounds.js

@@ -1,27 +1,27 @@
-import { assert } from "../src/core/assert.js";
-import { MeshSystem3 } from "../src/engine/graphics3/MeshSystem3.js";
-
-/**
- * Where an entity's model is, in world space.
- *
- * The renderer refreshes a world box per scene node as part of placing it, so the answer is the
- * renderer's rather than the component's — which is why this is a reader built from an engine rather
- * than a function over a component.
- *
- * **Precondition:** the engine has a {@link MeshSystem3}. It is what puts anything on a screen at
- * all, so an editor running without one has nothing to select.
- *
- * @param {Engine} engine
- * @returns {function(ArrayLike<number>, number): boolean} writes an aabb3 in the order
- * `x0,y0,z0,x1,y1,z1` and answers whether the entity had one — an entity with no model, or one
- * whose model has not loaded, has no bounds and that is not an error
- */
-export function entity_world_bounds_reader(engine) {
-    assert.defined(engine, 'engine');
-
-    const meshes = engine.entityManager.getSystem(MeshSystem3);
-
-    assert.notNull(meshes, 'MeshSystem3');
-
-    return (target, entity) => meshes.compute_world_bounds(target, entity);
-}
+import { assert } from "../src/core/assert.js";
+import { MeshSystem } from "../src/engine/graphics3/MeshSystem.js";
+
+/**
+ * Where an entity's model is, in world space.
+ *
+ * The renderer refreshes a world box per scene node as part of placing it, so the answer is the
+ * renderer's rather than the component's — which is why this is a reader built from an engine rather
+ * than a function over a component.
+ *
+ * **Precondition:** the engine has a {@link MeshSystem}. It is what puts anything on a screen at
+ * all, so an editor running without one has nothing to select.
+ *
+ * @param {Engine} engine
+ * @returns {function(ArrayLike<number>, number): boolean} writes an aabb3 in the order
+ * `x0,y0,z0,x1,y1,z1` and answers whether the entity had one — an entity with no model, or one
+ * whose model has not loaded, has no bounds and that is not an error
+ */
+export function entity_world_bounds_reader(engine) {
+    assert.defined(engine, 'engine');
+
+    const meshes = engine.entityManager.getSystem(MeshSystem);
+
+    assert.notNull(meshes, 'MeshSystem');
+
+    return (target, entity) => meshes.compute_world_bounds(target, entity);
+}

package/editor/particles/rebuildParticleEmitter.js

@@ -1,31 +1,31 @@
-import {
-    ParticleEmitter
-} from "../../src/engine/graphics/particles/particular/engine/emitter/ParticleEmitter.js";
-import { ParticleEmitterSystem3 } from "../../src/engine/graphics3/ParticleEmitterSystem3.js";
-
-/**
- * Rebuild a live particle emitter after structural edits (layers, sprites, parameter
- * tracks): the system pulls it out of the particle engine, runs the full build sequence and puts
- * it back. Sleep state is preserved.
- *
- * @param {EntityManager} entityManager
- * @param {number} entity
- * @returns {boolean} false when the entity has no emitter or no emitter system runs
- */
-export function rebuildParticleEmitter(entityManager, entity) {
-    const system = entityManager.getSystem(ParticleEmitterSystem3);
-
-    if (system === null) {
-        return false;
-    }
-
-    const emitter = entityManager.dataset.getComponent(entity, ParticleEmitter);
-
-    if (emitter === undefined) {
-        return false;
-    }
-
-    system.rebuild(emitter);
-
-    return true;
-}
+import {
+    ParticleEmitter
+} from "../../src/engine/graphics/particles/particular/engine/emitter/ParticleEmitter.js";
+import { ParticleEmitterSystem } from "../../src/engine/graphics3/ParticleEmitterSystem.js";
+
+/**
+ * Rebuild a live particle emitter after structural edits (layers, sprites, parameter
+ * tracks): the system pulls it out of the particle engine, runs the full build sequence and puts
+ * it back. Sleep state is preserved.
+ *
+ * @param {EntityManager} entityManager
+ * @param {number} entity
+ * @returns {boolean} false when the entity has no emitter or no emitter system runs
+ */
+export function rebuildParticleEmitter(entityManager, entity) {
+    const system = entityManager.getSystem(ParticleEmitterSystem);
+
+    if (system === null) {
+        return false;
+    }
+
+    const emitter = entityManager.dataset.getComponent(entity, ParticleEmitter);
+
+    if (emitter === undefined) {
+        return false;
+    }
+
+    system.rebuild(emitter);
+
+    return true;
+}

package/editor/process/SymbolicDisplayProcess.js

@@ -27,7 +27,7 @@ import {
  * went — which is why this process had to spawn a `RenderSystem` to draw at all and had to check
  * whether each display's component types were even registered before starting it. None of that
  * survives: the displays are asked once a frame what the scene looks like and answer with shapes
- * in {@link Gizmo}, and `DebugDrawSystem3` turns them into pixels.
+ * in {@link Gizmo}, and `DebugDrawSystem` turns them into pixels.
  */
 class SymbolicDisplayProcess extends EditorProcess {
     name = SymbolicDisplayProcess.Id;