@woosh/meep-engine 2.165.0 → 2.165.2

package/README.md

@@ -1,108 +1,137 @@
-# 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](http://gitlab.company-named.com/travnik/dream-engine-template)
-
----
-
-## 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,000 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 6,500+ 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.
-* **Uncompromised Speed:** Because the architecture is solid, you can query, filter, and iterate over millions of entities without performance cliffs.
-
----
-
-## ⚡ High-Performance Rendering
-Meep implements a Clustered Forward+ rendering pipeline, allowing for scenes that traditional web engines choke on.
-
-* **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. Compiled into just 4 shaders to eliminate state-switching overhead.
-
-* **Path Tracing:** Includes a pure JS path tracer utilizing the engine's internal BVH.
-
-## 🧠 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.
-
-* **Inverse Kinematics:** Includes FABRIK solvers and specialized bip/quadruped solvers for uneven terrain adaptation.
-
-## 🛠️ Developer Experience
-
-### Installation & Stripping
-
-Meep is designed to be invisible in production.
-```shell
-npm install @woosh/meep-engine
-```
-
-**Development Mode:** The engine includes ~4,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:** 7,554 tests with 90%+ core coverage.
-
-* **Stability:** Exhaustively tested corner cases over a decade of development.
-
----
-
-## Additional Features
-
-| Category         | Features                                                                                                              |
-|------------------|-----------------------------------------------------------------------------------------------------------------------|
-| Audio            | Custom culling and attenuation; supports 1,000s of positional sources with zero overhead                              |
-| Input            | Unified abstraction for Touch, Mouse, and Keyboard. 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                                                |
-| Inverse Kinematics (IK) | Highly optimized FABRIK inverse kinematics solver even the most complex IK use cases                                  |
-
----
-
-## License & Copyright
-Copyright © 2026 Company Named Limited, All Rights Reserved.
+# 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](http://gitlab.company-named.com/travnik/dream-engine-template)
+
+---
+
+## 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 8,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.
+* **Uncompromised Speed:** Because the architecture is solid, you can query, filter, and iterate over millions of entities without performance cliffs.
+
+---
+
+## ⚡ High-Performance Rendering
+Meep implements a Clustered Forward+ rendering pipeline, allowing for scenes that traditional web engines choke on.
+
+* **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. Compiled into just 4 shaders to eliminate state-switching overhead.
+
+* **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 agents and runtime obstacle carving.
+
+## 🛠️ 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.