@woosh/meep-engine 3.11.2 → 3.12.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.