@woosh/meep-engine 3.13.0 → 3.14.0

package/README.md

@@ -1,134 +1,278 @@
 # 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.
+**Desktop-grade real-time graphics in the browser, in a JavaScript engine you import from and drive in code.**
 
-**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)
-
----
-
-## Installation
+[🕹️ 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) · [📄 Licence](#licence--pricing)
 
 ```shell
 npm install @woosh/meep-engine
 ```
 
-**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.
+**Proprietary and source-available.** You get all ~6,200 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.
 
 ---
 
-## ⚡ 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.
+meep has one renderer, not a kit of parts. Every feature is part of a single frame and works off
+the same shared data, so a character's shadow, the decal on the wall behind it and the fog in
+between are computed together and agree with each other. There is one path rather than a
+combinatorial number of them, so it is tuned once - by the engine, not by you.
 
-* **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.
+That is not how browser rendering usually goes. Most WebGPU and WebGL renderers are a rasterizer
+plus an ecosystem: you assemble the frame yourself out of plugins written without knowledge of each
+other, so a stack can have shadows, decals, global illumination, anti-aliasing and volumetric fog
+on paper and still not have them working together - and every plugin is another set of numbers to
+tune, per scene and per device.
 
-* **Particles:** zero-allocation, fully lit, soft, automatically atlassed, drawn through the renderer's own billboard pipeline.
+**Shadows, ambient occlusion, indirect lighting, auto-exposure, anti-aliasing and transparency are
+all on by default, and there is nothing to configure to get a correct-looking frame.** No quality
+tiers to author, no per-device profiles, no exposure value to pick, no shadow cascade splits to
+hand-tune. You put a scene together, it looks right, and it holds its frame rate across a wide
+range of hardware without you doing anything about it.
 
-* **Resolution:** TAA/NSS upscaling and dynamic resolution scaling.
+<!--
+PLACEHOLDER - two claims were removed from the opening because nothing in the repository
+supports them. Both may be true; neither is verifiable from source. Restore with specifics.
 
-* **Path tracing:** a GPU path tracer in Shade, and a separate CPU one that runs off the engine's own BVH.
+1. "shipped in commercial Steam releases" - needs the titles. Verified 2026-09-01: zero Steam app
+   IDs, zero steamworks/steam_api references, zero named shipped products anywhere in the tree.
+   The only game the repo names is the codename "mir", whose own README says it is unpublished.
+   Every other occurrence of "Steam" is Steam Audio cited as a design reference. Naming even one
+   title is worth more than the generic sentence was.
 
-* **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.
+2. "Built over 10+ years" - git history runs 2020-04-19 to 2026-09-01 (6y4m, 7,652 commits), with
+   no earlier commit by author or committer date. If the 10 years predates this repository, say
+   so; otherwise "in development since 2020" is defensible as written.
+-->
 
-* **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.
+# The renderer
+
+A GPU-driven deferred renderer on WebGPU. It lives under `src/shade/`, which is where the `Shade*`
+type names come from.
+
+## What you get
+
+* **Thousands of dynamic lights.** Lighting is one pass over the screen however many lights are in
+  the scene. A light adds work only on the pixels it actually touches - not another pass, not
+  another draw - so lights are something you place rather than something you budget.
+* **Shadows from every light, with nothing to set up.** No fixed limit on how many lights cast
+  shadows. Cascade distances come from your camera, each shadow's resolution from how large that
+  light looks on screen, and refresh priority from what has changed. There is no per-light shadow
+  setting to get wrong.
+* **Scene complexity is nearly free on the CPU.** All opaque geometry is submitted in a couple of
+  draw calls, whether the scene holds one object or a hundred thousand. Visibility is decided on
+  the GPU, so adding objects does not add CPU work per object.
+* **You don't pay for what you can't see.** Geometry hidden behind other geometry is dropped on the
+  GPU before anything shades it, and this works below the level of whole objects - a mesh half
+  behind a wall does not cost its hidden half. A dense interior costs roughly what you can see of it.
+* **Overlapping geometry doesn't multiply cost.** Deferred shading means a surface hidden behind
+  another is not shaded twice. Materials are evaluated once per visible pixel, after the scene is
+  drawn.
+* **Features you turn off cost nothing.** The frame is assembled as a graph, and work that nothing
+  consumes is dropped before it reaches the GPU. That applies to passes you add as well - you
+  extend the frame by declaring where your work goes, not by patching the renderer.
+
+If you want the mechanisms behind these - visibility buffer, meshlet clustering, clustered lighting,
+occlusion culling, the frame graph - they are in **[the renderer contract](src/shade/RENDERER_CONTRACT.md)**,
+which also covers how to put a model on the screen and how to add your own work to the frame.
+
+## How the features interact
+
+What a feature list cannot tell you is whether the features work together once they are in the same
+scene. This can.
+
+| | Lit by scene lights | Shadows | Stable when it moves | Indirect light |
+|---|---|---|---|---|
+| Static meshes | ✅ | casts + receives | ✅ | ✅ |
+| **Skinned characters** | ✅ | casts + receives | ✅ **per-vertex** | ✅ |
+| Terrain | ✅ | casts + receives | ✅ | ✅ |
+| Decals | ✅ | receives | ✅ follows the surface | ✅ |
+| Transparent surfaces | ✅ | receives | ❌ | ✅ |
+| Volumetric fog | ✅ | shadowed by them | ✅ | n/a |
+| Water, particles, trails, overlays | ❌ | ❌ | ❌ | ❌ |
+
+Those top six are not six systems that were each taught about lighting. They read the same lighting,
+the same shadows and the same motion data, because there is only one of each. Three consequences:
+
+* **Animated characters are not a special case.** A skinned character goes down the same path as a
+  static one: same culling, same shadows, same lighting. It also produces motion data per vertex
+  rather than per object, so a swinging arm resolves cleanly under anti-aliasing instead of
+  smearing - which is the usual failure of bolt-on temporal AA.
+* **A decal is lit like the surface it lands on.** Decals modify the surface itself rather than
+  painting over the finished image, so a scorch mark is lit, shadowed and bounced exactly like the
+  wall under it, and ambient occlusion and reflections see it too.
+* **Ordering is declared, not accidental.** Systems state what they must come after, by name, and
+  the renderer resolves the order. Decals declare that they follow terrain, so scorch marks land on
+  textured ground - rather than depending on which system happened to register first.
+
+Water, particles, trails and screen overlays are drawn after lighting, so they are not lit or
+shadowed and contribute no motion data. They read the scene's depth, so they are correctly hidden
+behind things in front of them.
+
+## Scaling across hardware
+
+**One build covers a wide hardware range, and you don't author the tiers.** When frames start
+costing more than the budget - on a weaker GPU, or because the scene got busy - the engine renders
+internally at a lower resolution and upscales back to the display, adjusting continuously as
+conditions change. Nothing in your application is involved: this is wired up by default when you
+construct an `Engine`.
+
+Anti-aliasing is what does the upscaling, and it is on by default. Out of the box the internal and
+display resolutions are the same, so you get anti-aliasing at native resolution and no upscaling
+until something needs the headroom.
+
+It holds a **floor rather than a target**: 30 FPS by default, taking no action on hardware that is
+already clearing it, and trading resolution down to 43% before it runs out of room. What it costs
+is one re-converging frame each time the resolution steps, since temporal history is discarded.
+
+To override or opt out:
 
-## 🌐 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.
+```js
+engine.graphics.dynamic_resolution.enabled = false;      // or .target_frame_rate / .min_scale
+engine.graphics.renderer.feature_taa_enabled = false;    // only valid after start()
+```
 
-* **Serialization:** binary, with version upgrading.
+Two things to know. Anti-aliasing is the only thing that upscales, so switching it off while the
+resolution scale is below full leaves the frame un-upscaled. And if you drive the `Renderer`
+directly rather than through `Engine`, none of this is wired for you.
+
+A neural upscaler ships alongside the default one - a port of ARM's Neural Super Sampling, weights
+included, no setup needed - one assignment away at `renderer.upscale_type = ShadeUpscalerType.NSS`.
+
+## Correct by default
+
+The out-of-the-box configuration is the expensive-and-correct one, not the safe-and-cheap one.
+
+**On, with nothing to configure:** shadows · ambient occlusion · indirect lighting · anti-aliasing ·
+auto-exposure · tonemapping · bloom · sharpening · order-independent transparency. Virtual texturing
+is available system-wide and opts in per material.
+
+* **Shadows** need no numbers from you. Cascade distances come from your camera, shadow map sizes
+  from how large each light looks on screen, and depth bias from constants that work. There is no
+  cascade array to hand-tune and no shadow budget to apportion.
+* **Auto-exposure** needs no exposure value. The engine meters the scene's brightness each frame,
+  weighted toward the centre of the image and ignoring the brightest and darkest few percent so a
+  bright sky or a dark corner does not drag the whole frame, then eases toward it - faster when the
+  scene brightens than when it darkens, the way an eye does. Walk from a dark interior into daylight
+  and it adjusts.
+* **Tonemapping** picks its own operator from the display: ACES on SDR, and a dedicated HDR curve
+  when the display is HDR.
+
+Opt-in, off by default: screen-space reflections, motion blur, depth of field, ReSTIR direct
+lighting, and a reference path tracer.
+
+**Global illumination** defaults to image-based. There is also a baked volumetric GI mode - probe
+bricks through the scene volume, in the shape Unreal's volumetric lightmaps take - which dynamic and
+skinned objects sample as they move through it. It bakes in-engine, from a live scene and renderer,
+so the precompute is a call you make rather than a tool you leave the engine for. Opaque and
+transparent surfaces both use it, so turning it on does not leave them lit differently.
+
+## WebGPU only
+
+WebGPU is not a better WebGL - it is a different machine. Compute shaders, storage buffers and
+indirect draw are what let visibility be decided on the GPU and a whole scene be submitted in a
+couple of draw calls. None of that has an equivalent in WebGL, so supporting both would mean either
+a second renderer to maintain or holding this one down to what the older API can express. meep
+targets WebGPU, and everything above follows from that.
+
+The floor is fixed and checked before anything is created: WebGPU plus a small set of capabilities
+that mainstream desktop GPUs have had for years. Hardware that does not clear it gets a clear
+failure message written to be shown to a person, rather than a degraded picture. The exact features
+and limits are in [§2 of the contract](src/shade/RENDERER_CONTRACT.md).
+
+## Numbers
+
+There is no published benchmark for the renderer yet. What the pipeline does differently is
+checkable in the source without running anything - draw count independent of object count, one
+lighting pass independent of light count, material cost independent of overdraw - and the tools to
+measure the rest ship with it.
+
+The renderer records `.sgpt` GPU profile captures - per-pass timings, and at higher capture levels
+the frame-graph structure, dispatch and draw counts. Assign a
+`GPUProfileSession({ level: GPUProfileLevel.WORKLOAD })` to `renderer.profile_session`, call
+`start()`, run frames, and `stop()` returns an `ArrayBuffer` to write out. The recorder and the
+[format specification](src/shade/device/timing/profile/SGPT_FORMAT.md) both ship in this package.
+
+<!--
+BENCHMARK TABLE - do not fill from memory or estimate. Needs a real measured run.
+Verified 2026-09-01: no end-to-end renderer frame-time measurement exists anywhere in this
+repository, and no measurement against three.js / PlayCanvas / Unity / Babylon exists in any form.
+Do not write "several times faster than three.js" until there is a reproducible run behind it.
+
+| Scene | Hardware | Resolution | Frame time | Draw calls | Triangles | Lights |
+|---|---|---|---|---|---|---|
+|   |   |   |   |   |   |   |
+
+To fill this, the following must be measured and recorded:
+  1. A PUBLIC scene. None currently exists - all four playground entry points are dev-server-only
+     and three need assets from the gitignored, unpublished `test_assets/`. Publishing one scene
+     the reader can open is a prerequisite for every row of this table.
+  2. Whole-frame time at a named resolution on a NAMED GPU (not "4070-class"), with the swap chain
+     confirmed not to be the limiter - volumetrics_froxel/README.md:83 records 1080p reading a flat
+     ~16.5 ms under presentation throttling, which is what makes its 28 ms figure at :189 unusable.
+  3. Draw-call and triangle counts from the same run - both are already in an .sgpt capture.
+  4. The same scene at two or three resolutions, to show the dynamic-resolution curve.
+  5. Optional and unusually strong: publish the .sgpt capture itself alongside the numbers.
+     The writer already ships; the viewer needs deploying (it is currently `"private": true`).
+-->
 
 ---
 
-## 🛠️ 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.
+## Everything else
+
+The rest of what a game needs, in the same package. Each links out to its own documentation.
+
+* **Architecture.** A real ECS - one component per type per entity - with parent/child hierarchy
+  available without a scene graph. Allocation-conscious on the hot paths, so frame times stay flat
+  rather than sawtoothing against the garbage collector.
+* **Physics.** Deterministic rigid bodies in pure JavaScript, no WebAssembly and no worker threads,
+  with the determinism covered by replay tests - which is what lets it sit under rollback netcode.
+  Convex and mesh collision, continuous collision detection for fast movers, and bodies that stop
+  costing anything once they settle. A raycast vehicle, a character controller that handles stairs
+  and slopes, and inverse kinematics. [Fluid simulation](src/engine/physics/mls-mpm/README.md) is
+  separate and can run off the main thread.
+* **Audio.** The Wwise/FMOD feature set without the middleware: events, a mixer bus tree, real-time
+  parameters, voice stealing, snapshots and ducking, all authored as engine data you can serialize.
+  Opt-in [acoustic simulation](src/engine/sound/simulation/README.md) adds occlusion, transmission
+  and reverb driven by the scene's own geometry.
+* **[Networking](src/engine/network/README.md).** Server-authoritative rollback: client-side
+  prediction, reconciliation, and binary snapshots. Transports for WebRTC, WebTransport, WebSocket
+  and Node UDP, plus loopback and deliberately lossy ones for tests. Bandwidth metering, packet
+  record and replay, and cross-peer desync detection.
+* **Navigation & AI.** Grid A\*, and a [navigation mesh](src/engine/navigation/mesh/README.md) with
+  any-angle paths and obstacle carving at build time. Behaviour trees and blackboards, [Monte-Carlo
+  tree search](src/engine/intelligence/mcts/README.md) for agents that search a game tree rather
+  than follow one, and a planner for spending limited resources. Ray, box, frustum and point queries
+  against the scene.
+* **Procedural generation.** [A rule-driven grid generator](src/generation): cellular automata,
+  layered grids, rule sets that place markers and spawn entities, theme-driven selection. Generation
+  composes as tasks over shared state, so building a world is a graph of steps rather than a script.
+* **Assets & codecs.** glTF, including meshopt compression, loading into **entities** rather than
+  one opaque tree. PNG, JPEG and AVIF decoded in-engine - the AV1 codec is a from-scratch encoder
+  *and* decoder in pure JavaScript, no WebAssembly. Web-first asset streaming, and binary
+  serialization that upgrades across versions.
+* **Tooling.** An in-app editor that attaches to and detaches from a running engine. [GPU profile
+  capture](src/shade/device/timing/profile/SGPT_FORMAT.md) that records per-pass timings and leaves
+  the build entirely when you don't import it. A software WebGPU implementation and a WGSL
+  interpreter, so shaders and pipelines are testable on machines with no GPU.
+* **Everything smaller.** Input across touch, mouse, keyboard and gamepad behind one abstraction ·
+  an optional DOM UI layer, replaceable with React or Vue · colour management with perceptual
+  spaces, HDR transfer functions, tone mapping and gamut clipping · node graphs · achievements ·
+  localisation · key-value storage over IndexedDB.
+
+Held to **~15,000 tests** - determinism, adversarial and shader-emulation suites among them.
 
 ---
 
-## 🔬 Shipping a build
+## 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,100 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
@@ -138,27 +282,21 @@ export default defineConfig({
 });
 ```
 
----
-
-## 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                                             |
+Note that those defaults also strip `console.*`.
 
 ---
 
-## License & Copyright
+## Licence & pricing
+
 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.
+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.
+See [LICENSE](LICENSE) for the terms covering this package, and the
+[pricing page](https://meep.company-named.com/pricing/) for the tier ladder.

package/editor/prototypeEditorShell.js

@@ -16,7 +16,16 @@ import { TransformAttachmentSystem } from "../src/engine/ecs/transform-attachmen
 import { EngineHarness } from "../src/engine/EngineHarness.js";
 import TopDownCameraController from "../src/engine/graphics/ecs/camera/topdown/TopDownCameraController.js";
 import { DebugDrawSystem } from "../src/engine/graphics3/DebugDrawSystem.js";
+import {
+    HighlightOutlineSystem
+} from "../src/engine/graphics3/HighlightOutlineSystem.js";
 import { MeshSystem } from "../src/engine/graphics3/MeshSystem.js";
+import {
+    ShadedGeometryHighlightSystem
+} from "../src/engine/graphics/ecs/highlight/system/ShadedGeometryHighlightSystem.js";
+import {
+    SGMeshHighlightSystem
+} from "../src/engine/graphics/ecs/mesh-v2/aggregate/SGMeshHighlightSystem.js";
 import {
     ShadedGeometrySystem
 } from "../src/engine/graphics3/ShadedGeometrySystem.js";
@@ -73,16 +82,31 @@ function addModelLoaders(config) {
 async function addGraphicsSystems(engine) {
     const em = engine.entityManager;
 
-    await em.addSystem(new MeshSystem(
+    const meshes = new MeshSystem(
         engine.graphics,
         EngineHarness.shadeScene(engine),
         url => load_model_scene_bundle(engine.assetManager, url)
-    ));
+    );
+
+    await em.addSystem(meshes);
 
     // a model with neither skin nor clip becomes entities, and its primitives are drawn by the
     // system that owns primitives (D47)
     await em.addSystem(new ShadedGeometrySystem(engine.graphics, EngineHarness.shadeScene(engine)));
 
+    /*
+     One outline pass and both of its sources, because the editor offers a `Highlight` editor and
+     either kind of thing can be carrying the component: a model placed from the mesh library is an
+     `SGMesh`, and anything built in place is a `ShadedGeometry`. The pass is registered once and
+     draws for both — a pass per kind would read the whole visibility buffer once per kind, and the
+     last would paint over the rest.
+    */
+    const outline = new HighlightOutlineSystem(engine.graphics);
+
+    await em.addSystem(outline);
+    await em.addSystem(new SGMeshHighlightSystem(outline, meshes));
+    await em.addSystem(new ShadedGeometryHighlightSystem(outline));
+
     await em.addSystem(new ParticleEmitterSystem(engine.graphics, engine.assetManager));
 
     // the editor's selection box is the debug-draw pass's first consumer (V5)

package/package.json

@@ -3,10 +3,10 @@
   "license": "SEE LICENSE IN LICENSE",
   "productName": "Meep",
   "homepage": "https://meep.company-named.com/",
-  "description": "Pure JavaScript game engine. Fully featured and production ready.",
+  "description": "Advanced 3D game engine",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "3.13.0",
+  "version": "3.14.0",
   "exports": {
     "./build/*": "./build/*",
     "./src/*": "./src/*",
@@ -39,7 +39,8 @@
     "README.md",
     "!src/**/*.spec.js",
     "!editor/**/*.spec.js",
-    "!src/**/__fixtures__/**"
+    "!src/**/__fixtures__/**",
+    "!src/shade/renderer/texture/noise/stbn/images/**"
   ],
   "dependencies": {
     "opentype.js": "1.3.3",

package/src/core/geom/3d/shape/ConvexHullShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ConvexHullShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/ConvexHullShape3D.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IA8CI;;;;;;;OAOG;IACH,sBAJW,YAAY,WACZ,WAAW,GACT,iBAAiB,CAQ7B;IA1DD;;;;OAIG;IACH,UAFU,YAAY,CAES;IAE/B;;;;OAIG;IACH,SAFU,WAAW,CAEQ;IAE7B;;;;;;OAMG;IACH,cAFU,WAAW,CAEa;IAElC,0BAA0B;IAC1B,YADW,WAAW,CACU;IAEhC;;;;;;OAMG;IACH,iBAA+B;IAE/B,oCAAoC;IACpC,eAA6B;IAE7B,8BAA8B;IAC9B,iBAAa;IAEb,8BAA8B;IAC9B,uBAAmB;IAkBnB;;;OAGG;IACH,kBA8EC;IAKD,wCAIC;IAED;;;;;OAKG;IACH,qGAwCC;IAED;;;;;;;;OAQG;IACH,yCAEC;IAED;;;;OAIG;IACH,wCAEC;IAED,qCAkBC;IAED;;;OAGG;IACH,oCAgBC;IAED;;;OAGG;IACH,6CAiBC;IAED,mEAEC;IAED,4DAoBC;IAGD;;;OAGG;IACH,cAHW,iBAAiB,GACf,OAAO,CAanB;IAcL;;;;OAIG;IACH,8BAFU,OAAO,CAE8B;CAP9C;gCAvX+B,sBAAsB"}
+{"version":3,"file":"ConvexHullShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/ConvexHullShape3D.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IA8CI;;;;;;;OAOG;IACH,sBAJW,YAAY,WACZ,WAAW,GACT,iBAAiB,CAQ7B;IA1DD;;;;OAIG;IACH,UAFU,YAAY,CAES;IAE/B;;;;OAIG;IACH,SAFU,WAAW,CAEQ;IAE7B;;;;;;OAMG;IACH,cAFU,WAAW,CAEa;IAElC,0BAA0B;IAC1B,YADW,WAAW,CACU;IAEhC;;;;;;OAMG;IACH,iBAA+B;IAE/B,oCAAoC;IACpC,eAA6B;IAE7B,8BAA8B;IAC9B,iBAAa;IAEb,8BAA8B;IAC9B,uBAAmB;IAkBnB;;;OAGG;IACH,kBAkFC;IAUD,wCAQC;IAED;;;;;OAKG;IACH,qGAwCC;IAED;;;;;;;;OAQG;IACH,yCAEC;IAED;;;;OAIG;IACH,wCAEC;IAED,qCAkBC;IAED;;;OAGG;IACH,oCAgBC;IAED;;;OAGG;IACH,6CAiBC;IAED,mEAEC;IAED,4DAwBC;IAGD;;;OAGG;IACH,cAHW,iBAAiB,GACf,OAAO,CAanB;IAcL;;;;OAIG;IACH,8BAFU,OAAO,CAE8B;CAP9C;gCAtY+B,sBAAsB"}

package/src/core/geom/3d/shape/ConvexHullShape3D.js

@@ -1,10 +1,10 @@
 import { hash_mix2 } from "../../../math/hash/hash_mix2.js";
 import { computeHashFloat } from "../../../primitives/numbers/computeHashFloat.js";
+import { aabb3_from_v3_array } from "../aabb/aabb3_from_v3_array.js";
+import { convex_polyhedron3_raycast } from "../polyhedron/convex_polyhedron3_raycast.js";
 import { tri3_closest_point } from "../triangle/tri3_closest_point.js";
 import { AbstractShape3D } from "./AbstractShape3D.js";
 import { compute_signed_distance_gradient_by_sampling } from "./util/compute_signed_distance_gradient_by_sampling.js";
-import { aabb3_from_v3_array } from "../aabb/aabb3_from_v3_array.js";
-import { convex_polyhedron3_raycast } from "../polyhedron/convex_polyhedron3_raycast.js";
 
 /**
  * Convex polyhedron collider.
@@ -161,9 +161,13 @@ export class ConvexHullShape3D extends AbstractShape3D {
             //   Σ a·n === Σ (a − o)·n over a closed surface, since Σ n = 0.
             vol6 += (ax - ox) * nx + (ay - oy) * ny + (az - oz) * nz;
 
-            nx /= len; ny /= len; nz /= len;
+            nx /= len;
+            ny /= len;
+            nz /= len;
             const o = f * 4;
-            planes[o] = nx; planes[o + 1] = ny; planes[o + 2] = nz;
+            planes[o] = nx;
+            planes[o + 1] = ny;
+            planes[o + 2] = nz;
             planes[o + 3] = nx * ax + ny * ay + nz * az;
         }
         this.__planes = planes;
@@ -178,13 +182,22 @@ export class ConvexHullShape3D extends AbstractShape3D {
         this.face_loops = idx;
     }
 
-    get volume() { return this.__volume; }
-    get surface_area() { return this.__surface_area; }
+    get volume() {
+        return this.__volume;
+    }
+
+    get surface_area() {
+        return this.__surface_area;
+    }
 
     compute_bounding_box(result) {
         const b = this.__bbox;
-        result[0] = b[0]; result[1] = b[1]; result[2] = b[2];
-        result[3] = b[3]; result[4] = b[4]; result[5] = b[5];
+        result[0] = b[0];
+        result[1] = b[1];
+        result[2] = b[2];
+        result[3] = b[3];
+        result[4] = b[4];
+        result[5] = b[5];
     }
 
     /**
@@ -201,9 +214,9 @@ export class ConvexHullShape3D extends AbstractShape3D {
     ) {
 
         const v = this.vertices;
-        const vc = v.length / 3;
+        const vertex_array_length = v.length;
 
-        if (vc === 0) {
+        if (vertex_array_length === 0) {
 
             result[result_offset] = 0;
             result[result_offset + 1] = 0;
@@ -212,27 +225,27 @@ export class ConvexHullShape3D extends AbstractShape3D {
             return;
         }
 
-        let best = -Infinity;
-        let bi = 0;
+        let best_distance = -Infinity;
+        let best_offset = 0;
 
-        for (let i = 0; i < vc; i++) {
+        for (let offset = 0; offset < vertex_array_length; offset += 3) {
 
-            const v_x = v[i * 3];
-            const v_y = v[i * 3 + 1];
-            const v_z = v[i * 3 + 2];
+            const v_x = v[offset];
+            const v_y = v[offset + 1];
+            const v_z = v[offset + 2];
 
             const d = direction_x * v_x + direction_y * v_y + direction_z * v_z;
 
-            if (d > best) {
-                best = d;
-                bi = i;
+            if (d > best_distance) {
+                best_distance = d;
+                best_offset = offset;
             }
 
         }
 
-        result[result_offset] = v[bi * 3];
-        result[result_offset + 1] = v[bi * 3 + 1];
-        result[result_offset + 2] = v[bi * 3 + 2];
+        result[result_offset] = v[best_offset];
+        result[result_offset + 1] = v[best_offset + 1];
+        result[result_offset + 2] = v[best_offset + 2];
     }
 
     /**
@@ -342,10 +355,14 @@ export class ConvexHullShape3D extends AbstractShape3D {
             const d2 = tri3_closest_point(scratch_closest, 0, px, py, pz, ax, ay, az, bx, by, bz, cx, cy, cz);
             if (d2 < best_d2) {
                 best_d2 = d2;
-                bx_ = scratch_closest[0]; by_ = scratch_closest[1]; bz_ = scratch_closest[2];
+                bx_ = scratch_closest[0];
+                by_ = scratch_closest[1];
+                bz_ = scratch_closest[2];
             }
         }
-        result[0] = bx_; result[1] = by_; result[2] = bz_;
+        result[0] = bx_;
+        result[1] = by_;
+        result[2] = bz_;
     }
 
 
@@ -387,4 +404,3 @@ ConvexHullShape3D.prototype.isConvexHullShape3D = true;
 
 // closest-point-on-triangle output for the surface-scan query helpers
 const scratch_closest = new Float64Array(3);
-const scratch_point = new Float64Array(3);