@woosh/meep-engine 3.9.0 → 3.11.0

package/README.md

@@ -1,152 +1,168 @@
-# Meep Engine
-**The unopinionated, high-performance ECS engine for code-first developers.**
-
-Meep is a battle-tested JavaScript game engine designed for scale. Built over 10+ years and used in commercial Steam releases, it strips away the bloat of traditional engines to offer a molecular, zero-allocation architecture.
-
-It is designed for engineers who want full control, offering performance that rivals native code on the web.
-
-[🕹️Examples](https://meep.company-named.com/examples/) | [📚 Documentation](https://meep.company-named.com/docs/getting-started/) | [🚀 Quick Start Template](https://gitlab.company-named.com/travnik/dream-engine-template) | [📄 License](#license--copyright)
-
----
-
-## Why Meep?
-Most web engines are heavy, opinionated, and struggle with garbage collection. Meep is different.
-
-* **Pure ECS Architecture:** A true data-oriented foundation that supports complex hierarchies and millions of entities. Unlike hybrid engines, our component queries are instantaneous.
-* **Molecular Modularity:** Distributed as ~3,700 fine-grained modules. Need a lerp function? Import it for a 4-line footprint. You never pay for code you don't use.
-* **Zero-Garbage Architecture:** Custom memory management ensures stable frame rates. Meep handles millions of objects on low-spec mobile hardware without GC spikes.
-* **Code-First:** No GUI. No black boxes. Meep is a programmatic tool designed for software engineers who value architecture and long-term integration.
-* **Battle-Hardened:** Covered by 12,000+ unit tests and extensive assertions. This is not a prototype; it is industrial-grade software.
-
----
-
-## 💎 Architecture: Pure ECS
-Meep is not yet another Object-Oriented engine with an ECS tacked on; it is a **Pure Entity Component System** engine.
-
-While other engines (like Unity) struggle with slow query times and documentation that advises you to use component lookups "sparingly" — Meep thrives on them.
-
-* **Strict Data-Oriented Design:** One component instance per type per entity. This guarantees memory layout optimization and cache locality.
-* **The Hierarchy Problem: Solved.**  Pure ECS architectures historically struggle with scene graphs and parent-child transforms. Meep solves this natively. You get the composability of a scene graph with the raw speed of a flat array. (Similar to the Rust-based Bevy engine).
-* **Tiered API Access:**
-  * **High-Level:** Use convenient abstraction layers for gameplay logic.
-  * **Low-Level:** Drop down to raw typed arrays for performance-critical paths — physics bodies, geometry and transforms are all backed by them. The component store itself is index-addressed rather than a flat typed array.
-* **Uncompromised Speed:** Because the architecture is solid, you can query, filter, and iterate over millions of entities without performance cliffs.
-
----
-
-## ⚡ High-Performance Rendering
-Meep 3 renders through **Shade**: a GPU-driven, visibility-buffer deferred renderer on **WebGPU**. Geometry is clustered into meshlets ahead of time and lives GPU-resident; culling runs on the GPU; lights are binned into froxels and applied deferred.
-
-**→ [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.
-**Coming from 2.x?** [Migration guide](MIGRATION_2_TO_3.md) · [Changelog](CHANGELOG.md).
-
-* **WebGPU only.** There is no WebGL fallback, no backend abstraction and no degradation tiers. Hardware below the device floor gets a clean failure message rather than a lesser picture.
-
-* **Unlimited Lighting:** Render thousands of point lights (muzzle flashes, explosions, torches) with clustered lighting.
-
-* **GPU-Driven Decals:** Handle 1,000,000+ decals for persistent battle damage and environmental details.
-
-* **Massive Terrain:** Chunk-based, auto-culled terrain system supporting up to 256 layers (vs Unity's 4).
-
-* **"Particular" Particle Engine:** A zero-allocation particle system with full lighting, soft particles, and automatic atlassing, drawn through the renderer's own billboard pipeline.
-
-* **Extensible frames:** Your own work goes into the frame as a *render extension* — a declared phase, declared ordering, and typed per-frame records — rather than as a patch to the pipeline.
-
-* **Path Tracing:** Includes a pure JS path tracer utilizing the engine's internal BVH.
-
-## ⚙️ Physics
-A deterministic rigid-body engine in pure JS — no WASM, no worker threads — built for replay-stable netcode and scenes with millions of mostly-sleeping bodies.
-
-* **Rigid Bodies at Scale:** SoA body pool, two-tree BVH broadphase, sequential-impulse solver with warm starting, and island-based atomic sleep/wake.
-
-* **Broad Shape Coverage:** Closed-form sphere/box/capsule paths, GJK+EPA for arbitrary convex shapes, heightmap and triangle-mesh terrain collisions, and continuous collision detection for fast movers.
-
-* **Fluid Dynamics:** Eulerian MAC-grid solver (MacCormack advection, vorticity confinement, SOR/PCG pressure) plus an MLS-MPM material-point simulator.
-
-* **Vehicles & Characters:** Raycast vehicle and a kinematic first-person character controller with stair and ramp handling.
-
-* **Inverse Kinematics:** Highly optimized FABRIK and analytic two-joint solvers.
-
-## 🔊 Audio
-A data-driven sound engine built on Wwise / FMOD concepts — without the opaque middleware banks.
-
-* **Full Middleware Feature Set:** Events, a mixer bus tree, RTPC parameters, voice stealing, mixer snapshots, and ducking — all authored as serializable engine data.
-
-* **Acoustic Simulation (opt-in):** Geometry-driven occlusion, transmission, propagation pathing, and baked reverb probes. What Steam Audio is to FMOD/Wwise, this layer is to the sound engine.
-
-* **Scale:** Custom culling and attenuation support 1,000s of positional sources with zero overhead.
-
-## 🌐 Networking
-A game-ready netcode stack, from raw transport to rollback.
-
-* **Server-Authoritative Rollback:** Client-side prediction and reconciliation over action-log replication and binary snapshots.
-
-* **Pluggable Transports:** WebRTC DataChannel, WebTransport, WebSocket, and Node UDP — with ack-based reliability, MTU fragmentation, and per-peer scope filtering.
-
-* **Diagnostics Built In:** Bandwidth metering, packet record/replay, and cross-peer desync detection.
-
-## 🧠 AI & Simulation Tools
-Meep provides a suite of tools rarely found in JS engines, optimized for complex decision making.
-
-* **Behavior Trees & Blackboards:** Industry-standard tools for state management.
-
-* **Monte-Carlo Tree Search:** The same algorithm used in AlphaGo, available for your decision logic.
-
-* **Resource Allocation Solver:** Plan optimal actions based on limited resources (ammo, health, currency).
-
-* **Spatial Query System:** Highly optimized BVH for Ray, Box, Frustum, and Point queries.
-
-* **Pathfinding:** A* grid search, and a navigation mesh with build-time obstacle carving and exact (Polyanya) any-angle path queries. Agent steering and runtime obstacle carving are not implemented — `NavigationMeshAgent` is a placeholder, and changing the mesh after build means rebuilding it.
-
-## 🛠️ Developer Experience
-
-### Installation & Stripping
-
-Meep is designed to be invisible in production.
-```shell
-npm install @woosh/meep-engine
-```
-
-**Development Mode:** The engine includes ~5,000 assertions to help you catch errors instantly.
-
-**Production Mode:** Using @rollup/plugin-strip, Meep compiles to tiny size and runs at the speed of light.
-
-```js
-// vite.config.js
-import strip from '@rollup/plugin-strip';
-export default defineConfig({
-    plugins: [{ ...strip(), apply: 'build' }]
-});
-```
-
-### Reliability
-* **Tests:** 8,000+ tests across 1,400+ suites, including determinism, benchmark, and adversarial suites.
-
-* **Stability:** Exhaustively tested corner cases over a decade of development.
-
----
-
-## Additional Features
-
-| Category         | Features                                                                                                              |
-|------------------|-----------------------------------------------------------------------------------------------------------------------|
-| Input            | Unified abstraction for Touch, Mouse, Keyboard, and Gamepad. Event-driven and Query-based APIs                        |
-| Assets           | Web-first asset streaming. The engine runs before assets even load                                                    |
-| Serialization    | Binary serialization system with version upgrading                                                                    |
-| UI               | High-speed, zero-garbage UI system. Optional—can be replaced with React/Vue if desired                                |
-| Color Management | Scientific-grade color management toolkit, including spectral-integration tools and modern color spaces such as OKLab |
-| NodeGraph        | A building block for node-graph systems, such as shader editors and workflow engines                                  | 
-| Achievements     | State-of-the-art achievement system, using expressions and blackboards                                                |
-
----
-
-## License & Copyright
-Copyright © 2026 Company Named Limited. All rights reserved.
-
-Meep is **proprietary, source-available** software. The full source ships in the npm package — no binary blobs, no obfuscation — but it is not open source.
-
-**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.
-
-See [LICENSE](LICENSE) for the terms covering this package, and the [pricing page](https://meep.company-named.com/pricing/) for the tier ladder.
+# 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.
+
+**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.
+
+[🕹️Examples](https://meep.company-named.com/examples/) | [📚 Documentation](https://meep.company-named.com/docs/getting-started/) | [🚀 Quick Start Template](https://gitlab.company-named.com/travnik/dream-engine-template) | [📄 License](#license--copyright)
+
+---
+
+## 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.
+
+```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).
+
+---
+
+## 💎 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.
+* **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.
+
+---
+
+## ⚡ 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.
+
+* **Lighting:** clustered point and spot lights, shadows, ReSTIR DI, brick4 volumetric GI.
+
+* **Virtual geometry and virtual textures:** `.vgeo` streaming, a GPU scene database, GPU animation and skinning.
+
+* **Decals:** frustum-culled and cluster-assigned on the GPU, composited against the G-buffer out of a shared atlas. Capacity grows with the record buffer rather than sitting behind a fixed cap.
+
+* **Terrain:** chunk-based and auto-culled, splat-weighted per layer. The layer count is bounded by the device's texture-array depth rather than by an engine constant.
+
+* **Particles:** zero-allocation, fully lit, soft, automatically atlassed, drawn through the renderer's own billboard pipeline.
+
+* **Resolution:** TAA/NSS upscaling and dynamic resolution scaling.
+
+* **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.
+
+* **Picking** is asynchronous and batched (`PickingQuery`); there is no synchronous entry point.
+
+On top of Shade, `engine/graphics3` carries the ECS systems a game binds to: cameras, lights, animation, decals, particles, terrain, water, trails, highlights, fog of war and volumetric light maps.
+
+Deliberately absent: compressed textures (DDS, Draco, Basis), double-sided drawing, and any second backend.
+
+---
+
+## ⚙️ 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.
+
+* **At scale:** SoA body pool, two-tree BVH broadphase, sequential-impulse solver with warm starting, island-based atomic sleep/wake.
+
+* **Shape coverage:** closed-form sphere/box/capsule paths, GJK+EPA for arbitrary convex shapes, heightmap and triangle-mesh terrain collisions, continuous collision detection for fast movers.
+
+* **Fluids:** Eulerian MAC-grid solver (MacCormack advection, vorticity confinement, SOR/PCG pressure) plus an MLS-MPM material-point simulator.
+
+* **Vehicles and characters:** raycast vehicle, and a kinematic first-person controller with stair and ramp handling.
+
+* **Inverse kinematics:** FABRIK and analytic two-joint solvers.
+
+## 🔊 Audio
+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.
+
+* **Two entry points:** `AudioEmitter` puts a sound on an entity; `AudioEventTrigger` fires authored events in response to entity events.
+
+* **Acoustic simulation (opt-in):** geometry-driven occlusion, transmission, propagation pathing and baked reverb probes. What Steam Audio is to FMOD/Wwise, this layer is to the sound engine.
+
+* **Scale:** custom culling and attenuation support 1,000s of positional sources.
+
+## 🌐 Networking
+
+* **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.
+
+* **Diagnostics:** bandwidth metering, packet record/replay, cross-peer desync detection.
+
+## 🧠 Navigation & AI
+
+* **Pathfinding:** A* grid search, and a navigation mesh with build-time obstacle carving and exact (Polyanya) any-angle queries.
+
+* **Behavior trees and blackboards** for agent state.
+
+* **Monte-Carlo tree search**, for decision logic that searches a game tree rather than following one.
+
+* **Resource allocation solver:** plan optimal actions against limited resources (ammo, health, currency).
+
+* **Spatial queries:** 2-wide and 8-wide BVH implementations for ray, box, frustum and point queries.
+
+## 🌱 Procedural Generation
+`src/generation` is a rule-driven grid generator: cellular automata, layered grids with bitmask cell matchers, rule sets that place markers and spawn entities, filtering and placement passes, theme-driven selection. Generation is composable tasks over a shared `GridGenerationResource`, so building a world is a task graph rather than a script.
+
+## 📦 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.
+
+* **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.
+
+* **Serialization:** binary, with version upgrading.
+
+---
+
+## 🛠️ Tooling
+
+* **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.
+
+* **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.
+
+---
+
+## 🔬 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.*`:
+
+```js
+// vite.config.js
+import strip from '@rollup/plugin-strip';
+export default defineConfig({
+    plugins: [{ ...strip(), apply: 'build' }]
+});
+```
+
+---
+
+## Additional Features
+
+| Category         | Features                                                                                                          |
+|------------------|-------------------------------------------------------------------------------------------------------------------|
+| Input            | Touch, mouse, keyboard and gamepad behind one abstraction. Event-driven and query-based APIs                      |
+| UI               | Zero-garbage DOM view system. Optional; replaceable with React/Vue                                                |
+| Color Management | OKLab/OkHSV, CIELAB, HSV/HCL, PQ, YCbCr/YCoCg, illuminants, spectral integration, tone mapping and gamut clipping |
+| NodeGraph        | A building block for node-graph systems, such as shader editors and workflow engines                              |
+| Achievements     | Achievement system driven by expressions and blackboards                                                          |
+| Localization     | Per-locale string catalogues with template variables and `Intl` number formatting                                 |
+| Storage          | Key-value `Storage` abstraction with IndexedDB and in-memory backends                                             |
+
+---
+
+## 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.
+
+Short version: ship anything you like, just don't redistribute the source and don't build a competing engine.
+
+See [LICENSE](LICENSE) for the terms covering this package, and the [pricing page](https://meep.company-named.com/pricing/) for the tier ladder.