@woosh/meep-engine 3.13.1 → 3.14.1

package/README.md

@@ -1,134 +1,240 @@
 # 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.
+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.
 
-* **Virtual geometry and virtual textures:** `.vgeo` streaming, a GPU scene database, GPU animation and skinning.
+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.
 
-* **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.
+**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.
 
-* **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.
+In development since 2013, shipped in a commercial Steam release, and held to **~15,000 tests** -
+determinism, adversarial and shader-emulation suites among them.
 
 ---
 
-## ⚙️ 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.
+# 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:
 
-* **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.
+```js
+engine.graphics.dynamic_resolution.enabled = false;      // or .target_frame_rate / .min_scale
+engine.graphics.renderer.feature_taa_enabled = false;    // only valid after start()
+```
 
-* **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.
+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.
 
-* **Diagnostics:** bandwidth metering, packet record/replay, cross-peer desync detection.
+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`.
 
-## 🧠 Navigation & AI
+## Correct by default
 
-* **Pathfinding:** A* grid search, and a navigation mesh with build-time obstacle carving and exact (Polyanya) any-angle queries.
+The out-of-the-box configuration is the expensive-and-correct one, not the safe-and-cheap one.
 
-* **Behavior trees and blackboards** for agent state.
+**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.
 
-* **Monte-Carlo tree search**, for decision logic that searches a game tree rather than following one.
+* **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.
 
-* **Resource allocation solver:** plan optimal actions against limited resources (ammo, health, currency).
+Opt-in, off by default: screen-space reflections, motion blur, depth of field, ReSTIR direct
+lighting, and a reference path tracer.
 
-* **Spatial queries:** 2-wide and 8-wide BVH implementations for ray, box, frustum and point queries.
+**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.
 
-## 🌱 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.
+## WebGPU only
 
-## 📦 Assets & Codecs
+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.
 
-* **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.
+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).
 
-* **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.
+## Numbers
 
-* **Streaming:** web-first asset streaming. The engine runs before assets even load.
+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.
 
-* **Serialization:** binary, with version upgrading.
+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.
 
 ---
 
-## 🛠️ 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.
 
 ---
 
-## 🔬 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 +244,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.1",
+  "version": "3.14.1",
   "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/engine/graphics/ecs/highlight/system/ShadedGeometryHighlightSystem.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Outlines a highlighted primitive — one that is not a model.
+ *
+ * **A `ShadedGeometry` is not an `SGMesh`, and {@link SGMeshHighlightSystem} reads only the latter.**
+ * A model is a file that expanded into entities, and the highlight sits on the root; a primitive is
+ * a geometry and a material some tool built directly, and the highlight sits on the thing itself.
+ * This tuple was the last `HighlightSystemBase` subclass still standing when the three renderer was
+ * deleted, and it went with it — so between then and now, everything built rather than loaded had no
+ * outline. This file is that path restored, at the import path it used to occupy.
+ *
+ * **It is a second source, not a second pass.** Everything about drawing the outline —
+ * the pass, the lookup table, the renderer — belongs to {@link HighlightOutlineSystem}, and this
+ * contributes entries to it through {@link HighlightOutlineSystem#add_entry}. Two passes would each
+ * read the whole visibility buffer and the later would paint over the earlier's outline wherever
+ * they named the same row.
+ *
+ * The walk is one node, because that is what the component is: `ShadedGeometry` is *"not a
+ * hierarchical data structure"* in its own words, and `ShadedGeometrySystem` gives it exactly one
+ * row. A primitive whose system has not linked it yet has no node and contributes nothing, which is
+ * the same silence every other reader of `ShadedGeometry.node` already tolerates.
+ */
+export class ShadedGeometryHighlightSystem extends System<any> {
+    /**
+     * @param {HighlightOutlineSystem} outline the system that owns the outline pass
+     */
+    constructor(outline: HighlightOutlineSystem);
+    dependencies: (typeof ShadedGeometry | typeof Highlight)[];
+    startup(entityManager: any): Promise<void>;
+    shutdown(entityManager: any): Promise<void>;
+    /**
+     * @param {Highlight} highlight
+     * @param {ShadedGeometry} geometry
+     * @param {number} entity
+     */
+    link(highlight: Highlight, geometry: ShadedGeometry, entity: number): void;
+    /**
+     * @param {Highlight} highlight
+     * @param {ShadedGeometry} geometry
+     * @param {number} entity
+     */
+    unlink(highlight: Highlight, geometry: ShadedGeometry, entity: number): void;
+    #private;
+}
+import { System } from "../../../../ecs/System.js";
+import { ShadedGeometry } from "../../mesh-v2/ShadedGeometry.js";
+import Highlight from "../Highlight.js";
+//# sourceMappingURL=ShadedGeometryHighlightSystem.d.ts.map

package/src/engine/graphics/ecs/highlight/system/ShadedGeometryHighlightSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShadedGeometryHighlightSystem.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/highlight/system/ShadedGeometryHighlightSystem.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAiBI;;OAEG;IACH,6CAMC;IAzBD,2DAA2C;IA2B3C,2CAEC;IAED,4CAWC;IAED;;;;OAIG;IACH,gBAJW,SAAS,YACT,cAAc,UACd,MAAM,QAgBhB;IAED;;;;OAIG;IACH,kBAJW,SAAS,YACT,cAAc,UACd,MAAM,QAYhB;;CACJ;uBA3GsB,2BAA2B;+BAEnB,iCAAiC;sBAD1C,iBAAiB"}

package/src/engine/graphics/ecs/highlight/system/ShadedGeometryHighlightSystem.js

@@ -0,0 +1,109 @@
+import { assert } from "../../../../../core/assert.js";
+import { System } from "../../../../ecs/System.js";
+import Highlight from "../Highlight.js";
+import { ShadedGeometry } from "../../mesh-v2/ShadedGeometry.js";
+
+/**
+ * Outlines a highlighted primitive — one that is not a model.
+ *
+ * **A `ShadedGeometry` is not an `SGMesh`, and {@link SGMeshHighlightSystem} reads only the latter.**
+ * A model is a file that expanded into entities, and the highlight sits on the root; a primitive is
+ * a geometry and a material some tool built directly, and the highlight sits on the thing itself.
+ * This tuple was the last `HighlightSystemBase` subclass still standing when the three renderer was
+ * deleted, and it went with it — so between then and now, everything built rather than loaded had no
+ * outline. This file is that path restored, at the import path it used to occupy.
+ *
+ * **It is a second source, not a second pass.** Everything about drawing the outline —
+ * the pass, the lookup table, the renderer — belongs to {@link HighlightOutlineSystem}, and this
+ * contributes entries to it through {@link HighlightOutlineSystem#add_entry}. Two passes would each
+ * read the whole visibility buffer and the later would paint over the earlier's outline wherever
+ * they named the same row.
+ *
+ * The walk is one node, because that is what the component is: `ShadedGeometry` is *"not a
+ * hierarchical data structure"* in its own words, and `ShadedGeometrySystem` gives it exactly one
+ * row. A primitive whose system has not linked it yet has no node and contributes nothing, which is
+ * the same silence every other reader of `ShadedGeometry.node` already tolerates.
+ */
+export class ShadedGeometryHighlightSystem extends System {
+    dependencies = [Highlight, ShadedGeometry];
+
+    /**
+     * @type {HighlightOutlineSystem}
+     */
+    #outline;
+
+    /**
+     * The entry each highlighted primitive has with {@link #outline}, which is the only handle on
+     * it: an entity that is both a model and a primitive has an entry from each contributing system,
+     * so the shared list cannot be keyed by entity and each contributor remembers its own.
+     *
+     * @type {Map<number, object>}
+     */
+    #entries = new Map();
+
+    /**
+     * @param {HighlightOutlineSystem} outline the system that owns the outline pass
+     */
+    constructor(outline) {
+        super();
+
+        assert.defined(outline, 'outline');
+
+        this.#outline = outline;
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+    }
+
+    async shutdown(entityManager) {
+        /*
+         Handing every entry back rather than trusting the outline system to have cleared its list
+         makes shutdown order between the two free — and `remove_entry` tolerates an entry that is
+         already gone, which is the case when the outline system went down first.
+        */
+        for (const entry of this.#entries.values()) {
+            this.#outline.remove_entry(entry);
+        }
+
+        this.#entries.clear();
+    }
+
+    /**
+     * @param {Highlight} highlight
+     * @param {ShadedGeometry} geometry
+     * @param {number} entity
+     */
+    link(highlight, geometry, entity) {
+        const entry = this.#outline.add_entry(entity, highlight, visitor => {
+            const node = geometry.node;
+
+            if (node === null || node === undefined) {
+                // not in the scene: either `ShadedGeometrySystem` has not linked it yet, or it is
+                // not running at all, and neither is this system's to complain about
+                return;
+            }
+
+            visitor(node);
+        });
+
+        this.#entries.set(entity, entry);
+    }
+
+    /**
+     * @param {Highlight} highlight
+     * @param {ShadedGeometry} geometry
+     * @param {number} entity
+     */
+    unlink(highlight, geometry, entity) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        this.#entries.delete(entity);
+
+        this.#outline.remove_entry(entry);
+    }
+}