# Meep documentation — full text > Every page of the Meep engine documentation, concatenated as Markdown in the order the site's sidebar lists them. Meep is a source-available JavaScript game engine with a pure ECS core, published on npm as @woosh/meep-engine. Source: https://meep.company-named.com/docs/ Index of this and every other page: https://meep.company-named.com/llms.txt Written against: @woosh/meep-engine 3.71.0 Pages: 64 --- # Getting started Section: Getting started Source: https://meep.company-named.com/docs/getting-started/ Description: A 10-minute tour of the Meep engine, from install to a lit cube rendering on WebGPU. Meep is a pure-ECS, zero-allocation JavaScript game engine. A Meep game is plain code from end to end, so you and any coding agent you work with read and change the same thing. Meep's renderer runs on **WebGPU only** - there is no WebGL path, no software fallback and no degradation tier. In practice that means **Chromium 149 or newer** today: the shaders declare the WGSL `immediate_address_space` extension, which Chrome shipped in 149/150, so an older browser acquires a GPU device and then fails the moment it tries to dispatch. The rest of the engine - ECS, physics, AI, generation, math, networking - never touches `navigator.gpu` and runs anywhere, including Node. ## What you'll need - A **WebGPU** browser. Chromium 149+ in practice; see [Installation](https://meep.company-named.com/docs/installation/) for the exact device floor and how to feature-detect it. - [Node.js](https://nodejs.org/en/download) 24 or newer. That's the toolchain requirement, not a constraint on what you ship to. - A bundler that handles ES modules and `@rollup/plugin-strip`. Vite, Rollup, esbuild and webpack 5 all work. - A valid Meep license. The [Free tier](https://meep.company-named.com/pricing/) covers evaluation and most hobby projects. ## Install ```bash npm install @woosh/meep-engine ``` The package ships the full engine source under `src/` - over 7,000 fine-grained ES modules, unobfuscated, no binary blobs. There is no prebuilt bundle to import: you import module paths directly and let your bundler tree-shake. `samples/engine/first-scene/` inside the package is the smallest complete application - boot, a lit scene, keyboard and pointer input - and the README beside it covers the Vite configuration, why a scene is authored in metres, and reference values for photometric lights. ## The two core pieces Meep splits the ECS into two cooperating objects: - **`EntityComponentDataset`** owns the entities and components - the data. - **`EntityManager`** owns the systems and orchestrates the simulation loop - the logic. You usually create one of each, register your systems on the `EntityManager`, attach the dataset, and then call `update(dt)` once per frame. ```js import { EntityComponentDataset } from "@woosh/meep-engine/src/engine/ecs/EntityComponentDataset.js"; import { EntityManager } from "@woosh/meep-engine/src/engine/ecs/EntityManager.js"; import { System } from "@woosh/meep-engine/src/engine/ecs/System.js"; import Entity from "@woosh/meep-engine/src/engine/ecs/Entity.js"; import { Transform64 } from "@woosh/meep-engine/src/engine/ecs/transform/Transform64.js"; import { t64_announce_change } from "@woosh/meep-engine/src/engine/ecs/transform/t64_announce_change.js"; import Vector3 from "@woosh/meep-engine/src/core/geom/Vector3.js"; ``` ## Spawning entities (high-level API) The fluent way to build an entity is through the `Entity` class. It's a thin wrapper that lets you compose an entity in one expression and then commit it to a dataset. First, a component to attach. Components are just classes - tiny, focused data containers. `Transform64` is built in; here's a `Velocity` of your own: ```js class Velocity { velocity = new Vector3(0, 0, 0); } ``` Now compose an entity from a `Transform64` and a `Velocity`: ```js const ecd = new EntityComponentDataset(); const t = new Transform64(); t.setTranslation(0, 0, 0); const v = new Velocity(); v.velocity.set(1, 0, 0); // moving along +X at 1 unit/sec const id = new Entity() .add(t) .add(v) .build(ecd); ``` `Entity` is the high-level builder. It hides the verbosity of the low-level `dataset.createEntity()` + `addComponentToEntity()` calls and gives you a chainable API. You can also construct a `Transform64` from JSON: ```js const t = Transform64.fromJSON({ translation: { x: 0, y: 0, z: 0 } }); ``` `Transform64` is a `Float64Array` of 23 elements: a matrix at `0..15` whose translation column *is* the translation, a rotation quaternion at `16..19` and a scale at `20..22`. Read a component with `translation_x` … `scale_z`, write one with `setTranslation` / `setRotation` / `setScale`, and call `updateMatrix()` after a rotation or a scale so the matrix catches up. The `Velocity` above carries a single `velocity` vector. Components hold no logic of their own - that lives in systems. ## Iterating entities To do something with every entity matching a component shape, use `traverseEntities`: ```js ecd.traverseEntities( [Transform64, Velocity], (transform, vel, entity) => { transform.setTranslation( transform.translation_x + vel.velocity.x * dt, transform.translation_y + vel.velocity.y * dt, transform.translation_z + vel.velocity.z * dt, ); // a Transform64 has no signals: nothing downstream sees the move until // the writer says so t64_announce_change(ecd, entity); } ); ``` The callback receives one argument per requested component, plus the entity id. Internally the dataset walks a tight typed-array index - querying for a component shape with a million matches has the same per-iteration cost as querying for a hundred. ## Wiring up a system Most of the time you don't call `traverseEntities` directly from your game loop - you put the logic in a `System` and let the `EntityManager` schedule it for you. ```js class MovementSystem extends System { dependencies = [Transform64, Velocity]; update(timeDelta) { const ecd = this.entityManager.dataset; ecd.traverseEntities( [Transform64, Velocity], (transform, vel, entity) => { transform.setTranslation( transform.translation_x + vel.velocity.x * timeDelta, transform.translation_y + vel.velocity.y * timeDelta, transform.translation_z + vel.velocity.z * timeDelta, ); t64_announce_change(ecd, entity); } ); } } const em = new EntityManager(); em.addSystem(new MovementSystem()); em.attachDataset(ecd); em.startup(); // Per-frame: em.update(0.016); // advance the simulation by 16ms ``` The `dependencies` array tells the engine which components the system cares about, which lets it compute an efficient execution order. The base `System` class also provides a `fixedUpdate(dt)` hook for physics-stable stepping, and `link(...)/unlink(...)` hooks for per-entity setup and teardown. > `em.simulate(dt)` is a deprecated alias of `update`; call `update`. `MovementSystem` is deliberately the smallest system that does something - a hand-rolled integrator to show the shape. You won't write your own for real physics: Meep ships a built-in `PhysicsSystem` that simulates `RigidBody` and `Collider` components (gravity, contacts, joints, raycasts) for you. See the [physics docs](https://meep.company-named.com/docs/physics/overview/) for that path. ## A live example Everything above, running right here on the page - a single cube spawned with the high-level `Entity` builder and drawn by `ShadedGeometrySystem`. Drag to orbit, scroll to zoom. This is a real `meep` build embedded in the docs, not a video, so it needs a WebGPU browser like everything else the renderer draws. Two pieces are new here. `EngineHarness` spins up the canvas, camera and lights so there's something to look at. And `ShadedGeometrySystem` - the system that puts an entity's geometry in front of the renderer - is constructed with the graphics facade and the renderer's `Scene` to draw into, which `EngineHarness.shadeScene(engine)` hands out (one per engine, made on first ask). The engine's view stack uses `pointer-events: none` so DOM UI can sit over the game. The render viewport opts back in with `auto`, and `GraphicsEngine` preserves that setting when it mounts or replaces the canvas. Pointer input needs no extra canvas styling in this example. ```js import { EngineHarness } from "@woosh/meep-engine/src/engine/EngineHarness.js"; import Entity from "@woosh/meep-engine/src/engine/ecs/Entity.js"; import { Transform64 } from "@woosh/meep-engine/src/engine/ecs/transform/Transform64.js"; import { ShadedGeometry } from "@woosh/meep-engine/src/engine/graphics/ecs/mesh-v2/ShadedGeometry.js"; import { ShadedGeometrySystem } from "@woosh/meep-engine/src/engine/graphics3/ShadedGeometrySystem.js"; import { make_box_geometry } from "@woosh/meep-engine/src/shade/renderer/geometry/primitives/make_box_geometry.js"; import { meshlet_geometry_build_from_geometry } from "@woosh/meep-engine/src/shade/renderer/geometry/meshlet_geometry_build_from_geometry.js"; import { StandardShadeMaterial } from "@woosh/meep-engine/src/shade/renderer/material/StandardShadeMaterial.js"; import { Color } from "@woosh/meep-engine/src/core/color/Color.js"; import Vector3 from "@woosh/meep-engine/src/core/geom/Vector3.js"; // EngineHarness.bootstrap creates the EntityManager + dataset, attaches a // canvas, and gives us a hook to register systems. ShadedGeometrySystem is what // actually draws any entity carrying a ShadedGeometry component. const engine = await EngineHarness.bootstrap({ configuration: (config, engine) => { config.addSystem(new ShadedGeometrySystem(engine.graphics, EngineHarness.shadeScene(engine))); }, }); // buildBasics frames the camera, adds a directional sun with the scene's // own sky behind it, and wires the orbital drag-to-look / WASD-to-pan / // wheel-to-zoom controls. await EngineHarness.buildBasics({ engine, enableTerrain: false, enableWater: false, enableLights: true, enableShadows: false, focus: new Vector3(0, 0, 0), distance: 4, pitch: 0.6, yaw: 0.4, showFps: false, }); const ecd = engine.entityManager.dataset; // The shape and the material are the renderer's. `make_box_geometry` builds an // authoring-form Geometry; `meshlet_geometry_build_from_geometry` clusters it // into the GPU form the renderer draws - a precompute you do once per shape, // not per frame. const cubeGeometry = meshlet_geometry_build_from_geometry(make_box_geometry(1, 1, 1)); // Material colours are linear. `Color.parse` speaks encoded sRGB - the space a // hex code from a design tool is in - so decode it before assigning. const cubeMaterial = new StandardShadeMaterial(); cubeMaterial.diffuse_color.copy(Color.from_sRGB_to_linear(Color.parse("#4ef0a8"))); const cubeMesh = ShadedGeometry.from(cubeGeometry, cubeMaterial); const t = new Transform64(); t.setTranslation(0, 0, 0); new Entity() .add(t) .add(cubeMesh) .build(ecd); ``` Three things in there are worth naming, because they're the ones people trip on: - **The component and the system live in different trees.** `ShadedGeometry` is at `graphics/ecs/mesh-v2/`; every rendering *system* is under `graphics3/` and takes explicit collaborators rather than the engine. - **Meshletisation is a one-time cost per shape, not per entity.** Build the `MeshletGeometry` once and hand the same one to every `ShadedGeometry` that needs it. - **Something has to give the scene to the graphics engine.** `ShadedGeometrySystem` deliberately doesn't; `LightSystem` does, and `buildBasics({ enableLights: true })` registers it for you. Drop the lights and you get a black frame with the cube in it. See the [rendering overview](https://meep.company-named.com/docs/rendering/overview/) for the wiring rule. ## Adding particle effects Use `ParticleEffect` with `Transform64` for GPU particles. Register `GPUParticleEmitterSystem(engine.graphics, EngineHarness.shadeScene(engine), engine.assetManager)` in the bootstrap configuration, alongside any other rendering systems. A particle simulation has three authored parts: a layout declaring each particle's state, an **INIT** graph that seeds newborn particles, and an **UPDATE** graph that moves, colours and eventually kills them. Compile those graphs with `create_particle_effect`, then pass the result to `ParticleEffect.from` with an emission rate, texture and render bindings. The system handles GPU simulation and the shared sprite atlas. Start with the [complete small graph](https://meep.company-named.com/docs/rendering/particles/#a-complete-small-graph), or open the [five-effect particle example](https://meep.company-named.com/examples/particles/) and choose **View source**. Its `src/particleGraphs.js` keeps the simulation graphs in the example, and `src/specs/` holds the editable layer settings and curves. ## Production builds In development the engine runs 6,000+ assertions that catch invalid component state, out-of-range indices and broken invariants at the moment they happen. For production, strip them with `@rollup/plugin-strip`: ```js // vite.config.js import { defineConfig } from "vite"; import strip from "@rollup/plugin-strip"; export default defineConfig({ plugins: [ { ...strip(), apply: "build" }, ], }); ``` The plugin's defaults already cover `assert.*`. They also cover `console.*` - pass `strip({ functions: ["assert.*"] })` if you want to keep your own logging. Stripped builds run at native speed and tree-shake down to only the modules you actually import. ## Next up - [Installation guide](https://meep.company-named.com/docs/installation/) - device floor, peer dependencies, bundler configuration. - [ECS overview](https://meep.company-named.com/docs/ecs-overview/) - the architecture and design philosophy. - [Rendering overview](https://meep.company-named.com/docs/rendering/overview/) - how the renderer puts a frame together. - [Migrating 2.x to 3](https://meep.company-named.com/docs/reference/migrating-2-to-3/) - if you have an existing project. - [FAQ](https://meep.company-named.com/docs/faq/) - answers to the most common questions. For licensing - tiers, pricing, contract language - see [/pricing](https://meep.company-named.com/pricing/) and [/license](https://meep.company-named.com/license/). > Heads up - this documentation is being built out as we go. Subsystems with thinner coverage are marked `draft` in the sidebar. Email us if there's a specific area you need expanded sooner. --- # Installation Section: Getting started Source: https://meep.company-named.com/docs/installation/ Description: Install the engine, meet the WebGPU device floor, and configure your bundler for development and production. ## From npm ```bash npm install @woosh/meep-engine ``` This pulls the latest published release. ## What comes with it Two runtime dependencies, installed for you: | Package | Version | What it's for | |---|---|---| | `opentype.js` | 1.3.4 | Font parsing | | `robust-predicates` | 3.0.3 | Exact geometric predicates for triangulation and hull construction | PNG and compressed texture decoding use the platform's asynchronous `DecompressionStream` API. And one peer dependency: | Peer | Version | Required? | Who imports it | |---|---|---|---| | `dat.gui` | `>=0.7.0` | **Yes** | `DatGuiController`, `DatGuiUtils`, the built-in `OptionsView`, and one in-tree prototype script | `dat.gui` carries no `optional` flag, so npm installs it alongside the engine. It enters your bundle only if you import a module that imports it. The harness FPS counter - `EngineHarness.addFpsCounter`, or `buildBasics({ showFps: true })` - is `FrameRateView`, part of the engine; it needs no package. **There is no renderer peer dependency.** The renderer ships inside the package. The package declares `"engines": { "node": ">=24" }`. That is the Node version the toolchain expects when you install and build, not a constraint on the browsers you ship to. ## There is no prebuilt bundle `package.json` has no `main` and no `module` field. The `exports` map publishes `./src/*`, `./build/*`, `./editor/*`, `./samples/*`, the root `*.md` files and `./package.json`, and `build/` contains exactly two files: | File | What it is | |---|---| | `build/bundle-worker-image-decoder.js` | Prebuilt web worker for off-thread PNG decoding | | `build/bundle-worker-terrain.js` | Prebuilt web worker for terrain processing | Everything else you import by source path, and your bundler builds it with the rest of your application. Both workers are located relative to the engine's own modules, so they need no configuration. If your page sets `Cross-Origin-Embedder-Policy: require-corp` - which WebGPU pushes you toward - serve them with `Cross-Origin-Resource-Policy` as well, or the worker's `importScripts` is blocked with the same `NetworkError` a missing file gives. Without the terrain worker, terrain does not build; without the image-decoder worker, PNG decoding falls back to the main thread, which is correct and slower. The package also ships `samples/engine/first-scene/`, the smallest complete application - boot, a lit scene, keyboard and pointer input in about eighty lines - and `samples/engine/README.md` beside it, with the bundler stanza below, why a scene is authored in metres, and photometric reference values for lights. ## Importing Meep is distributed as fine-grained ES modules - over 7,000 of them. There's no monolithic root import; the `exports` map is a 1:1 passthrough of `src/`, so a module's path in the package is its import specifier: ```js import { EntityManager } from "@woosh/meep-engine/src/engine/ecs/EntityManager.js"; import { Transform64 } from "@woosh/meep-engine/src/engine/ecs/transform/Transform64.js"; import Entity from "@woosh/meep-engine/src/engine/ecs/Entity.js"; ``` Export form varies by module - most are named, a handful are default (`Entity` and `Vector3` are both, for instance). The docs show the form that actually works for each symbol; when in doubt, open the file in `node_modules/@woosh/meep-engine/src/` and look for `export class` versus `export default`. Tree-shaking eliminates anything you don't reference - the bundle size of a "use the lerp function" demo is about four lines compiled. ## Browser and device requirements **WebGPU only.** There is no WebGL path, no software renderer, no RHI and no degradation tiers. Hardware below the floor is not accommodated; it is told clearly that it cannot run this. `Renderer.initialize()` checks the following before it will hand back a device: | Kind | Requirement | Why | |---|---|---| | Adapter feature | `indirect-first-instance` | GPU-driven indirect draws, used throughout | | Adapter feature | `float32-blendable` | Order-independent transparency | | Adapter feature | `texture-formats-tier1` | The hierarchical Z buffer is reduced in compute into `rg16float` storage textures; occlusion culling, SSR, screen-space shadows and light culling read it | | Adapter limit | `maxStorageBuffersPerShaderStage` >= 10 | The GPU-resident scene database | | Adapter limit | `maxColorAttachmentBytesPerSample` >= 32 | Large G-buffers | `timestamp-query`, `subgroups` and the three texture-compression features are requested when the adapter offers them and are never required - without `timestamp-query` the GPU timers simply go quiet instead of failing startup. ### When it fails - Every browser or GPU failure throws a `ShadeDeviceFailure` carrying a `ShadeDeviceFailureReason`: `WebGPUUnavailable` (no `navigator.gpu` at all), `AdapterUnavailable`, `BelowFloor`, `DeviceRequestFailed` or `DeviceLost`. Anything else that breaks arrives as whatever was thrown, so test `isShadeDeviceFailure` before reading `reason`. - The whole floor is checked before a device is requested, and `BelowFloor`'s message names every feature and limit the hardware misses, so it is worth surfacing rather than swallowing. - A device lost while running is **not** recovered. Everything built on it is gone with it; the honest response is to say so and reload. ### The WGSL extension nobody checks for you Beyond the WebGPU floor, the renderer's shaders declare `requires immediate_address_space;`. That's a WGSL *language* extension, not a `GPUFeatureName`, so it never appears in `adapter.features` and there is nothing to put in `requiredFeatures`. Detect it separately - synchronously, no adapter needed: ```js const ok = "gpu" in navigator && navigator.gpu.wgslLanguageFeatures.has("immediate_address_space"); ``` Chrome shipped it in 149/150. On an older Chromium the engine acquires a device successfully and then fails when it tries to dispatch, which reads like a shader bug rather than a browser one - so check the pair (WebGPU present, extension listed) rather than a user-agent string. Verified against real browsers: Chromium 148 fails, Chrome 151 runs. In practice the floor today is **Chromium 149 or newer**. ### Running without a GPU Nothing outside `src/shade/**` and `src/engine/graphics3/**` touches `navigator.gpu`. A simulation-only build - ECS, physics, AI, navigation, generation, math, storage, networking - runs in a browser without WebGPU, and under Node. For testing the graphics half without a GPU, the package ships a validating software WebGPU device under `src/shade/device/mock/`. ## Bundler configuration ### Vite ```js // vite.config.js import { defineConfig } from "vite"; import strip from "@rollup/plugin-strip"; export default defineConfig({ optimizeDeps: { // 7,000+ source modules: far too large to pre-bundle, and pre-bundling // rewrites the engine's own asset imports. Excluding it also stops Vite's // scanner discovering the engine's CommonJS dependencies, so name them. exclude: ["@woosh/meep-engine"], include: ["dat.gui", "opentype.js"], }, plugins: [ { ...strip(), apply: "build" }, ], }); ``` The `optimizeDeps` block is what a Vite dev server needs, and its absence fails in a way that does not mention meep: a `SyntaxError` about a package your application never referenced, and a blank page. ### Rollup ```js // rollup.config.js import strip from "@rollup/plugin-strip"; export default { // ... plugins: [ strip(), ], }; ``` ### Webpack Use `babel-plugin-strip` or a custom Terser pass. The pattern is the same - remove the `assert.*` calls before minification. ## What `strip` actually does In development, Meep runs 6,000+ assertions across the engine. They catch invalid component state, out-of-range indices, broken invariants and similar bugs at the moment they happen. In production you don't want that overhead, so the strip plugin removes the calls entirely. The resulting bundle is meaningfully smaller and runs at full speed. Two things about the defaults, since the configs above pass no options: - `@rollup/plugin-strip`'s default `functions` list is `['console.*', 'assert.*']`. `assert.*` is what the engine needs; `console.*` comes along with it, so a bare `strip()` also removes your own `console.log` calls. Pass `strip({ functions: ["assert.*"] })` to keep them. - The default `include` is `**/*.js`, which means the pass covers your application code as well as the engine's. ## Verifying your install ```js import { lerp } from "@woosh/meep-engine/src/core/math/lerp.js"; console.log(lerp(0, 10, 0.5)); // 5 ``` If that runs without errors, you're set up. `@woosh/meep-engine/package.json` is on the `exports` map, so `npm ls @woosh/meep-engine` and an import of it both report the installed version. ## Next Move on to the [ECS overview](https://meep.company-named.com/docs/ecs-overview/). If you have a 2.x project, [Migrating 2.x to 3](https://meep.company-named.com/docs/reference/migrating-2-to-3/) carries the import-path map and the constructor shapes. --- # ECS overview Section: ECS Source: https://meep.company-named.com/docs/ecs-overview/ Description: How Meep's Entity Component System differs from Unity, Bevy, and the rest - and why. Meep is a Pure ECS engine. The phrase carries weight, so this page unpacks what it means and how it shapes everything else in the engine. ## The three pieces **Entities** are identifiers. An entity is a 32-bit integer plus a generation counter - nothing more. No methods, no state of its own. **Components** are plain data. A `Transform64` is 23 doubles - a matrix, a translation, a rotation and a scale. A `Velocity` is `{ x, y, z }`. Components don't contain logic. **Systems** are functions that iterate over entities matching a component shape. A `MovementSystem` runs over every entity with `Transform64 + Velocity` and advances position by velocity each frame. ## "Pure" ECS Many engines call themselves ECS but smuggle in OOP under the hood. Unity's GameObject + MonoBehaviour is the canonical example - components are objects with methods, lifecycle hooks, and references to other components. The result is faster to prototype but slower to query and harder to optimize. Meep is strict: one component instance per type per entity, no methods on components, no lifecycle hooks beyond `init/destroy`. Every system iterates over flat typed arrays whenever possible. Memory layout is predictable. Component queries are O(1) cached. The trade is real - you write a little more code to wire systems together. In exchange, you get architectural clarity and performance that holds at scale. ## The hierarchy problem Pure ECS engines have historically struggled with scene graphs. Parent-child transforms imply a tree, and trees don't fit naturally into flat component arrays. Meep solves this with a dedicated hierarchy system that maintains parent-child links separately from the component arrays. Transforms still iterate as flat arrays for speed; hierarchy queries walk the tree only when needed. You get composable scene graphs without paying for them in the hot path. (Bevy uses a similar approach.) See [Hierarchy & attachment](https://meep.company-named.com/docs/ecs/hierarchy/) for the two components that express it. ## Tiered access Meep gives you two levels of API for the same data: - **High level.** `transform.setTranslation(x, y, z)`, `entity.add(component)`. Comfortable, slightly slower. - **Low level.** Raw typed array views, manual index math. For tight inner loops where you measured a bottleneck. You drop down only when you need to. The high-level API is usually fast enough. The transform below is that split made concrete: one type, reachable both ways. ## Transform64, the pose component `Transform64` is the pose: the ECS component you add to an entity, and the same type [meep's renderer](https://meep.company-named.com/docs/rendering/overview/) reads an entity's row from - there is no second transform anywhere. Every system that places something in the world - meshes, lights, decals, cameras, colliders, audio emitters - declares it in its dependency tuple. It `extends Float64Array`: one 23-element buffer holding a matrix and the three components, no sub-objects, no signals, no flags. Double precision throughout, one allocation per pose, and plain array stores instead of setter dispatch. ```js import { Transform64 } from "@woosh/meep-engine/src/engine/ecs/transform/Transform64.js"; const t = new Transform64(); t.setTranslation(10, 0, 20); t.setScale(2, 2, 2); t.updateMatrix(); // nothing touched the matrix before this line ``` The layout is part of the contract, so hot code can index the buffer directly instead of going through the accessors: | Elements | Contents | | --- | --- | | `0..15` | matrix, column-major | | `12..14` | translation `x, y, z` - **aliased into the matrix** | | `16..19` | rotation `x, y, z, w` | | `20..22` | scale `x, y, z` | The translation is not stored twice: it *is* the matrix's translation column, which gives the staleness rule its exact shape. A translation-only change lands in the matrix as it is written; a rotation or a scale does not, and the matrix is whatever `updateMatrix()` last composed until you call it again. The flip side is a matrix that can describe a pose that never existed - write a translation and a rotation without an `updateMatrix()` between them and it carries the new position under the old orientation. Because the matrix starts at element 0, a `Transform64` can be handed straight to any `mat4` helper, and `translation_x` … `scale_z` read a single component without allocating. The `translation` / `rotation` / `scale` getters return live views over the same buffer, but a freshly allocated view on every access - hold one rather than reading the property in a loop. Those views are bare `Float64Array`s, not a `Vector3` or a `Quaternion`, so they carry no maths of their own: `transform.rotation.fromAxisAngle(...)` throws rather than turning anything. Compose the value first and hand it over, or use the helper that does both - `t64_set_rotation_axis_angle(t, ax, ay, az, angle)` (`engine/ecs/transform/t64_set_rotation_axis_angle.js`), the `Transform64` counterpart of `Quaternion.fromAxisAngle`. Its axis must be unit length: a longer one does not fail, it quietly turns further. ### Say when you have written one A `Transform64` has no signals, so a write is invisible until the writer announces it. Everything that reacts to motion - the mesh and light placement, the parent/child sync, the terrain cling, the grid mirror - wakes on one entity event: ```js import { t64_announce_change } from "@woosh/meep-engine/src/engine/ecs/transform/t64_announce_change.js"; transform.setRotation(x, y, z, w); transform.updateMatrix(); t64_announce_change(ecd, entity); // once, after the last write of the group ``` The announcement names the transform, not what changed inside it, so a consumer that only tracks translation still wakes on a scale write - redundant work, not wrong work. Engine systems that write a pose announce it themselves: `PhysicsSystem` does it once per awake body per step, `TransformAttachmentSystem` for every child it composes, `PathFollowingSystem` for every follower it moves, and `TopDownCameraControllerSystem` for a camera whose pose its controller changed. `Transform` is a second pose type in the package - a class holding a live `Vector3` position, a `Quaternion` rotation and a `Vector3` scale, each with its own change signal, over an f32 matrix it recomposes for you. The serialization registry reads it, so a save written against it still loads; no system depends on it. Write `Transform64`, and use `t64_copy_from_transform` / `transform_copy_from_t64` where the two shapes meet. ## Why this matters on the web JavaScript's garbage collector punishes per-frame allocation patterns. Every `new Vector3()` in your update loop is a potential GC pause; on low-spec devices, those pauses turn into frame drops you can't paper over. Meep's zero-allocation discipline isn't a marketing line - it's a technical requirement. Components live in pre-allocated pools. Math operations write into out-parameters instead of returning new objects. Particle systems re-use buffers. The engine can run a million entities on a mid-range phone with stable frame timing because nothing is being allocated and garbage-collected each tick. ## Where to go next - [Physics overview](https://meep.company-named.com/docs/physics/overview/) - the rigid-body engine that ships in the box, built on the ECS. - [AI & simulation tools](https://meep.company-named.com/docs/ai-and-simulation/) - behavior trees, MCTS, and the decision-making toolkit. - [FAQ](https://meep.company-named.com/docs/faq/) - common questions. - The source itself: `src/engine/ecs/` is well-organized. Start with `EntityManager.js`. --- # Entities Section: ECS Source: https://meep.company-named.com/docs/ecs/entities/ Description: How entities are identified, built and destroyed with the high-level Entity builder and the low-level EntityComponentDataset, and how EntityReference gives you handles that survive ID reuse. An entity is an integer ID plus a generation counter - nothing more. The `EntityComponentDataset` recycles IDs when entities are removed; the generation counter makes a recycled ID distinguishable from a stale reference to the old one, without any extra bookkeeping. The data an entity carries lives in [components](https://meep.company-named.com/docs/ecs/components/); this page is about creating, reading, and destroying the entities themselves. ## Building an entity - the high-level API `Entity` is a chainable builder that accumulates components and then inserts everything into a dataset in one call: ```js import Entity from "@woosh/meep-engine/src/engine/ecs/Entity.js"; import { Transform64 } from "@woosh/meep-engine/src/engine/ecs/transform/Transform64.js"; const transform = new Transform64(); transform.setTranslation(10, 0, 20); const entityId = new Entity() .add(transform) .build(ecd); // returns the numeric entity ID ``` `add()` returns `this` for chaining. If the entity is already built when you call `add()`, the component is forwarded directly to the dataset. `entity.destroy()` removes the entity from the dataset and clears the builder so it can be rebuilt later. `Entity` also exposes: | Method | Description | | --- | --- | | `hasComponent(klass)` | Returns `true` if a component of that type is present | | `getComponent(klass)` | Returns the instance, or `null` if absent | | `getComponentSafe(klass)` | Same, but throws if absent | | `removeComponent(klass)` | Removes and returns the instance (also removes from dataset if built) | | `isBuilt` | `true` after `build()`, `false` after `destroy()` | ## Reading an existing entity into a builder If you have a numeric entity ID and a dataset, `Entity.readFromDataset(id, ecd)` reconstructs an `Entity` builder from the live components, so you can inspect or modify them with the same API. ## Creating and destroying entities directly `EntityComponentDataset` is the actual storage. The `Entity` builder calls into it; you can also use it directly when you need fine-grained control over the entity lifecycle: ```js import { EntityComponentDataset } from "@woosh/meep-engine/src/engine/ecs/EntityComponentDataset.js"; const ecd = new EntityComponentDataset(); const id = ecd.createEntity(); // allocates an ID (reusing freed slots) // ... attach components (see Components) ... ecd.removeEntity(id); // removes all components and frees the ID ``` Entity-level dataset methods: | Method | Description | | --- | --- | | `createEntity()` | Allocates a new ID (reuses freed slots) | | `entityExists(id)` | Tests whether an ID is live | | `getEntityGeneration(id)` | Returns the generation counter for a live entity | | `removeEntity(id)` | Removes all components, fires lifecycle events, frees the ID | | `getEntityCount()` | Current live entity count | Attaching and reading components on a dataset is covered in [Components](https://meep.company-named.com/docs/ecs/components/). ## EntityReference - generation-safe handles `EntityReference` stores an entity ID plus the generation counter it had when bound. Because IDs are recycled, a raw integer ID is unsafe to hold onto: after the original entity is removed, the same ID may belong to a different entity. An `EntityReference` whose generation no longer matches the dataset's is treated as invalid, so you can always tell whether you still hold the entity you think you do. ```js import { EntityReference } from "@woosh/meep-engine/src/engine/ecs/EntityReference.js"; const ref = EntityReference.bind(ecd, entityId); if (ref.verify(ecd)) { const t = ecd.getComponent(ref.id, Transform64); } ref.destroy(ecd); // removes the entity if still valid; no-op otherwise ``` | Member | Description | | --- | --- | | `id` | Entity ID (`-1` when unset) | | `generation` | Generation counter at bind time | | `bind(ecd, entity)` | Sets `id` and reads the current generation | | `verify(ecd)` | `true` if the entity still exists and the generation matches | | `destroy(ecd)` | Removes the entity if valid; returns `false` if invalid | | `equals(other)` | Compares both `id` and `generation` | | `EntityReference.NULL` | A frozen invalid reference (`id = -1`, `generation = -1`) | Every `Entity` builder holds an `EntityReference` in its `reference` property - set on `build()`, cleared on `destroy()`. For persisting references across save and load, see [Saving & loading](https://meep.company-named.com/docs/platform/persistence/). ## Where to go next - [Components](https://meep.company-named.com/docs/ecs/components/) - defining component types and attaching them. - [Systems & scheduling](https://meep.company-named.com/docs/ecs/systems/) - how systems read and write components each frame. - [Queries](https://meep.company-named.com/docs/ecs/queries/) - `traverseEntities`, `traverseComponents`, and cached iteration. --- # Components Section: ECS Source: https://meep.company-named.com/docs/ecs/components/ Description: How components are defined as plain classes, registered with a dataset, attached to and read from entities, and observed as they are added and removed. Components are the data half of the ECS: plain classes that hold state and nothing else. An [entity](https://meep.company-named.com/docs/ecs/entities/) is just an ID; everything you can know about it is the set of components attached to it. Logic that acts on that data lives in [systems](https://meep.company-named.com/docs/ecs/systems/). ## Defining a component A component is a plain JavaScript class. The only requirement is a static `typeName` string, which the dataset uses for name-based lookup and serialisation: ```js export class Velocity { static typeName = "Velocity" x = 0 y = 0 z = 0 } ``` Components have no built-in lifecycle hooks and no methods that reference the entity they belong to. Keep behaviour out of them - it belongs in systems. ## One component per type per entity A dataset enforces one rule: each entity can hold **at most one instance of any given component type**. Adding a second instance of the same type to the same entity throws. This constraint is intentional - it makes component lookup O(1) and keeps the data layout flat. ## Registering component types A dataset only accepts components whose type it knows about. Register types before adding instances: ```js import { EntityComponentDataset } from "@woosh/meep-engine/src/engine/ecs/EntityComponentDataset.js"; const ecd = new EntityComponentDataset(); ecd.registerComponentType(Transform64); ecd.registerComponentType(Velocity); ``` In practice you rarely register by hand: `EntityManager` calls `registerManyComponentTypes` automatically from the component lists each system declares in its `dependencies` and `components_used`. ## Attaching and reading components Once the type is registered, attach, read, and remove components through the dataset: ```js const id = ecd.createEntity(); ecd.addComponentToEntity(id, new Transform64()); ecd.addComponentToEntity(id, new Velocity()); const t = ecd.getComponent(id, Transform64); // the instance, or undefined ecd.removeComponentFromEntity(id, Velocity); ``` | Method | Description | | --- | --- | | `addComponentToEntity(id, instance)` | Attaches a component; its type must be registered | | `getComponent(id, klass)` | Returns the instance, or `undefined` | | `getComponentSafe(id, klass)` | Same, but throws on missing | | `hasComponent(id, klass)` | Boolean presence check | | `removeComponentFromEntity(id, klass)` | Detaches a component | The [`Entity` builder](https://meep.company-named.com/docs/ecs/entities/) wraps these same calls with a chainable API when you're building an entity up rather than poking at a live one. ## Observing components An `EntityObserver` fires a callback when an entity first acquires a complete tuple of specified components, and again when that tuple breaks. Systems use this internally; you can use it directly too: ```js import { EntityObserver } from "@woosh/meep-engine/src/engine/ecs/EntityObserver.js"; const observer = new EntityObserver( [Transform64, Velocity], // watch for this tuple (transform, velocity, entity) => { /* linked */ }, (transform, velocity, entity) => { /* unlinked */ } ); ecd.addObserver(observer, true); // true = fire immediately for existing matches // ... ecd.removeObserver(observer, true); // true = fire broken-callbacks on removal ``` For per-entity signals, the dataset also dispatches string-named events on individual entities. The built-in names are in `EventType`: ```js import { EventType } from "@woosh/meep-engine/src/engine/ecs/EventType.js"; ecd.addEntityEventListener(entityId, EventType.ComponentAdded, (event) => { console.log("added", event.klass.typeName, event.instance); }); ``` `EventType.ComponentAdded`, `EventType.ComponentRemoved`, and `EventType.EntityRemoved` are the three built-in events. ## Where to go next - [Entities](https://meep.company-named.com/docs/ecs/entities/) - building and destroying the entities components attach to. - [Queries](https://meep.company-named.com/docs/ecs/queries/) - iterating entities by their component makeup. - [Saving & loading](https://meep.company-named.com/docs/platform/persistence/) - per-component serialization adapters and transient marking. --- # Systems & scheduling Section: ECS Source: https://meep.company-named.com/docs/ecs/systems/ Description: How to write a System, declare component dependencies, use link/unlink for reactive per-entity setup, and how execution order is derived from access declarations. A `System` is a class you extend. It declares which components it cares about and implements any combination of four methods: `startup`, `shutdown`, `link`/`unlink` for reactive per-entity logic, and `update`/`fixedUpdate` for time-step logic. ## Extending System ```js import { System } from "@woosh/meep-engine/src/engine/ecs/System.js"; import { ResourceAccessKind } from "@woosh/meep-engine/src/core/model/ResourceAccessKind.js"; import { ResourceAccessSpecification } from "@woosh/meep-engine/src/core/model/ResourceAccessSpecification.js"; class MovementSystem extends System { // Entities with BOTH Transform64 and Velocity trigger link/unlink. dependencies = [Transform64, Velocity]; // Optional: declare how this system accesses each component type. // The scheduler uses this to derive execution order. components_used = [ ResourceAccessSpecification.from(Transform64, ResourceAccessKind.Write), ResourceAccessSpecification.from(Velocity, ResourceAccessKind.Read), ]; update(timeDelta) { const ecd = this.entityManager.dataset; ecd.traverseEntities( [Transform64, Velocity], (transform, velocity, entity) => { transform.setTranslation( transform.translation_x + velocity.x * timeDelta, transform.translation_y + velocity.y * timeDelta, transform.translation_z + velocity.z * timeDelta, ); // a Transform64 carries no signals; the writer announces the move t64_announce_change(ecd, entity); } ); } } ``` ## dependencies, link, and unlink `dependencies` is an array of component classes. When an entity acquires all of them, `link` is called with the component instances followed by the entity ID. When any of them is removed (or the entity is destroyed), `unlink` is called with the same arguments. ```js class FallDamageSystem extends System { dependencies = [Health, RigidBody]; #listeners = []; // per-entity storage link(health, rigidBody, entity) { const onContact = () => { health.value -= 10; }; const ecd = this.entityManager.dataset; ecd.addEntityEventListener(entity, PhysicsEvents.ContactBegin, onContact); this.#listeners[entity] = onContact; } unlink(health, rigidBody, entity) { const listener = this.#listeners[entity]; const ecd = this.entityManager.dataset; ecd.removeEntityEventListener(entity, PhysicsEvents.ContactBegin, listener); delete this.#listeners[entity]; } } ``` `link` and `unlink` are the right place to subscribe and unsubscribe from component-level signals, attach physics callbacks, start coroutines, and so on. They are never called during `update` - they fire when the component tuple becomes complete or breaks. ## update and fixedUpdate Override `update(timeDelta)` for frame-rate logic (rendering, camera, interpolation). Override `fixedUpdate(timeDelta)` for simulation logic that must be deterministic. The `EntityManager` drives both: - `update` is called once per `em.update(dt)` call with the real elapsed delta. - `fixedUpdate` is called zero or more times per `em.update(dt)` call, each time with the fixed step size (`em.fixedUpdateStepSize`, default 25 ms / 40 Hz). Leftover time accumulates and pays off in a future frame. Every system's `fixedUpdate` for a given step runs before any system's `update` for the cycle, so a tick is a clean simulate-then-render split and every system sees the same `em.fixedStepTick`. If a system overrides neither, `EntityManager` skips it in the hot path entirely - the check is a fast function identity compare against a shared no-op. ## startup and shutdown `startup(entityManager)` and `shutdown(entityManager)` are `async` methods called by `EntityManager` during `em.startup()` / `em.shutdown()` / `em.addSystem()`. They receive the `EntityManager` instance. `startup` is a good place to fetch assets, create worker threads, or obtain handles to other systems via `entityManager.getSystem(SomeSystemClass)`. ## Registering a system ```js import { EntityManager } from "@woosh/meep-engine/src/engine/ecs/EntityManager.js"; const em = new EntityManager(); em.addSystem(new MovementSystem()); em.addSystem(new FallDamageSystem()); em.attachDataset(ecd); // EntityComponentDataset em.startup(); // starts all systems in parallel // game loop: em.update(0.016); // drive both update and fixedUpdate ``` `addSystem` returns a `Promise` that resolves once the system's `startup` completes. If the entity manager is already running, the system starts immediately; otherwise it starts when `em.startup()` is called. `em.simulate(dt)` is a deprecated alias of `em.update(dt)`; write `update`. ## How execution order is derived You do not set an execution order manually. `EntityManager` derives it from each system's `components_used` declarations, and re-derives it at the top of the next `em.update(dt)` after the set of registered systems changes. A system that writes or creates a component runs before other systems that read it in the same pass (`fixedUpdate` or `update`). The scheduler builds those dependency edges and chooses a topological order. A write in one pass and a read in the other add no edge: every fixed step already runs before the frame's update pass. A system implementing both methods participates in both passes. When dependencies leave a choice, the scheduler uses its access-based score, then registration order. Cycles have no order that satisfies every edge. The scheduler breaks ties within a cycle by those same rules while preserving dependencies entering or leaving it; a downstream reader does not jump ahead of the cycle that produces its data. `ResourceAccessKind` values that affect scheduling: | Kind | Bit | Meaning | | --- | --- | --- | | `Read` | `1` | Reads component data, does not write | | `Write` | `2` | Mutates component data | | `Create` | `4` | Creates new component instances | `Create` carries the highest scheduling weight and `Write` medium weight when choosing between otherwise eligible systems. Both count as writers for dependency ordering; a score never overrides an acyclic writer-to-reader dependency. Declaring `components_used` is optional - the engine works without it - but declaring it accurately gives the scheduler enough information to pipeline your systems correctly. ## Accessing other systems From inside a system method, `this.entityManager` is the attached `EntityManager`. Use it to reach sibling systems: ```js async startup(entityManager) { this.physics = await entityManager.promiseSystem(PhysicsSystem); } ``` `promiseSystem(Class)` returns a `Promise` that resolves as soon as a system of that class is running, whether it is already present or added later. ## Dataset attachment hooks Two optional methods let a system respond when a dataset is swapped in or out at runtime (for scene transitions): - `handleDatasetAttached(dataset)` - called after the dataset is wired in and before any entities are linked. - `handleDatasetDetached(dataset)` - called after all entities are unlinked and before the dataset is removed. ## Systems that run off-thread `WorkerSystem` (in `src/engine/ecs/async/WorkerSystem.js`) is a `System` whose per-tick work happens on a worker thread over a `SharedArrayBuffer`, while its hot path on the main thread stays **synchronous** - no `async fixedUpdate`, no promise that resolves a microtask too late to be useful. Each fixed tick `T` the system does exactly two things: 1. **join** step `T - 1` - a load and an `apply` call, never a wait; 2. **dispatch** step `T` - `collect` writes the command words, one `Atomics.store` publishes the request. Between dispatch and the next join the worker owns the shared state and the main thread must not touch it. What makes that safe for the simulation is a **fixed-step gate**: on `startup` the system registers itself with the entity manager, and the fixed loop refuses to advance into tick `T + 1` until step `T` has landed. So every system's `fixedUpdate` runs with the worker idle, and exactly one step is ever in flight. A gate changes *when* a step runs in wall-clock terms, never *what* it computes - determinism is unaffected. When a result isn't ready the gate spins for `join_spin_budget_ms` (0.25 ms by default) and then gives up for this cycle: `update` breaks out of the catch-up loop with the unconsumed time still in the accumulator, so the step runs on a later call rather than being skipped. Subclasses implement four hooks: | Hook | When | Purpose | | --- | --- | --- | | `createWorker()` | once, during `startup` | Spawn the worker. Kept as a hook so the `import.meta.url` spawn expression stays out of modules a test imports | | `collect(command, tick, dt)` | on tick, worker idle | Prepare shared state, write the `Float64` command words. Return `false` to skip dispatching this tick | | `apply(tick)` | on tick, worker idle | Integrate a completed step. Nothing to do when results live entirely in shared memory | | `buildBootPayload()` / `handleWorkerMessage(data)` | boot / cold plane | Optional one-off setup payload and rare out-of-band messages | The worker half is `SystemWorkerHost`, which owns the protocol and calls into a plain "core" object that does the work: ```js // my.worker.js import { SystemWorkerHost } from "@woosh/meep-engine/src/engine/ecs/async/SystemWorkerHost.js"; SystemWorkerHost.serve({ boot(payload) { /* one-off setup */ }, step(tick, command) { /* hot plane: runs once per dispatched tick */ }, }); ``` Practical notes: - **The page must be cross-origin isolated.** The bridge allocates a real `SharedArrayBuffer` and refuses to degrade to a private `ArrayBuffer` - serve with `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp`, or construction throws with that message. - **A hung worker fails the bridge, it doesn't freeze the game.** A step outstanding past `step_deadline_ms` (2 s) is declared dead; the boot handshake times out at 15 s; `shutdown` waits 1 s for in-flight work before terminating. Sustained slowness is handled by deferring steps, not by failing. - **Cold-plane messages are expensive.** A worker parked in `Atomics.wait` isn't running its event loop, so `postToWorker` costs a scheduling round trip. Keep it for structural changes; use the command region for per-tick data. - `SystemWorkerLoopback` runs a real host, core, and shared buffer in-process, so a test can drive message delivery and step execution in any order without a worker thread. Custom gates use the same contract directly - `entityManager.registerFixedStepGate(gate)` with a `gate.may_advance(next_tick) => boolean`, and `unregisterFixedStepGate(gate)` to remove it. A gate must only ever answer `false` transiently; one that never opens freezes the simulation. ## Where to go next - [Queries](https://meep.company-named.com/docs/ecs/queries/) - `traverseEntities` and friends. - [Hierarchy & attachment](https://meep.company-named.com/docs/ecs/hierarchy/) - parent-child transforms. - [Scenes](https://meep.company-named.com/docs/ecs/scenes/) - multiple datasets and scene transitions. --- # Queries Section: ECS Source: https://meep.company-named.com/docs/ecs/queries/ Description: How to iterate over entities that match a component tuple using traverseEntities and traverseComponents, and what the performance characteristics of each are. `EntityComponentDataset` provides three traversal methods for querying entities by their components. All three avoid heap allocation on the hot path by reusing scratch arrays internally. ## traverseEntities - match a component tuple `traverseEntities` visits every entity that carries all of the specified component types. The visitor receives one instance per listed type, followed by the entity ID as the final argument: ```js ecd.traverseEntities( [Transform64, Velocity], (transform, velocity, entity) => { transform.setTranslation( transform.translation_x + velocity.x * dt, transform.translation_y + velocity.y * dt, transform.translation_z + velocity.z * dt, ); // a Transform64 carries no signals; the writer announces the move t64_announce_change(ecd, entity); } ); ``` Return `false` from the visitor to stop iteration early. The optional third argument is a `thisArg` for the callback: ```js ecd.traverseEntities([Health], function(health, entity) { if (health.value <= 0) this.scheduleRemoval(entity); // return false to stop after the first match }, this); ``` If any of the listed component types is not registered in the dataset, `traverseEntities` returns immediately with no visits - it cannot match any entity if a required type is absent. The inner loop is a tight bit-test over a packed occupancy table. For N entities and K component types, the occupancy check is O(K) per entity; there are no per-frame allocations. ## traverseComponents - iterate one component type When you only need instances of a single component type, `traverseComponents` is more direct: ```js ecd.traverseComponents(Velocity, (velocity, entity) => { velocity.x *= 0.98; // dampen all velocities }); ``` Return `false` to stop early. Because it iterates the backing store for one component index directly, it pays no bit-mask overhead - it just walks the sparse array. ## traverseEntitiesExact - match a tuple with no extras `traverseEntitiesExact` visits only entities that have **exactly** the listed component types and nothing else. It is slower than `traverseEntities` (it counts all components on each entity and rejects any that have more), so reserve it for cases where the extra-component check matters. ```js ecd.traverseEntitiesExact([Transform64, Tag], (transform, tag, entity) => { // only entities with exactly Transform64 and Tag - not Transform64 + Tag + Collider }); ``` ## traverseEntityIndices - raw entity IDs When you only need the entity IDs, not their components: ```js ecd.traverseEntityIndices((entity) => { console.log(entity); }); ``` ## Iterating all entities with for…of `EntityComponentDataset` is `Iterable`, so you can also use a `for...of` loop: ```js for (const entity of ecd) { const t = ecd.getComponent(entity, Transform64); if (t !== undefined) { /* ... */ } } ``` ## Singleton components - getAnyComponent Some components are expected to have exactly one instance in the dataset (camera, audio listener, settings). `getAnyComponent` returns the first one it finds without allocating: ```js const { entity, component } = ecd.getAnyComponent(Camera); if (component !== null) { // component is the Camera instance; entity is its owner ID } ``` ## Observer-based queries For reactive queries that must fire when the matching set changes, use `EntityObserver` (see [Components](https://meep.company-named.com/docs/ecs/components/)). `EntityObserver` is O(1) per change event - it fires the callback at the moment the tuple completes or breaks, not by scanning the whole dataset each frame. Systems use observers internally to drive `link` and `unlink`. Prefer observers for setup/teardown logic and `traverseEntities` for per-frame iteration over the matched set. ## Performance notes - `traverseEntities` and `traverseComponents` reuse a shared scratch array between calls. They are safe to call from within a traversal of a *different* component set, but not to nest on the same scratch buffer. In practice, calling `traverseEntities` inside a visitor passed to `traverseEntities` can corrupt arguments. Use `traverseComponents` or a manual index loop for nested iteration. - `getComponent(id, klass)` is a hash-map lookup (Map.get) and is O(1). - `hasComponent(id, klass)` delegates to `getComponent` and is also O(1). ## Where to go next - [Systems & scheduling](https://meep.company-named.com/docs/ecs/systems/) - how systems call these methods each frame. - [Components](https://meep.company-named.com/docs/ecs/components/) - `EntityObserver` for reactive queries. --- # Hierarchy & attachment Section: ECS Source: https://meep.company-named.com/docs/ecs/hierarchy/ Description: The two hierarchies meep keeps - ParentEntity for lifetime, TransformAttachment for space - how their systems index and compose them, and how to find a named node on a loaded model. Meep keeps **two** hierarchies, and they are deliberately separate. `ParentEntity` says what an entity's lifetime is tied to; `TransformAttachment` says what its transform is relative to. Both are components on the child, each naming its parent by entity id, and they are free to name **different** entities - which is how a floating health bar can be positioned against a unit's head while being owned by the UI layer. Neither direction is stored on the parent. Each hierarchy's system keeps the reverse index itself, so "who are my children" is a lookup rather than a sweep of the whole dataset. ```pintora componentDiagram package "Child entity" { [ParentEntity] [TransformAttachment] } [ParentEntity] --> [Entity whose lifetime owns the child] [TransformAttachment] --> [Entity the child transform composes against] ``` ## The two components | | `ParentEntity` | `TransformAttachment` | | --- | --- | --- | | Relation | Lifetime | Spatial | | Field naming the parent | `entity` | `parent` | | Extra state | none | `transform` (the local pose), `flags` | | Owning system | `ParentEntitySystem` | `TransformAttachmentSystem` | | When the parent is destroyed | the child is destroyed | the component is removed; the child survives as a root | | Serialization | Opted out (`serializable = false`) - entity IDs are transient | Has `toJSON` / `fromJSON`; no binary adapter is registered by default | **Both parent fields are immutable while the component is attached.** Writing `ParentEntity.entity` or `TransformAttachment.parent` in place does not reparent anything - each system resolves the parent once, when the component links - and it also desynchronises the system's parent-to-children index, which is built on link and unlink being the only transitions those fields ever undergo. To move an entity, remove the component and add it back. ## Spatial hierarchy: TransformAttachment `TransformAttachment` holds a local transform and the entity that transform is relative to. `TransformAttachmentSystem` composes the child's world `Transform64` as parent world times local: ```js // world transform = parent_transform × attachment.transform transform.multiplyTransforms(parent_transform, attachment.transform); ``` Register the system or nothing composes: ```js import { TransformAttachmentSystem } from "@woosh/meep-engine/src/engine/ecs/transform-attachment/TransformAttachmentSystem.js"; em.addSystem(new TransformAttachmentSystem()); // constructor takes no arguments ``` Its `dependencies` are `[TransformAttachment, Transform64]`, so it links any entity carrying both. On link it listens for two entity events - `TRANSFORM64_EVENT_CHANGE` on the parent, `TRANSFORM_ATTACHMENT_EVENT_CHANGE` on the child - so motion propagates reactively and a bound child costs nothing per frame. Neither component announces itself, so a hand-written parent move ends with `t64_announce_change(ecd, parent)` and a hand-written local offset ends with `ecd.sendEvent(child, TRANSFORM_ATTACHMENT_EVENT_CHANGE)`. Building the pair by hand: ```js import { TransformAttachment } from "@woosh/meep-engine/src/engine/ecs/transform-attachment/TransformAttachment.js"; import { ParentEntity } from "@woosh/meep-engine/src/engine/ecs/parent/ParentEntity.js"; import { Transform64 } from "@woosh/meep-engine/src/engine/ecs/transform/Transform64.js"; const attachment = new TransformAttachment(); attachment.parent = parentEntityId; attachment.transform.setTranslation(0, 1, 0); // 1 unit above the parent new Entity() .add(new Transform64()) .add(attachment) .add(ParentEntity.from(parentEntityId)) // also die with the parent .build(ecd); ``` `TransformAttachmentFlags.Immediate` is set by default and makes the system compose once at link time, so the child's world transform is correct from frame one. Clear it (`attachment.immediate = false`) when you know the child's `Transform64` is already right and want to skip the work. A child whose parent has no `Transform64` yet - because it was built first, or because a model has not finished loading - is **queued** rather than dropped. The system retries up to 32 queued children per `update`, and finalises each one the moment its parent becomes bindable. ### Two hazards worth knowing **Non-uniform parent scale is lossy.** The world transform is stored decomposed as translation, rotation and scale. A rotated child of a non-uniformly scaled parent composes to a non-orthogonal basis that TRS cannot hold, and the shear is silently best-fitted away - a mesh under such a parent draws wrong. Nothing in the component fixes this; either scale the parent uniformly, or bake the scale into the geometry. **Deep chains drift.** Repeated composition accumulates roughly 1e-6 of scale error over 64 rotation-only levels. Harmless in itself, but the composed child is rewritten and announced on every rotation, so anything listening below it wakes for a scale that did not really change. ## Lifetime hierarchy: ParentEntity `ParentEntity` names the entity whose destruction destroys this one. `ParentEntitySystem` owns the cascade and the reverse index: ```js import { ParentEntitySystem } from "@woosh/meep-engine/src/engine/ecs/parent/ParentEntitySystem.js"; em.addSystem(new ParentEntitySystem()); ``` Beyond the cascade it exposes a query surface over the hierarchy: | Method | Result | | --- | --- | | `findParentEntity(entity)` | The parent, or `-1` when the entity has no `ParentEntity` | | `findRoot(entity)` | The top of the chain; `entity` itself when it has no parent. Throws on a cycle | | `isAncestorOf(child, ancestor)` | `true` if `ancestor` is on the chain above `child`. An entity is its own ancestor. Throws on a cycle | | `findChildrenOf(result, offset, entity)` | Writes the direct children into `result` from `offset`, returns how many | | `countChildrenOf(entity)` | Direct child count - sizes a buffer for `findChildrenOf` without filling one | | `traverse(root, callback, thisArg?)` | Visits `root` and everything below it, parents before children | ```js const parents = em.getSystem(ParentEntitySystem); const children = []; const count = parents.findChildrenOf(children, 0, unitEntity); for (let i = 0; i < count; i++) { ecd.removeEntity(children[i]); } ``` `TransformAttachmentSystem` carries the same two lookup methods, `findChildrenOf` and `countChildrenOf`, over its own hierarchy. ### What the reverse index guarantees Both systems keep their back-links in an `EntityChildIndex` (`src/engine/ecs/hierarchy/EntityChildIndex.js`). It is not a component, and the difference matters: - **It is derived, never authored.** There is no child-list component and nothing user-writable. The owning system is the only writer, the index is never serialized, and it is rebuilt from the child-side components on load. A component would have been a second copy of an edge that already exists, with nothing keeping the two ends agreeing. - **Children come back ascending by entity id**, not in link order. Link order is only as deterministic as entity creation order, and consumers feed traversals whose output order is part of their contract. - **Callers get a snapshot.** `findChildrenOf` copies out, because the usual thing to do with a child list is destroy or detach what it names - and that would move a live list under the loop walking it. `traverse` snapshots each node's children before visiting them for the same reason, so the callback may destroy subtrees it has not reached yet. - **A key may name an entity that no longer exists**, for as long as it takes a removal cascade to reach the children that entity owned. On the spatial side, a **queued** child is in the index too, so a non-zero child count does not mean those children are composing yet. `ParentEntitySystem.traverse` reports a cycle and skips the offending edge rather than throwing, so a caller asking for a subtree still gets the acyclic part of it. ## When a parent dies The two hierarchies answer this differently, and the difference is the reason they are separate components. A **lifetime** parent takes its children with it: `ParentEntitySystem` destroys every entity whose `ParentEntity` names it, recursively. A **spatial** parent does not. When the entity named by `TransformAttachment.parent` is destroyed there is nothing left to compose against, so the system **removes the `TransformAttachment` component**. The child keeps the last world transform it had and becomes a root. That is an observable state change rather than a child silently freezing while holding a dead parent's `Transform64` alive. If a child should die with its spatial parent - the ordinary case - give it a `ParentEntity` naming the same entity. The two components together are what make that happen; neither does it alone. ## EntityNode - the ergonomic wrapper `EntityNode` is a scene-graph helper that manages both components for you: building a child node adds a `TransformAttachment` *and* a `ParentEntity` pointing at its parent, so a node tree behaves the way a scene graph is expected to. It wraps an `Entity` and exposes a `transform` property for the local pose. ```js import { EntityNode } from "@woosh/meep-engine/src/engine/ecs/parent/EntityNode.js"; import { Transform64 } from "@woosh/meep-engine/src/engine/ecs/transform/Transform64.js"; // Wrap the car's visual entity (already has a Transform64) const carNode = new EntityNode(carVisualEntity); // Attach a headlight as a child node const headlightNode = EntityNode.fromComponents(new Transform64(), headlightComponent); headlightNode.transform.setTranslation(0.6, 0.4, 1.5); carNode.addChild(headlightNode); // Build the whole tree into the dataset at once carNode.build(ecd); ``` `EntityNode.fromComponents(...components)` is a factory that creates a node and adds the supplied components to its underlying entity. A node that has children must carry a `Transform64` - `build` asserts it, because the attachment hierarchy has nothing to compose against otherwise. `EntityNode` key members: | Member | Description | | --- | --- | | `transform` | Local `Transform64`. After writing it, call `transform_changed()` - the node pushes the pose into the components and announces it; nothing watches the buffer for you | | `entity` | The underlying `Entity` builder | | `parent` | Parent `EntityNode`, or `null` for a root | | `children` | Read-only array of child `EntityNode` instances | | `addChild(node)` | Attaches `node` as a child; builds it immediately if the parent is already built | | `removeChild(node)` | Detaches a child | | `traverse(visitor)` | Depth-first visit of this node and all descendants | | `traverseChildren(visitor)` | Depth-first visit of the descendants only | | `root` | Walks up to the root of the hierarchy | | `build(ecd)` | Builds this node and all children into the dataset | | `destroy()` | Destroys all children first, then this entity | | `isBuilt` | `true` after `build()` | This pattern is used in the [raycast-vehicle example](https://meep.company-named.com/examples/raycast-vehicle/) to attach wheels and lights to the car chassis. The physics body is a separate entity; only the visual mesh rides the `EntityNode` tree. ## Finding a named node on a model There are no attachment-socket components, and no skeleton object to ask for a bone. A model is spawned into entities - `prefab_instantiate`, one entity per node of the file - and every one of them carries a `Name` and a `TransformAttachment` pointing at its parent. **Naming a bone is naming an entity in a hierarchy.** ```js import { transform_attachment_find_descendant_by_name } from "@woosh/meep-engine/src/engine/ecs/transform-attachment/transform_attachment_find_descendant_by_name.js"; import { transform_attachment_parent_of } from "@woosh/meep-engine/src/engine/ecs/transform-attachment/transform_attachment_parent_of.js"; const hand = transform_attachment_find_descendant_by_name(ecd, characterEntity, "hand.R"); // -1 when nothing under `characterEntity` carries that name. // That is not an error - the model may simply not have arrived yet. const up_one = transform_attachment_parent_of(ecd, hand); // -1 when `hand` is a root ``` `transform_attachment_find_descendant_by_name` searches names first and ancestry second, which is the cheaper way around: `Name` is a component the dataset already indexes, and the walk up from a candidate is the depth of the hierarchy rather than its width. The `root` entity is not itself a candidate. Anything you attach to that entity - with its own `TransformAttachment` and `ParentEntity` - now rides the bone. ### Where the node actually is this frame The entity's `Transform64` is only current for hierarchies the CPU composes. A joint driven by a skinned animation is posed on the GPU, so the entity that carries its name still holds the rest pose. Ask for the animated pose instead - this is a different lookup: it goes to `MeshSystem` for the entity's loaded model instance and finds the node by its **asset** name, rather than finding an entity in the dataset. ```js import { query_entity_node_world_pose } from "@woosh/meep-engine/src/engine/graphics3/pose/query_entity_node_world_pose.js"; import { Transform64 } from "@woosh/meep-engine/src/engine/ecs/transform/Transform64.js"; const pose = new Transform64(); if (query_entity_node_world_pose(pose, engine.entityManager, characterEntity, "hand.R")) { // pose carries both its matrix and its components } ``` This is the sanctioned way to ask where a socket, muzzle or effect anchor is. The answer is **computed, never read back from the GPU**: readback is a frame late and asynchronous, so an outcome that depended on it would depend on frame pacing, and determinism and replay would go with it. The pose is evaluated over exactly the clips the animation systems are driving, off the same clock the renderer draws from, so a socket stays on the mesh you can see. It returns `false` when there is no such node to answer about - no `MeshSystem` registered, the model has not loaded, the entity has no model, or the name is not in it. None of the four is an error, so branch on the return value rather than assuming a pose. ## Where to go next - [ECS overview](https://meep.company-named.com/docs/ecs-overview/) - `Transform64`, the pose component this page composes. - [Entities](https://meep.company-named.com/docs/ecs/entities/) - `EntityReference` for safe cross-entity handles. - [Systems & scheduling](https://meep.company-named.com/docs/ecs/systems/) - how these systems integrate into the system graph. - [Raycast-vehicle example](https://meep.company-named.com/examples/raycast-vehicle/) - a live demo using `EntityNode` for visual attachments. --- # Scenes Section: ECS Source: https://meep.company-named.com/docs/ecs/scenes/ Description: How a Scene wraps an EntityComponentDataset into an isolated world, and how SceneManager creates scenes and switches the active one. ## Scenes A **scene** is a named world that owns its own `EntityComponentDataset`, so entities in one scene are fully isolated from another. Many scenes can exist at once, but only one is *active* - attached to the `EntityManager` - at a time. Switching scenes swaps the active dataset in a single step, which is how you move between, say, a menu and a level. You rarely build scenes by hand. The engine's `SceneManager` (at `engine.sceneManager`) creates them and switches between them: ```js const sm = engine.sceneManager; sm.create("main"); // register an empty scene named "main" sm.set("main"); // make it the active scene ``` `create` returns the `Scene`, so you can populate its dataset before activating it: ```js const level = sm.create("level-1"); new Entity() .add(new Transform64()) .build(level.dataset); sm.set("level-1"); // its entities are now live ``` Once a scene is active, `engine.entityManager.dataset` is that scene's dataset - add and query entities through it as usual. ## SceneManager | Method | Description | | --- | --- | | `create(name)` | Creates an empty `Scene`, registers it, and returns it | | `set(name)` | Switches to the named scene (synchronous dataset swap) | | `getByName(name)` | Looks up a registered scene | | `exists(name)` | `true` if a scene with that name is registered | | `add(scene)` | Registers a pre-built `Scene` instance | | `remove(name)` | Unregisters a scene, deactivating it first if active | | `stackPush(name)` | Remembers the current scene, then switches | | `stackPop()` | Returns to the last `stackPush`-ed scene | | `clear()` | Detaches the current scene, leaving none active | | `current_scene` | The active `Scene`, or `null` | `set` throws if the name isn't registered, and is a no-op if that scene is already active. ### Waiting for assets to load `set` swaps datasets instantly, which is fine when everything is already in memory. When the incoming scene needs meshes or terrain tiles to load first, use `transitionToScene` - it shows a loading screen, waits for visible terrain tiles and mesh assets, renders one warm-up frame, then resolves: ```js import { transitionToScene } from "@woosh/meep-engine/src/engine/scene/transitionToScene.js"; await transitionToScene({ scene: myScene, engine, tasks: [myLoadTask] }); ``` `transitionToScene` knows nothing about any renderer: [meep's renderer](https://meep.company-named.com/docs/rendering/overview/) has no render layers to hide and no material pre-pass to trigger. What covers the load is the loading screen the call returns. ## Advanced: custom Scene subclasses `create` hands you a plain `Scene`, which is all most projects need. For a scene with its own build or teardown logic, subclass `Scene`, override the hooks you need, and register the instance with `sm.add(new MyScene())`: | Hook | When it runs | | --- | --- | | `setup(options, engine, success, failure)` | Build the world; call `success()` when done | | `handlePreActivation()` / `handlePostActivation()` | Around the dataset being attached | | `handlePreDeactivation()` / `handlePostDeactivation()` | Around the dataset being detached | | `teardown(engine, success, failure)` | Release resources | A `Scene` also exposes `name`, `dataset`, `active` (an `ObservedBoolean`), `destroyed`, `speedModifiers` (clock multipliers active with the scene), and `clear()` (empties the dataset). ## Where to go next - [ECS overview](https://meep.company-named.com/docs/ecs-overview/) - the conceptual model. - [Entities](https://meep.company-named.com/docs/ecs/entities/) - building entities and holding `EntityReference` handles. - [Saving & loading](https://meep.company-named.com/docs/platform/persistence/) - serializing a scene's dataset and marking entities transient. --- # Physics overview Section: Physics Source: https://meep.company-named.com/docs/physics/overview/ Description: Meep ships a rigid-body physics engine in the box - pure JavaScript, built for massive worlds, fully debuggable, and bit-exact across V8 runtimes. Meep comes with a rigid-body physics engine built in. Not a binding to a WebAssembly blob, not a third-party library you wire up yourself - an engine, written in the same JavaScript as the rest of Meep, that you turn on by registering two systems. ## Built in, not bolted on Most web engines don't ship physics. Babylon and PlayCanvas both tell you to bring your own - Rapier, Cannon, Ammo, Havok - and give you an integration layer at best. That means a second runtime to load, a WASM heap that lives outside your debugger, and a simulation whose source you can't step into. Meep's physics is part of the engine. A body is three components on one entity, and the simulation is two systems: ```js import { PhysicsSystem } from "@woosh/meep-engine/src/engine/physics/ecs/PhysicsSystem.js"; import { ColliderObserverSystem } from "@woosh/meep-engine/src/engine/physics/ecs/ColliderObserverSystem.js"; const physics = new PhysicsSystem(); em.addSystem(physics); // the solver em.addSystem(new ColliderObserverSystem(physics)); // attaches colliders to bodies ``` Both lines are required - `PhysicsSystem` says so in its own contract. Its dependency tuple is `(RigidBody, Transform64)`; it is `ColliderObserverSystem` that watches for `(Collider, Transform64)` and attaches each collider to a body, so a `PhysicsSystem` registered on its own leaves you with bodies that have nothing to collide against. The observer resolves the body from the collider's own entity when that entity also carries a `RigidBody`, and from its `ParentEntity` when it does not - which is how compound bodies are assembled from child collider entities. A collider that resolves to neither is an **orphan and is silently skipped**, so add the body before its colliders. From here, any entity carrying `Transform64 + RigidBody + Collider` falls under gravity, collides, and comes to rest - see [Rigid bodies](https://meep.company-named.com/docs/physics/rigid-bodies/) and [Colliders & shapes](https://meep.company-named.com/docs/physics/colliders/). ## Optimized for massive worlds The simulation cost tracks the *active* set, not the size of the world: - **Two spatial indexes** - one for static geometry, one for moving bodies. Level geometry is added once and never rebuilt; only moving bodies pay a per-frame cost. - **Solving in groups.** Bodies that are touching are solved together as a group, and separate groups are solved independently. Static and kinematic bodies anchor a group without enlarging it. - **Sleeping in bulk.** A pile that comes to rest sleeps as a unit and drops out of the active set entirely. A hundred-block stack wakes in a single step when something hits it - no frame-by-frame ripple up the stack. A scene can hold an enormous static world and thousands of resting bodies while the per-frame budget stays proportional to what's actually moving. ## Fully debuggable - it's all JavaScript Because the solver is plain JS, it lives in the same world as your gameplay code. Set a breakpoint inside the collision code. Step through a contact being resolved. Read a body's velocity in the console mid-frame. There is no opaque WASM heap and no separate runtime - the same browser DevTools you use for the rest of your page reach all the way down. In development, [thousands of runtime assertions](https://meep.company-named.com/features/) guard the physics invariants and fail loudly at the source of the problem. In production, the strip plugin removes them for native-speed runtime. ### Drawing what the solver sees Physics ships **no debug-draw API of its own**. Anything you want to see - a contact normal, a shape cast's swept volume, a broadphase box - you draw yourself through the engine's immediate-mode gizmo surface, which is renderer-neutral, plus the system that renders one frame of it: ```js import { Gizmo } from "@woosh/meep-engine/src/engine/graphics/render/gizmo/Gizmo.js"; import { DebugDrawSystem } from "@woosh/meep-engine/src/engine/graphics3/DebugDrawSystem.js"; em.addSystem(new DebugDrawSystem(engine.graphics)); // …then, from anywhere during the frame: Gizmo.color = [1, 0.2, 0.1, 1]; // RGBA, at least 4 elements Gizmo.draw_wire_sphere(hit.position, 0.1); // centre, radius Gizmo.draw_line(hit.position, contactEnd); // from, to ``` `Gizmo` is a singleton. `color` is a property, not a method, and every `draw_*` call takes the colour that is set when it runs - which is what lets one pass carry a frame's worth of differently coloured shapes. The rest of the surface is `clear()`, `draw_line`, `draw_solid_cube`, `draw_wire_cube`, `draw_solid_sphere` and `draw_wire_sphere`; positions and sizes are indexable triples, so a `Vector3` works directly. The recording is immediate-mode: **a frame's recording does not survive into the next**, and `DebugDrawSystem` clears it once the frame that consumed it has been submitted. Shapes are blended and depth-tested but never depth-writing, so they are occluded by the scene and occlude nothing, including each other; two overlapping solid shapes composite in the order they were recorded rather than by depth. `line_width` is a property of the system (default `2`), in CSS pixels, not of a draw. See [Render extensions](https://meep.company-named.com/docs/rendering/render-extensions/) for how the pass slots into the frame. ## Deterministic and bit-exact across V8 The simulation advances on a [fixed timestep](https://meep.company-named.com/docs/physics/determinism/) and uses no wall-clock, no hardware randomness, and no platform math beyond IEEE-754 doubles. Given the same inputs in the same order, it produces **the same result, bit for bit, on every V8 runtime** - Chrome, Edge, Node, Deno, Electron. That's the foundation for: - **Lockstep multiplayer** - replicate inputs, not state. Every client simulates the same world. - **Replays** - record the input stream, replay the exact match. - **Server reconciliation** - the server re-runs the client's steps and gets the identical answer. - **Reproducible tests** - a physics regression is a diff, not a flake. See [Determinism](https://meep.company-named.com/docs/physics/determinism/) for the guarantees and the rules that preserve them. ## Where to go next - [Rigid bodies](https://meep.company-named.com/docs/physics/rigid-bodies/) - `RigidBody`, body kinds, mass, forces, sleeping. - [Colliders & shapes](https://meep.company-named.com/docs/physics/colliders/) - shapes, materials, layers, sensors, contact events. - [Spatial queries](https://meep.company-named.com/docs/physics/queries/) - raycasts, shape casts, and overlap tests against the live world. - [Joints](https://meep.company-named.com/docs/physics/joints/) - connect bodies with ball-sockets, hinges, sliders, and welds. - [Constraints](https://meep.company-named.com/docs/physics/constraints/) - per-DOF limits, springs, and motors on a joint. - [Determinism](https://meep.company-named.com/docs/physics/determinism/) - the fixed-step contract and what bit-exact buys you. - [Raining rigid bodies](https://meep.company-named.com/examples/physics-rain/) and [Jointed chains](https://meep.company-named.com/examples/chains/) - live demos. - The source: `src/engine/physics/ecs/` - start with `PhysicsSystem.js`. --- # Rigid bodies Section: Physics Source: https://meep.company-named.com/docs/physics/rigid-bodies/ Description: The RigidBody component - body kinds, mass and inertia, forces and impulses, damping, and sleeping. A rigid body is an entity carrying three components: a `Transform64` (its pose), a `RigidBody` (its dynamic state), and a `Collider` (its shape - covered in [Colliders & shapes](https://meep.company-named.com/docs/physics/colliders/)). The split matters. **Pose lives on the `Transform64`** - position and rotation - and the `PhysicsSystem` writes it back every step, so the renderer reads the result for free. **`RigidBody` owns everything that isn't pose:** velocity, mass, inertia, damping, gravity scale, and collision filtering. ```js import { RigidBody } from "@woosh/meep-engine/src/engine/physics/ecs/RigidBody.js"; import { BodyKind } from "@woosh/meep-engine/src/engine/physics/ecs/BodyKind.js"; const body = new RigidBody(); body.kind = BodyKind.Dynamic; body.mass = 2; new Entity() .add(new Transform64()) .add(body) .add(collider) // see Colliders & shapes .build(ecd); ``` ## Body kinds `BodyKind` decides how a body participates in the simulation. | Kind | Moves? | Use for | | --- | --- | --- | | `Static` | Never. Infinite mass; stored as immovable level geometry. | Level geometry, ground, walls. | | `Dynamic` | Integrated under gravity, forces, and contact impulses. | Gameplay objects - the common case. | | `KinematicVelocity` | Driven by its velocity; pushes dynamic bodies but isn't pushed back. | Moving platforms, elevators. | | `KinematicPosition` | `setTargetPose` derives the velocity needed to reach a target on the next fixed step. | Animation- or code-driven movers. | ### Moving a position-driven body Use `physics.setTargetPose(body, position, rotation)` to move a `KinematicPosition` body continuously. Position and rotation are indexed arrays, respectively `[x, y, z]` and `[x, y, z, w]`. The next fixed step derives linear and angular velocities from its `dt`, pushes and carries dynamic bodies along that motion, and finishes at the target pose. ```js physics.setTargetPose(platformBody, [5, 2, 0], [0, 0, 0, 1]); ``` Send a target every tick, including when standing still: the derived velocities remain on the body, so without another target it keeps moving at that rate. `setTargetPose` accepts only `KinematicPosition` bodies. Use `setPose` for teleports; direct `Transform64` edits also do not derive motion velocity. The first-person controller uses target poses for movement and `setPose` for warps. ## Mass and inertia `mass` is in kilograms and must be positive for dynamic bodies. Static and kinematic bodies behave as if mass were infinite regardless. Rotation is a separate matter. A body's `inverseInertiaLocal` defaults to `(0, 0, 0)`, which **locks rotation** - the body slides but never tumbles. This is deliberate: a missing inertia tensor gives you a locked body, never a `NaN` tumble. To let a body spin, set the inverse of its principal moments of inertia: ```js import { v3_set } from "@woosh/meep-engine/src/core/geom/vec3/v3_set.js"; // Solid box, half-extents (hx, hy, hz): const k = body.mass / 3; v3_set(body.inverseInertiaLocal, 0, 1 / (k * (hy*hy + hz*hz)), 1 / (k * (hx*hx + hz*hz)), 1 / (k * (hx*hx + hy*hy)), ); ``` A zero component locks that axis - handy for keeping a character capsule upright (`v3_set(body.inverseInertiaLocal, 0, 0, y, 0)`). `inverseInertiaLocal`, `linearVelocity`, `angularVelocity`, `accumulatedForce` and `accumulatedTorque` are three-element `Float64Array`s. Read them as `[0]`, `[1]`, `[2]` for x, y, z. Use `v3_set(vector, 0, x, y, z)` to write all three without allocating; these fields have no `.x` accessors or `Vector3.set(x, y, z)` method. ## Velocity, damping, and gravity - `linearVelocity` / `angularVelocity` - world-space, m/s and rad/s. Read freely; set through the system (below) so sleeping bodies wake. - `linearDamping` / `angularDamping` - per-second velocity decay. A little (`0.02`–`0.05`) helps piles settle instead of jittering. - `gravityScale` - multiplier on world gravity. `1` is normal, `0` floats, negative inverts. World gravity defaults to `(0, -9.81, 0)`; change it with `physics.setGravity([x, y, z])`. ## Forces and impulses Don't write the force accumulators directly - go through the `PhysicsSystem`, which also wakes a sleeping body for you: ```js physics.applyForce(body, [0, 40, 0]); // continuous, this step physics.applyImpulse(body, [5, 0, 0]); // instantaneous Δmomentum physics.applyImpulseAt(body, transform, impulse, point); // off-centre → adds spin physics.applyTorque(body, [0, 2, 0]); physics.setLinearVelocity(body, [0, 0, 0]); physics.setAngularVelocity(body, [0, 3, 0]); // replace the spin ``` Forces and torques accumulate between fixed steps and are consumed by the integrator each tick. Forces, impulses, torques, velocities and world points are read by index as `[x, y, z]`. `setPose(body, position, rotation)` takes an indexed position and quaternion `[x, y, z, w]`. Arrays, typed arrays, and the engine's `Vector3` / `Quaternion` classes all work; plain `{x, y, z}` objects do not. Reuse scratch arrays or a `Transform64`'s `translation` and `rotation` views in hot paths. `setPose` updates the live transform matrix, announces `TRANSFORM64_EVENT_CHANGE` and marks an interpolated body to snap instead of blending across the teleport. It then sends `TRANSFORM64_EVENT_PLACED`; attachments forward that placement intent to their children so motion consumers can reset their history. ## Sleeping A body that stays below a small velocity threshold for `sleepTimeThreshold` seconds (default `0.5`) leaves the active set and stops costing solver time. Connected piles sleep together - a whole stack drops out and wakes as one. - `physics.wake(body)` / `physics.sleep(body)` - force the state. - `RigidBodyFlags.DisableSleep` - keep a body always awake (e.g. one you drive externally). ```js import { RigidBodyFlags } from "@woosh/meep-engine/src/engine/physics/ecs/RigidBodyFlags.js"; body.setFlag(RigidBodyFlags.DisableSleep); ``` ## Where to go next - [Colliders & shapes](https://meep.company-named.com/docs/physics/colliders/) - give the body a shape and a surface. - [Determinism](https://meep.company-named.com/docs/physics/determinism/) - why the same forces produce the same result every time. --- # Colliders & shapes Section: Physics Source: https://meep.company-named.com/docs/physics/colliders/ Description: The Collider component - collision shapes, surface materials, layer/mask filtering, sensors, contact events, and raycasts. A `Collider` pairs an immutable **shape** with a **surface material** (friction, restitution). Its world pose comes from the entity's `Transform64`. ```js import { Collider } from "@woosh/meep-engine/src/engine/physics/ecs/Collider.js"; import { BoxShape3D } from "@woosh/meep-engine/src/core/geom/3d/shape/BoxShape3D.js"; const collider = new Collider(); collider.shape = BoxShape3D.from_size(2, 1, 2); collider.friction = 0.6; collider.restitution = 0.2; ``` Add it to the same entity as the body. The **`ColliderObserverSystem`** is what attaches a collider to its body, so register it alongside the `PhysicsSystem` - and register the `PhysicsSystem` first, so the body's slot exists before the collider attaches to it. ## Shapes Shapes are shared, immutable values - build one and reuse it across every collider of that size. | Shape | Construct | Notes | | --- | --- | --- | | Sphere | `SphereShape3D.from(radius)` | The simplest and fastest shape. | | Box | `BoxShape3D.from_size(w, h, d)` | Also `BoxShape3D.from(hx, hy, hz)` for half-extents. | | Capsule | `CapsuleShape3D.from(radius, height)` | Y-aligned; `height` is the cylinder section only (the rounded caps add `radius` at each end). | | Cylinder | `CylinderShape3D.from(radius, height)` | Y-aligned; `height` is the full height. | | Heightmap | `HeightMapShape3D.from(sampler, sizeX, sizeY, sizeZ, orientation, tessellation)` | A terrain surface read from a `Sampler2D` of heights, spanning `sizeX × sizeZ` with heights up to `sizeY`. It's a non-convex surface - put it on a `Static` body for ground. `tessellation` (default `1`) splits each sampler cell into `tessellation × tessellation` collision sub-cells, so a coarse sampler drawn as a finely tessellated mesh can still collide against something close to the rendered surface. | Sphere, box, and capsule pairs are handled by fast, exact routines written for those specific shapes - quicker and more robust than the general-purpose path on the common, smooth cases. > **Size lives on the shape, not the `Transform64`.** The simulation reads translation and rotation only - the transform's scale is ignored. Bake dimensions into the shape (`from_size`, `from`, the capsule radius/height), and match your render mesh to it. ## Surface material - `friction` - Coulomb coefficient. Combined with the other surface via a geometric-mean rule. - `restitution` - bounciness, `0` (inelastic) to `1` (elastic). - `density` - used by inertia helpers if you opt in; informational otherwise. ## Layers and masks Each body carries a `layer` bitmask (its category) and a `mask` (the layers it collides with). A pair (A, B) collides only when **both** sides agree: ``` (A.layer & B.mask) !== 0 && (B.layer & A.mask) !== 0 ``` Defaults are `layer = 1`, `mask = 0xFFFFFFFF` - everything collides with everything. Carve groups out by assigning bits (e.g. put debris on its own layer and clear that bit from the player's mask so debris never blocks the player). ## Sensors and contact events A **sensor** detects overlaps and fires events but applies no impulse - the basis for triggers and volumes. Flag the whole body (`RigidBodyFlags.IsSensor`) or a single collider (`ColliderFlags.IsSensor`); either flag makes the body present as a sensor. Being a sensor is not just "no impulse". A sensor is not a solid surface anywhere in the pipeline: the contact solver skips its impulse, the island builder leaves it out of sleep islands (so a trigger overlapping a pile can't hold it permanently awake), and [raycasts pass straight through it](https://meep.company-named.com/docs/physics/queries/). The system dispatches contact events through the dataset's per-entity event channel - each contacting pair fires on **both** of its entities. Subscribe with `addEntityEventListener` for the entities you care about: ```js import { PhysicsEvents } from "@woosh/meep-engine/src/engine/physics/ecs/PhysicsEvents.js"; const ecd = entityManager.dataset; ecd.addEntityEventListener(entity, PhysicsEvents.ContactBegin, (contact) => { /* new pair this step */ }); ecd.addEntityEventListener(entity, PhysicsEvents.ContactStay, (contact) => { /* persisting pair */ }); ecd.addEntityEventListener(entity, PhysicsEvents.ContactEnd, (contact) => { /* pair separated */ }); ``` The `contact` payload carries `entityA`, `entityB`, `point`, `normal`, and `depth`. It is reused per dispatch - copy any field you need to keep past the listener. For broad-strokes filtering, install a contact filter; return `false` to discard a pair before the full collision test (the cheap layer/mask test runs first): ```js physics.setContactFilter((entityA, entityB, colliderA, colliderB) => { return true; // keep, or false to ignore this pair }); ``` ## Querying without colliding These same shapes drive the read-only [spatial queries](https://meep.company-named.com/docs/physics/queries/) - `raycast`, `shapeCast`, and `overlap` - which ask the physics world questions ("what's under the cursor?", "would I fit here?") without adding a body or stepping the simulation. ## Where to go next - [Rigid bodies](https://meep.company-named.com/docs/physics/rigid-bodies/) - the body the collider attaches to. - [Spatial queries](https://meep.company-named.com/docs/physics/queries/) - raycasts, shape casts, and overlap tests using these shapes. - [Raining rigid bodies](https://meep.company-named.com/examples/physics-rain/) - spheres, boxes, and capsules in one scene. - [Raycast vehicle](https://meep.company-named.com/examples/raycast-vehicle/) - a `HeightMapShape3D` terrain driven on. --- # Spatial queries Section: Physics Source: https://meep.company-named.com/docs/physics/queries/ Description: Ask the physics world questions without stepping it - raycasts, shape casts, and overlap tests against the live world. Three read-only queries let you interrogate the physics world between steps. None of them mutate the simulation, and all three run against the same spatial index the solver uses - one for static geometry, one for moving bodies - so they see exactly the world the simulation sees, and scale the same way. Each takes an optional `filter(entity, collider) => boolean`, consulted before the expensive exact-shape test. Use it to skip the caller's own body, allies, or whole layers. ## Raycasts `raycast` finds the nearest body a ray hits. The ray is origin + unit direction + `tMax`. ```js import { Ray3 } from "@woosh/meep-engine/src/core/geom/3d/ray/Ray3.js"; import { PhysicsSurfacePoint } from "@woosh/meep-engine/src/engine/physics/queries/PhysicsSurfacePoint.js"; const ray = Ray3.from(0, 50, 0, 0, -1, 0); // origin, unit direction, optional tMax const hit = new PhysicsSurfacePoint(); if (physics.raycast(ray, hit)) { // hit.position, hit.normal, hit.t, hit.entity, hit.body_id } ``` `PhysicsSurfacePoint` is an output parameter: pre-allocate one (or pull it from a frame pool) and pass it in. On a hit the query writes `position` (world-space point), `normal`, `t` (distance along the ray), `entity` and `body_id` - the packed `index << 8 | generation`, which goes stale once the body is unlinked, so keep `entity` for anything that crosses a frame. **On a miss the fields are left untouched**, so branch on the return value rather than on the contents. Bullets-as-rays, line-of-sight checks, mouse picking, ground probes. `hit.position` and `hit.normal` are three-element `Float64Array`s. Read x, y and z as `[0]`, `[1]`, `[2]`, for example `hit.normal[1]` for the upward component. They have no `.x` / `.y` / `.z` accessors or vector methods. **Rays pass through sensors.** A trigger volume is not a solid surface, so a body or collider flagged `IsSensor` is skipped and the ray lands on the nearest solid surface behind it - you don't need a filter for it. To find trigger volumes, use an overlap query instead; `overlap` and `shapeCast` still report sensors, and it's the filter's job to exclude them there if you don't want them. ### Normals are exact, with one caveat Each candidate the broadphase turns up is refined against its **true shape geometry**, so `t` is the exact surface distance and `normal` the exact surface normal for every shape the engine defines: the convex primitives (sphere, box, capsule, cylinder, point), the convex hull, the concave mesh and heightmap, and the wrappers, which recurse into what they wrap. A leaf whose ray crosses the broadphase box but misses the true shape contributes nothing. The one exception is a shape class defined **outside** the engine, which the refinement dispatch does not recognise. That leaf falls back to the shape's tight world AABB hit plus an AABB-face normal. The fallback answers with the bounding box, so a ray crossing the box but missing the shape reports a phantom hit - **it is a floor, not a contract**. It also divides by the box extent per axis, so a shape whose AABB is flat on one is resolved through `NaN` comparisons rather than geometry. A body with several colliders resolves its primary (first-attached) one: the broadphase leaf encodes only the body id. ## Shape casts `shapeCast` is a raycast with volume: it sweeps a **convex shape** along a ray and returns the first body it would hit. The shape starts at `ray.origin` oriented by `rotation`, translates along `ray.direction` for up to `ray.tMax`, and the result is the nearest time-of-impact. ```js import { CapsuleShape3D } from "@woosh/meep-engine/src/core/geom/3d/shape/CapsuleShape3D.js"; const probe = CapsuleShape3D.from(0.4, 1.2); const identity = new Float64Array([0, 0, 0, 1]); // poses are read as [x, y, z, w] const ray = Ray3.from(px, py, pz, dx, dy, dz, maxDistance); // unit direction const hit = new PhysicsSurfacePoint(); if (physics.shapeCast(ray, probe, identity, hit, (entity) => entity !== self)) { // first contact within maxDistance - hit.position, hit.normal, hit.t } ``` Internally it quickly gathers the bodies the sweep could reach, then computes the exact moment of contact for each and keeps the nearest, stopping early once nothing closer is possible. Unlike `raycast` this resolves against the real shapes throughout, so `t` is a true time of impact. This is the query behind **character controllers** ("how far can I step before I hit something?"), volumetric projectiles, and camera-collision that won't clip through walls. **A shape already touching a target at `t = 0` is not a hit.** Contact depth at or below a shared tolerance (`1e-4`, the same `CONTACT_EPSILON` the narrowphase's `compute_penetration` uses) counts as tangency rather than overlap - a kissing pair is not always numerically exact, and MPR reports a few microns of "overlap" for a sphere resting on a plane where a box-on-box kiss returns a clean zero. A tangency blocks only a sweep driving *into* it (more than about 0.006° off parallel); otherwise it steps aside so the cast can reach real blockers behind it. Without that, a character standing on the floor and casting sideways against a wall would fall through the floor. Genuine overlap at `t = 0` is still reported as a hit at `t = 0`: targets are solid and the sweep is blocked where it stands. Either way, one contact at the start of the sweep never blinds the cast to the rest of it. ## Overlap queries `overlap` is speculative: given a **convex shape** at a world pose, it reports every body that shape would touch - without moving anything. It's the *"would I collide if I stood here?"* test, the foundation of kinematic and character controllers. It writes the overlapping bodies' **packed body ids** into a buffer you size, returning the count. Map an id back to its entity with `physics.entityOf(id)`. Both queries read the pose **by index** - `position[0..2]`, `rotation[0..3]` - rather than as `{x, y, z}` objects, which is what lets a `Transform64`'s own `translation` and `rotation` views go straight in: `physics.overlap(probe, t.translation, t.rotation, ids, 0)` queries exactly the pose the entity is drawn at. A `Vector3` works too, since it is a `Float64Array`; a plain `{x, y, z}` object does not. ```js import { BoxShape3D } from "@woosh/meep-engine/src/core/geom/3d/shape/BoxShape3D.js"; const probe = BoxShape3D.from_size(2, 2, 2); const ids = new Uint32Array(64); // caller sizes the buffer const count = physics.overlap( probe, [0, 1, 0], // world position, read as [x, y, z] [0, 0, 0, 1], // world rotation, read as [x, y, z, w] ids, 0, // output buffer + start offset (entity) => entity !== self, // skip ourselves ); for (let i = 0; i < count; i++) { const entity = physics.entityOf(ids[i]); // react to the overlap… } ``` Ids past the end of the buffer are dropped silently and the count caps at the space available - size the buffer for the most you care to handle. The query shape must be convex; concave shapes (heightmaps, meshes) throw, since they're terrain, not probes. Explosion-radius damage, build-placement validity, hand-placed trigger volumes, "is this spawn point clear?" checks. ## Where to go next - [Colliders & shapes](https://meep.company-named.com/docs/physics/colliders/) - the shapes these queries take, and the layer/mask groups the filter complements. - [Rigid bodies](https://meep.company-named.com/docs/physics/rigid-bodies/) - driving a kinematic controller from `shapeCast` / `overlap` results. - [Math & geometry](https://meep.company-named.com/docs/math/geometry/) - the closed-form ray primitives each candidate is refined against. - [Spatial acceleration](https://meep.company-named.com/docs/math/spatial/) - the BVH both broadphase trees are built from. --- # Determinism Section: Physics Source: https://meep.company-named.com/docs/physics/determinism/ Description: The fixed-step contract that makes Meep's physics bit-exact across V8 runtimes - and what that buys you. Meep's physics is **deterministic**: the same inputs, applied in the same order, produce the same world - every run. And because the engine is pure JavaScript over IEEE-754 doubles, that result is **bit-exact across V8 runtimes** - Chrome, Edge, Node, Deno, and Electron all compute the identical answer, down to the last mantissa bit. This isn't a happy accident of the implementation. It's a designed property, and a few rules keep it intact. ## The fixed-step contract The simulation never advances by a variable frame time. The `EntityManager` accumulates real elapsed time and steps the solver in fixed increments (`fixedUpdateStepSize`, `0.025 s` / 40 Hz by default), draining the accumulator one fixed tick at a time. A slow frame runs several physics steps to catch up; a fast frame may run none - but every step that runs is the same size. Within each tick the solver runs a fixed pipeline: find the contacts, group the connected bodies, then run a fixed number of solver substeps (`solverSubsteps`, default 4), each doing a fixed number of iterations (`solverItersPerSubstep`). No step count depends on wall-clock time or measured load, so the arithmetic is identical regardless of how fast the machine is. ```pintora activityDiagram start :accumulate the real frame time; while (enough for a fixed step?) :advance physics by one fixed step; endwhile :render the frame; end ``` ## Why it's bit-exact Floating-point math is only "unpredictable" when something in the stack is. Meep removes those somethings: - **Pure JavaScript, IEEE-754 doubles.** No WASM with its own float settings, no GPU readback, no native library compiled per platform. V8 evaluates double arithmetic to the bit-identical result on every host it runs on. - **Fixed iteration order.** Bodies, contacts, and groups of touching bodies are processed in a stable, deterministic order, so the order-dependent sum of impulses lands the same way every time. - **No hidden entropy.** The solver reads no wall-clock, no `Math.random`, no uninitialized memory. The scoping word is *V8*. Different JavaScript engines may evaluate transcendental functions (`Math.sin`, `Math.sqrt` edge cases) to different last-bit results, so bit-exactness is guaranteed across the V8 family - which is every realistic web and Node target - rather than across all engines everywhere. ## What it buys you - **Lockstep multiplayer.** Replicate the input stream, not world state. Every client runs the same simulation and stays in sync - a few bytes of input per tick instead of a firehose of positions. See [Networking](https://meep.company-named.com/features/). - **Replays.** Record inputs once; replay the exact match, every time, on any V8 host. - **Server reconciliation.** An authoritative server re-runs a client's steps and gets the client's exact result - mispredictions are real divergences, not float noise. - **Reproducible tests.** A physics regression is a clean diff against a recorded trace, not a flaky heisenbug. ## Keeping it deterministic The engine holds up its end; your gameplay code has to hold up the other: - **Drive simulation from `fixedUpdate`, not `update`.** Anything that affects the physics result - applying forces, spawning bodies - belongs on the fixed clock. `update` runs once per rendered frame and is for presentation. - **Keep entropy out of the sim.** If you need randomness in simulated logic, use a seeded PRNG you control, not `Math.random`. Don't feed `Date.now()` or frame timing into physics decisions. - **Order your writes.** Create bodies and apply inputs in a consistent order across clients. Two clients that spawn the same bodies in a different order are simulating different worlds. Follow those and the simulation is a pure function of its inputs. ## Where to go next - [Physics overview](https://meep.company-named.com/docs/physics/overview/) - how determinism fits the rest of the engine. - [Rigid bodies](https://meep.company-named.com/docs/physics/rigid-bodies/) - applying forces on the fixed clock. --- # Joints Section: Physics Source: https://meep.company-named.com/docs/physics/joints/ Description: Connecting bodies with the Joint constraint - ball-sockets, hinges, sliders, welds, and world anchors. A `Joint` connects two bodies - or a body and the world - and removes degrees of freedom between them. One configurable constraint expresses the whole joint taxonomy: it has six independent degrees of freedom (3 linear, 3 angular), each of which can be locked, free, limited, sprung, or motorised. The named helpers below pick the right combination for you. ## Anatomy A joint holds an **anchor frame** on each body coincident according to its per-DOF rules: - `entityA` / `entityB` - the two bodies. Set `entityB = JOINT_WORLD` to anchor body A to a fixed point in the world instead of a second body. - `localAnchorA` / `localAnchorB` - the anchor point on each body, in that body's local frame. When `entityB === JOINT_WORLD`, `localAnchorB` is a **world** coordinate. - `localBasisA` / `localBasisB` - the orientation of the joint's reference frame on each body (unit quaternions, identity by default). The locked/free/limited axes are this frame's axes - so for a hinge you orient the frame so its free axis is the hinge axis. Register a joint with the `PhysicsSystem` once both bodies exist; remove it with `unlink_joint`: ```js import { Joint, JOINT_WORLD } from "@woosh/meep-engine/src/engine/physics/ecs/Joint.js"; import { v3_set } from "@woosh/meep-engine/src/core/geom/vec3/v3_set.js"; const joint = new Joint(); // default: ball-socket joint.entityA = linkA; joint.entityB = linkB; v3_set(joint.localAnchorA, 0, 0, -0.3, 0); // bottom of A v3_set(joint.localAnchorB, 0, 0, 0.3, 0); // top of B physics.link_joint(joint); ``` ## Joint types Each helper configures the six DOFs and returns the joint, so you can chain. They're the standard joints expressed as DOF patterns: | Helper | DOFs | Use for | | --- | --- | --- | | `asBallSocket()` *(default)* | 3 linear locked, 3 angular free | chains, ropes, pendulums | | `asHinge(axis)` | 3 linear + 2 angular locked, 1 angular free | doors, wheels, elbows | | `asPrismatic(axis)` | 2 linear + 3 angular locked, 1 linear free | sliders, pistons, lifts | | `asWeld()` | all 6 locked | rigidly fuse two bodies | | `asConeTwist(twistLo, twistHi, swingY, swingZ?)` | 3 linear locked, 3 angular limited | ragdoll shoulders / hips | For hinges and sliders, orient `localBasisA` / `localBasisB` so the free frame axis is the one you want. Anchors are three-element `Float64Array`s; basis quaternions are four-element arrays in `[x, y, z, w]` order. Use `v3_set` for anchors and `v4_set` (from `src/core/geom/vec4/v4_set.js`) for bases, or copy an existing indexed vector with `.set(vector)`. ## Anchoring to the world `entityB = JOINT_WORLD` pins body A to a fixed world point. A pendulum is one ball-socket to the world: ```js const pivot = new Joint(); pivot.entityA = bob; pivot.entityB = JOINT_WORLD; v3_set(pivot.localAnchorA, 0, 0, 1, 0); // top of the bob, in its frame v3_set(pivot.localAnchorB, 0, 0, 5, 0); // fixed world point to hang from physics.link_joint(pivot); ``` ## Chains Wire a column of bodies anchor-to-anchor - bottom of each link to the top of the next - and pin the first to the world, and you have a rope or chain. The solver runs extra iterations on joints (`physics.jointIterations`) so impulses propagate the length of the chain in a single tick. See the [Jointed chains](https://meep.company-named.com/examples/chains/) example, which hangs four of them and sweeps a kinematic log through. ## Beyond locked DOFs Locking and freeing DOFs covers the rigid joints above. The same `Joint` also gives each DOF a **limit**, **spring**, or **motor** - end-stops, suspension, powered hinges. Those live on the [Constraints](https://meep.company-named.com/docs/physics/constraints/) page. ## Where to go next - [Constraints](https://meep.company-named.com/docs/physics/constraints/) - per-DOF limits, springs, and motors on a joint. - [Rigid bodies](https://meep.company-named.com/docs/physics/rigid-bodies/) - the bodies a joint connects. - [Jointed chains](https://meep.company-named.com/examples/chains/) - a live demo built on ball-socket joints. --- # Constraints Section: Physics Source: https://meep.company-named.com/docs/physics/constraints/ Description: Per-DOF limits, springs, and motors on a Joint - end-stops, suspension, and powered axes. [Joints](https://meep.company-named.com/docs/physics/joints/) lock or free each of their six degrees of freedom. The same `Joint` also lets each DOF be **limited**, **sprung**, or **motorised** - which is where range-of-motion stops, suspension, and powered hinges come from. Every DOF independently takes one mode (`DofMode`): | Mode | Behaviour | | --- | --- | | `LOCKED` | held at the rest value (the rigid joints) | | `FREE` | unconstrained | | `LIMITED` | free within `[lower, upper]`, resisted at the stops | | `SPRING` | a soft spring (stiffness + damping) pulling toward rest | | `MOTOR` | driven toward a target velocity, bounded by a max force | You don't set the mode directly - the helpers below configure the DOF and switch it into the right mode. Axes are `0 = x, 1 = y, 2 = z` of the joint's frame. ## Limits - end-stops and range of motion ```js // A hinge that only opens 0°–90°: const door = new Joint().asHinge(/* free axis */ 1); door.setAngularLimit(1, 0, Math.PI / 2); // A slider with 0–2 m of travel: const lift = new Joint().asPrismatic(0); lift.setLinearLimit(0, 0, 2); ``` `setLinearLimit(axis, lower, upper)` is metres; `setAngularLimit(axis, lower, upper)` is radians. The angular limit uses a small-angle measure that's accurate for modest ranges; for wide cones (ragdoll shoulders) reach for `asConeTwist`, which measures swing and twist as exact angles. ## Springs - suspension and soft returns ```js // A wheel on a vertical suspension spring: const suspension = new Joint().asPrismatic(1); suspension.setLinearSpring(1, /* stiffness N/m */ 4000, /* damping N·s/m */ 300); // A lever that springs back to centre: hinge.setAngularSpring(0, /* N·m/rad */ 20, /* N·m·s/rad */ 2); ``` A spring DOF yields under load and drives back toward its rest pose (place the anchors so the relaxed position is the zero) instead of holding rigid. Stiffness `0` makes it a pure damper. ## Motors - powered axes ```js // A powered wheel spinning at 10 rad/s, up to 50 N·m: wheel.setAngularMotor(0, /* target rad/s */ 10, /* max torque N·m */ 50); // A conveyor / piston pushing at 1 m/s: piston.setLinearMotor(0, /* target m/s */ 1, /* max force N */ 200); ``` A motor is a force-limited velocity servo: it pulls the relative velocity toward the target as hard as the force budget allows (`Infinity` for an ideal drive, `0` to switch it off). ## Determinism Constraints solve in the same fixed-step solver loop as contacts and locked joints, so everything you build with them inherits the engine's [determinism](https://meep.company-named.com/docs/physics/determinism/) - limits, springs, and motors all reproduce bit-for-bit across V8 runtimes. ## Where to go next - [Joints](https://meep.company-named.com/docs/physics/joints/) - the joint types these modes build on. - [Determinism](https://meep.company-named.com/docs/physics/determinism/) - why a sprung, motorised rig still replays exactly. --- # Navigation meshes Section: Physics Source: https://meep.company-named.com/docs/physics/navigation-meshes/ Description: Build a walkable navigation mesh from scene geometry and query shortest paths between two world points. A navigation mesh is a simplified triangulated surface that covers the walkable area of a scene. Pathfinding runs over this surface rather than the full scene geometry, so queries stay fast regardless of how detailed the world is. Meep's navmesh is a `NavigationMesh` - a topology of triangular faces with a BVH sitting on top. All path queries go through the same object. ## Building a navmesh `NavigationMesh.build` takes your scene geometry as a `BinaryTopology` and an agent description, and produces the walkable surface: ```js import { NavigationMesh } from "@woosh/meep-engine/src/engine/navigation/mesh/NavigationMesh.js"; import Vector3 from "@woosh/meep-engine/src/core/geom/Vector3.js"; const navmesh = new NavigationMesh(); navmesh.build({ source, // BinaryTopology of the scene, triangulated agent_radius: 0.4, // metres; the walkable area is inset by this agent_height: 1.8, // metres; overhead obstacles are carved out agent_max_step_height: 0.3, // metres; bridge stair-height gaps agent_max_step_distance: 0.5, // metres; bridge lateral gaps agent_max_climb_angle: Math.PI / 4, // radians; steeper faces are excluded up: Vector3.up, // world-up axis for the climb-angle test }); ``` `source` must be triangulated - run `bt_mesh_triangulate` first if it is not - and must have consistent outward winding, since a single face normal cannot distinguish a correctly wound floor from a flipped one. It must also be a **manifold walkable surface, not a pile of solids**. Level geometry from a brush-based editor is a set of interpenetrating closed volumes - a floor brush is a sealed box whose top happens to be a floor - and fed in directly it produces a navmesh that routes almost nothing. Extract the walkable surface first: keep triangles whose normal passes the walk threshold and drop those whose space above is solid. Render geometry is not a substitute either; it produces an empty build, which is a legitimate answer to bad input and is reported as zero faces. Repair with `bt_merge_vertices_by_distance`, then `bt_mesh_fuse_duplicate_edges`, then `bt_mesh_resolve_t_junctions` - in that order, on a triangulated mesh - and check with `bt_mesh_validate` / `bt_mesh_is_manifold`. Neither check is run for you, because a full manifold check costs more than most builds. Repair cannot union two overlapping coplanar floor brushes; that needs a boolean union upstream. For brush-based levels, a waypoint graph traced with the collision system's shape cast often routes more than a repaired navmesh does. ### Build parameters | Parameter | Type | Default | Meaning | | --- | --- | --- | --- | | `source` | `BinaryTopology` | required | Triangulated scene geometry to derive the mesh from. | | `agent_radius` | `number` | `0` | Half-width of the agent. The outer boundary is eroded by it and obstacle footprints are dilated by it. Also drives hole filling and simplification tolerance - at `0` both are no-ops. | | `agent_height` | `number` | `0` | Agent standing height. At `0` no overhead clearance is enforced and no obstacle is carved. | | `agent_max_step_height` | `number` | `0` | Vertical gap the agent can bridge - stairs, kerbs. Opt-in: at `0` the topology is left alone. | | `agent_max_step_distance` | `number` | `0` | Lateral gap the agent can bridge - a hole in the floor. Opt-in in the same way. | | `agent_max_climb_angle` | `number` | `Math.PI / 4` | Maximum slope angle (radians) an agent can traverse. Steeper faces are excluded. | | `up` | `Vector3` | `Vector3.up` | World up-axis against which slope angles are measured. | The build runs roughly: compute face normals and drop faces that are too steep or degenerate → weld the resulting soup and fuse duplicate edges → resolve T-junctions → erode each island's outer boundary by the agent radius → carve obstacle footprints, pre-dilated by the radius → bridge steps and gaps if asked → split pinched vertices → fill sliver holes → collapse the redundant triangulation inherited from the render geometry → recompute face normals. `NavigationMesh.build` then constructs the face BVH with `bt_mesh_build_face_bvh`. ### Build hardening Three details are worth knowing when a navmesh comes out with unwalkable seams: - **One weld distance, `NAVMESH_WELD_DISTANCE = 1e-6`**, is used everywhere the build merges positions. It exists to reunite the same corner reached by different arithmetic - the erosion's cut band and the obstacle carve both reconstruct shared points per source triangle - not to simplify anything. Float32 storage resolution raises it where it is finer. - **A short-edge kill pre-pass runs before every merge.** A face with an edge shorter than what the merge treats as one point survives the merge as a loop that visits the same vertex twice - a non-manifold edge, which is an unwalkable boundary. `bt_mesh_kill_short_edges` removes those faces first; `bt_mesh_split_pinched_vertices` afterwards separates vertices where two sheets of surface meet at a single point, which is what a hairline crack from the carve leaves behind and what otherwise stops every boundary walk dead. - **Overhead obstacles are carved as footprints, not sampled.** A group of overhead faces sharing a vertex is carved as its **convex hull** when the group's triangles tile that hull, and triangle by triangle when they do not - an L-shape, a doorway frame, two obstacles that merely touch. Both routes carve the same ground wherever the hull is valid (dilation by a disc distributes over union); the hull is kept only because it is cheaper. The result is the true offset of the obstacle - straight along edges, a clean arc at corners - rather than the wavy contour that sampling-then-eroding produced. Footprints go in a quad-tree, so each soup triangle only tests the ones that can overlap it: O(m log k) for m soup triangles and k footprints. ## Querying a path `find_path` writes a sequence of 3-D waypoints into a caller-supplied `Float32Array` and returns the number of points written. Points are packed XYZ triples. It assumes the surface is manifold and does not check: on a non-manifold surface it can read a released vertex and **throw from inside Polyanya** rather than return `0`. If the input is in doubt, validate once at build time rather than defensively per query. ```js const output = new Float32Array(1024 * 3); // size for up to 1024 waypoints const count = navmesh.find_path( output, sx, sy, sz, // start position (world space) gx, gy, gz, // goal position (world space) ); if (count === 0) { // no path - disconnected topology or empty mesh } else { for (let i = 0; i < count; i++) { const x = output[i * 3]; const y = output[i * 3 + 1]; const z = output[i * 3 + 2]; } } ``` **Signature:** ``` find_path(output: Float32Array, sx, sy, sz, gx, gy, gz): number ``` - Returns `0` if the mesh is empty or the start and goal faces are in different connected components. - The first and last points are the start and goal **snapped onto the mesh surface**, so they may differ from the raw inputs when those lie off the mesh. - The output buffer must have room for the full path; size it for the worst case you expect. ## The path-finding pipeline Each `find_path` call runs two stages: 1. **Face snapping.** `bt_mesh_find_nearest_face` uses the BVH to find the nearest face to each of the start and goal positions. Each snapped point is then nudged a thousandth of the way toward its face's centroid: the search degenerates when a point sits exactly on a triangle edge, which snapped, grid-aligned queries do constantly. 2. **Polyanya.** `bt_mesh_face_find_path_polyanya` computes the **exact any-angle geodesic** across the surface (Cui, Harabor and Grastien, IJCAI 2017). Search nodes are `(root, interval)` pairs - an interval on a mesh edge, seen from a point the path is already taut through - and expanding one projects the visibility cone into the triangle beyond, clipping it against that triangle's far edges. The path turns only at obstacle corners; there is no corridor-then-string-pull step, because there is no corridor. The search is planar but **intrinsic**: it follows the surface by unfolding each triangle into the frame accumulated along its own corridor, so the costs are true geodesic distances on a sloped or folded navmesh, not only on a flat one. No global up-axis is assumed. The A* heuristic measures with straight 3-D chords, which lower-bound the geodesic and are therefore admissible. The output follows the surface too. It is subdivided wherever the geodesic crosses a face boundary, so every emitted segment lies within a single triangle and the path never flies over a convex crease nor tunnels through a concave fold. Collinear runs are collapsed, so on a planar mesh what comes out is just the minimal corner polyline. Scratch buffers are module-level, so `find_path` is allocation-free at query time once the search-node pool has grown to size. `bt_mesh_face_find_path` - plain A* over the triangle adjacency graph - and `funnel_string_pull` ship, but `NavigationMesh.find_path` does not use them. ## Grid-based A* For tile-based or grid worlds, a lighter alternative is available: ```js import { find_path_on_grid_astar } from "@woosh/meep-engine/src/engine/navigation/grid/find_path_on_grid_astar.js"; // field: flat typed array, width × height cells // start / goal: flat indices into the field // block_value: the value that marks an impassable cell const path = find_path_on_grid_astar(field, width, height, start, goal, block_value); // returns number[] of cell indices, start → goal, or [] if no path ``` The grid variant returns an array of cell indices with collinear segments collapsed (only turning-point indices are recorded). It uses 4-connected neighbours and a squared-distance heuristic. ## Where to go next - [Navigation agents](https://meep.company-named.com/docs/physics/navigation-agents/) - attach `Path`, `PathFollower`, and `PathFollowingSystem` to move an entity along a queried path. - [Spatial queries](https://meep.company-named.com/docs/physics/queries/) - raycasts and overlap tests against physics geometry. - [Math & geometry](https://meep.company-named.com/docs/math/geometry/) - `BinaryTopology` and the `bt_*` family the navmesh is built and queried with. --- # Navigation agents Section: Physics Source: https://meep.company-named.com/docs/physics/navigation-agents/ Description: Move an entity along a path using the Path, PathFollower, and PathFollowingSystem components. Once you have a path from a [navigation mesh](https://meep.company-named.com/docs/physics/navigation-meshes/), three ECS pieces advance an entity along it every frame: the `Path` component holds the waypoints, `PathFollower` controls movement parameters, and `PathFollowingSystem` drives the `Transform64` each tick. ## Path component `Path` stores a sequence of 3-D waypoints and provides sampling methods used by `PathFollowingSystem`. ```js import Path from "@woosh/meep-engine/src/engine/navigation/ecs/components/Path.js"; const path = new Path(); // Populate from a navmesh query const output = new Float32Array(1024 * 3); const count = navmesh.find_path(output, sx, sy, sz, gx, gy, gz); path.setPointCount(count); for (let i = 0; i < count; i++) { path.setPosition(i, output[i * 3], output[i * 3 + 1], output[i * 3 + 2]); } ``` ### Key methods | Method | Description | | --- | --- | | `setPointCount(n)` | Resize the waypoint list. Truncates or extends. | | `setPosition(index, x, y, z)` | Write a single waypoint. | | `getPosition(index, result: Vector3)` | Read a waypoint into a `Vector3`. | | `getPointCount()` | Current number of waypoints. Also available as `.count`. | | `isEmpty()` | `true` when there are no waypoints. | | `clear()` | Remove all waypoints. | | `sample(result: Vector3, offset, interpolation?)` | Sample a world-space position at `offset` metres along the path. | | `get length` | Total arc length, computed lazily and cached until waypoints change. | | `reverse()` | Flip the waypoint order in-place. | ### Interpolation `path.interpolation` controls how positions between waypoints are computed. Values come from `InterpolationType`: ```js import { InterpolationType } from "@woosh/meep-engine/src/engine/navigation/ecs/components/InterpolationType.js"; path.interpolation = InterpolationType.Linear; // straight segments (default) path.interpolation = InterpolationType.CatmullRom; // smooth non-uniform spline ``` | Value | Behaviour | | --- | --- | | `Linear` (1) | Straight-line interpolation between consecutive waypoints. | | `CatmullRom` (3) | Non-uniform Catmull-Rom spline - smooth curves through the waypoints. | ## PathFollower component `PathFollower` sits next to `Path` on the same entity and describes how the entity moves: ```js import PathFollower from "@woosh/meep-engine/src/engine/navigation/ecs/path_following/PathFollower.js"; import { PathFollowerFlags } from "@woosh/meep-engine/src/engine/navigation/ecs/path_following/PathFollowerFlags.js"; const follower = new PathFollower(); follower.speed.set(3); // world units per second (Vector1, default 1) follower.rotationSpeed.set(4); // rad/s; Infinity = instant (default Infinity) follower.position = 0; // current offset along path in metres ``` ### Flags `PathFollower.flags` is a bitmask. Use `setFlag`, `clearFlag`, and `getFlag` to manipulate it: ```js follower.setFlag(PathFollowerFlags.Loop); // wrap back to start when the end is reached ``` | Flag | Value | Meaning | | --- | --- | --- | | `Active` | 1 | System advances this follower. Cleared automatically on arrival when not looping. | | `Locked` | 2 | Reserved - no system behaviour currently. | | `Loop` | 4 | Wrap the path position back to 0 instead of stopping at the end. | | `Finished` | 8 | Set by the system when the follower reaches the end of a non-looping path. | | `WritePositionX` | 16 | System writes the X coordinate of the `Transform64`'s translation. | | `WritePositionY` | 32 | System writes the Y coordinate. | | `WritePositionZ` | 64 | System writes the Z coordinate. | | `WriteRotationX` | 128 | System aligns rotation around X toward the movement direction. | | `WriteRotationY` | 256 | System aligns rotation around Y (yaw toward movement). | | `WriteRotationZ` | 512 | System aligns rotation around Z. | The default flags enable `Active` and all six write flags, so an entity moves and faces its direction of travel out of the box. ## PathFollowingSystem `PathFollowingSystem` iterates every entity that carries `PathFollower + Transform64 + Path` and calls `performStep` for each one. Register it alongside the rest of your ECS systems: ```js import PathFollowingSystem from "@woosh/meep-engine/src/engine/navigation/ecs/path_following/PathFollowingSystem.js"; em.addSystem(new PathFollowingSystem()); ``` Each tick it: 1. Skips entities whose `PathFollower` does not have the `Active` flag or whose `Path` is empty. 2. Advances `pathFollower.position` by `speed × timeDelta` metres (capped at `maxMoveDistance` per sub-step to prevent tunnelling at very high speeds or large time steps). 3. Calls `path.sample(...)` with the new offset to get the next world position. 4. Writes the result back into the `Transform64`'s translation on the axes enabled by the `WritePosition*` flags. A step that moved the transform ends with `t64_announce_change`, so the agent's mesh, its sounds and anything else placed by its transform follow it with no code of yours; a follower that is idle or already at its end announces nothing. 5. When rotation alignment flags are set, turns the transform's rotation toward the movement direction at up to `rotationSpeed × timeDelta` radians, and composes the matrix afterwards. 6. When a non-looping follower reaches the end, sets `Finished`, clears `Active`, and fires a `"path-end-reached"` event on the entity. ### Arrival event Listen for the arrival event with the entity manager's event API: ```js import { PathFollowerEventType } from "@woosh/meep-engine/src/engine/navigation/ecs/path_following/PathFollowerEventType.js"; em.dataset.addEntityEventListener(entity, PathFollowerEventType.EndReached, () => { // entity reached the end of its path }); // PathFollowerEventType.EndReached === "path-end-reached" ``` ## Putting it together ```js import Path from "@woosh/meep-engine/src/engine/navigation/ecs/components/Path.js"; import PathFollower from "@woosh/meep-engine/src/engine/navigation/ecs/path_following/PathFollower.js"; import PathFollowingSystem from "@woosh/meep-engine/src/engine/navigation/ecs/path_following/PathFollowingSystem.js"; import { PathFollowerFlags } from "@woosh/meep-engine/src/engine/navigation/ecs/path_following/PathFollowerFlags.js"; // 1. Register the system once em.addSystem(new PathFollowingSystem()); // 2. Query a path from the navmesh const output = new Float32Array(1024 * 3); const count = navmesh.find_path(output, sx, sy, sz, gx, gy, gz); // 3. Build the Path component const path = new Path(); path.setPointCount(count); for (let i = 0; i < count; i++) { path.setPosition(i, output[i * 3], output[i * 3 + 1], output[i * 3 + 2]); } // 4. Configure the follower const follower = new PathFollower(); follower.speed.set(3); // 5. Attach to an entity new Entity() .add(new Transform64()) .add(path) .add(follower) .build(em.dataset); ``` The system takes it from there - `PathFollower.position` advances each frame until `"path-end-reached"` fires. ## Where to go next - [Navigation meshes](https://meep.company-named.com/docs/physics/navigation-meshes/) - building the navmesh and querying raw paths. - [Rigid bodies](https://meep.company-named.com/docs/physics/rigid-bodies/) - combining physics with navigation (kinematic bodies driven by path followers). --- # Fluid simulation Section: Physics Source: https://meep.company-named.com/docs/physics/fluid/ Description: A volumetric incompressible-flow solver on a staggered grid, run through ECS - fluid volumes are components, effectors stir them, and gameplay reads the velocity field back out. Meep ships a real-time volumetric fluid solver - incompressible flow on a MAC (staggered) grid, with stable semi-Lagrangian or MacCormack transport and an exact pressure projection. It's built for *gameplay* fluid: wind over a field, the wake of something fast, smoke drifting through a corridor - a velocity field your entities can both stir and read. Like the rest of the engine, you use it through ECS: a volume is a component, the simulation is a system, and sources of motion are effector objects on entities. ## The two-minute version ```js import { FluidComponent } from "@woosh/meep-engine/src/engine/physics/fluid/ecs/FluidComponent.js"; import { FluidEffectorsComponent } from "@woosh/meep-engine/src/engine/physics/fluid/ecs/FluidEffectorsComponent.js"; import { FluidEffectorsSystem } from "@woosh/meep-engine/src/engine/physics/fluid/ecs/FluidEffectorsSystem.js"; import { FluidSystem } from "@woosh/meep-engine/src/engine/physics/fluid/ecs/FluidSystem.js"; import { WakeFluidEffector } from "@woosh/meep-engine/src/engine/physics/fluid/effector/WakeFluidEffector.js"; // once, at startup - the effectors' system first em.addSystem(new FluidEffectorsSystem()); em.addSystem(new FluidSystem()); // a static volume of air over the scene const fluid = new FluidComponent(); fluid.field.setResolution(51, 11, 34); // cells fluid.field.build(); fluid.cell_size = 0.6; // world units per cell fluid.origin = [-15, 0, -10]; // world position of cell (0,0,0) new Entity().add(fluid).build(ecd); // something that stirs it: a wake towed by a moving entity const wake = new WakeFluidEffector(); wake.radius = 2; // world units const effectors = new FluidEffectorsComponent(); effectors.addEffector(wake); new Entity().add(transform).add(effectors).build(ecd); // the moving thing // something that reads it: sample anywhere, in world space const v = new Float32Array(3); fluid.sampleVelocityAtWorld(v, x, y, z); ``` That's the whole loop: the system steps every enabled volume on the fixed timestep - effector splats, advection, pressure projection - and anything in your game can sample the result. The [wake-field example](https://meep.company-named.com/examples/wake-field/) is exactly this: one volume, one wake effector on a flying ball, and 140 trees bending to `sampleVelocityAtWorld` every frame. ## The pieces **`FluidComponent`** is the volume: a velocity grid plus its placement in the world. The mapping is uniform and axis-aligned - `origin` is the world position of cell `(0,0,0)`, cells are `cell_size` apart. Placement comes in two flavours: - **Static** - the entity has no `Transform64`; you set `origin` once and the system never touches it. - **Moving** - pair the component with a `Transform64` and the system re-anchors the grid to the entity every fixed tick, shifting the field by whole cells so the fluid appears to stay put in world space while the grid follows the entity. A hysteresis deadband stops a transform sitting on a cell boundary from re-shifting every frame. Use this for a volume that follows the player through a large world. **`FluidEffectorsComponent`** holds the things that stir. Effectors are deliberately decoupled from any specific volume: the system gathers all of them and applies each to every field whose bounds it overlaps (a cheap AABB broad-phase filters the rest). Pair the component with a `Transform64` and position-bearing effectors follow the entity automatically. **`FluidEffectorsSystem`** gives every effector its per-tick life, once a fixed step however many fluid systems read them: it syncs position-bearing effectors from their entity's `Transform64`, advances each effector, and folds every `GlobalFluidEffector` into one far field. `FluidSystem` and `WorkerFluidSystem` require it; register it first. **`FluidSystem`** is the pump. It runs on `fixedUpdate` - fluid stability and the warm-started pressure solve both want a constant dt - and owns one simulator that services every volume. ## Effectors | Effector | What it does | |---|---| | `WakeFluidEffector` | Splats the momentum of a moving source along its swept path - the wake of an agent passing through air or water. Transform-managed when its entity has a `Transform64`; works at any radius down to sub-cell. | | `ImpulseFluidEffector` | A velocity splat in a spherical region with a smooth quadratic falloff - fans, jets, point explosions. | | `GlobalFluidEffector` | The atmosphere: every cell integrates `dv/dt = force + drag · (wind − v)`, with turbulence carried on top of the wind (`turbulence_intensity`, `turbulence_length` - see [the scene's wind](#the-scenes-wind)). A bare `force` is a body force (note it grows without bound unless something dissipates it); `wind` + `drag` gives relaxation toward an ambient flow with a real terminal velocity. Globals act only through the far field `FluidEffectorsSystem` folds them into, so several act as one. | One sharp edge worth knowing: a teleporting wake source must call `wake.reset_trail()` after the jump, or the effector treats the teleport as one giant swept segment and splats a wall of momentum across the whole field. (The wake-field example does this on every loop wrap.) Custom effectors are a small class: extend `AbstractFluidEffector`, implement `apply(field, dt, world_to_grid)` and `getBoundingBox(out)`. ## The scene's wind The far field is also the scene's wind for everything that is not a CPU field. `GPUFluidSystem` (`engine/graphics3/GPUFluidSystem.js`) publishes it every frame as the scene's wind field, which water waves, cloth, particles and volumetric fog sample. Without a domain it publishes the far field alone; an entity with a `GPUFluidComponent` and a `Transform64` adds nested GPU fluid cascades around that entity, forced by the scene's wake, impulse and vortex effectors and `FluidObstacle`s. ```js import { GPUFluidSystem } from "@woosh/meep-engine/src/engine/graphics3/GPUFluidSystem.js"; import { GlobalFluidEffector } from "@woosh/meep-engine/src/engine/physics/fluid/effector/GlobalFluidEffector.js"; em.addSystem(new FluidEffectorsSystem()); em.addSystem(new GPUFluidSystem(engine.graphics, scene)); const weather = new GlobalFluidEffector(); weather.wind = [4, 0, 0]; // m/s weather.drag = 1; // per second: how quickly the air returns to `wind` weather.turbulence_intensity = 0.15; // eddies' rms, as a share of the mean speed const effectors = new FluidEffectorsComponent(); effectors.addEffector(weather); new Entity().add(effectors).build(ecd); ``` ### Mean and turbulence The far field is a mean wind plus a field of eddies the mean carries along. `FluidEffectorsSystem` folds every global into it once a tick: the drags sum, and the winds, the turbulence intensities and the length scales each fold to their drag-weighted mean, so several globals act as one whatever order they are in. The mean relaxes toward the folded wind at the summed drag; a scene that starts with its globals starts in steady state. | Field | Default | Meaning | |---|---|---| | `turbulence_intensity` | `0` | The eddies' rms on each axis as a share of the mean speed. `0` is no turbulence; near-ground wind over grass and crops measures `0.15` to `0.2`. A far field with no mean speed has no turbulence. | | `turbulence_length` | `58.6` | The von Kármán length scale `L`, in world units, above `0`. The most energetic eddies are about `4.05·L` long. The eddies come from one repeating tile, `16·L` across and `4·L` up, holding wavelengths down to `L/4`. | The eddies are isotropic turbulence, frozen and carried by the mean wind (Taylor's hypothesis): a gust travels downwind at the wind's speed, and two points a few metres apart feel it at different times. A smaller `turbulence_length` reaches down to a canopy's own eddies at the cost of a shorter repeat. Changing it rescales the eddies about the world's origin, so the air jumps: it is a property of a scene's weather, set once. How far the mean has carried the eddies is the system's own state and starts at zero, so a scene loaded from a save starts the eddies over. Who sees the turbulence: every GPU reader of the wind field, both cloth winds, and the GPU fluid, which steps every cascade toward the whole far field, so the ground, a wall or a canopy shapes the eddies. CPU fields (`FluidSystem`, `WorkerFluidSystem`) are brought to the mean alone. `gpu_fluid_system.far_field(out)` answers the far field's mean in m/s, and `gpu_fluid_system.far_field_at(out, x, y, z)` the far field at a world point, its turbulence included. Both are synchronous and deterministic, with or without a device - what gameplay should read. `request(...)` reads a lattice of the published wind back from the GPU, a frame or more late, for presentation only. A `ClothSystem` reads this wind by default: `ClothGPUFluidWind` while the scene has a GPU fluid domain, otherwise `ClothFluidWind` over the CPU fields and the far field outside them, and no air when there is neither. Both read the far field at the point they sample, turbulence included. Assigning `cloth_system.wind` overrides the choice; `null` keeps cloth out of the air. `GlobalFluidEffector` serializes through `GlobalFluidEffectorSerializationAdapter` at version 1: `force`, `wind`, `drag`, `turbulence_intensity` and `turbulence_length`. A host that loads version-0 streams registers `GlobalFluidEffectorSerializationUpgrader_0_1` (`engine/physics/fluid/effector/GlobalFluidEffectorSerializationUpgrader_0_1.js`) beside the adapter. ### Obstacles An entity with a `FluidObstacle` (`engine/physics/fluid/ecs/FluidObstacle.js`), a `Collider`, a `RigidBody` and a `Transform64` stands in the wind: its collider's shape is the obstacle and its body's velocity is what the air takes at it. `inflation` (world units, default `0`) grows or shrinks the shape. `drag` (per metre, default `0`) says how it stops the wind. At `0` the obstacle is solid. Above `0` it is porous: the air passes through it and is slowed toward its velocity by `drag · |u − v| · (u − v)` each second, `u` the air's velocity and `v` the obstacle's. For something made of leaves or blades - a field of grass, a crop, a hedge, the crown of a tree - it is their drag coefficient times their one-sided area per cubic metre of the volume. Only the GPU fluid has porous obstacles; `FluidObstacleSystem`, which voxelizes obstacles into CPU fields, leaves them out. ## Reading the field `sampleVelocityAtWorld(out, x, y, z)` returns trilinearly-interpolated velocity in **grid cells per second**, deliberately not rescaled by `cell_size`: read-side consumers like vegetation sway and dust drift want a consistent "wind strength" regardless of grid resolution. Multiply by `cell_size` if you need world-units-per-second. There's also `sampleScalarAtWorld(name, x, y, z)` for passive scalars (smoke density, dye) declared on the field with `field.addScalar(name)` before `build()`. Reading is cheap - a few hundred samples per frame is nothing - and it's the intended coupling point between the simulation and your game: trees bend, particles drift, cloth flutters, all without feeding anything back into the solver. ## Tuning the simulator The system's simulator is shared by all volumes; its knobs are engine-level: ```js const sim = em.getSystem(FluidSystem).simulator; sim.velocity_damping = 1.5; // exponential decay, per second - gusts die back to calm sim.advection_scheme = AdvectionScheme.SEMI_LAGRANGIAN; // or MACCORMACK (default) sim.vorticity_confinement = 0; // ε, per second - sharpens vortex cores; adds energy ``` Guidance that took us some trial and error in the wake-field example: - **`velocity_damping`** is the knob for "how far does a disturbance travel". The solver's incompressible projection has no propagating pressure wave - what travels is the shed vortices, and damping decides how long they live. `0` (the default) never settles under sustained forcing. - **`advection_scheme`**: MacCormack (default) is second-order and nearly energy-conserving - great for smoke plumes, but sustained stirring keeps ricocheting around the volume. Semi-Lagrangian smears small structures away, which for ambience-style wind is a feature: the gust passes, the field calms. - **`vorticity_confinement`** re-sharpens vortices that coarse grids smear. On the MAC grid it's rarely needed - the staggered discretization already preserves rotation well - and pairing it with low damping keeps a field churning indefinitely. Reach for it for visual smoke, not gameplay wind. Scalars: `velocity_diffusion_rate` / `scalar_diffusion_rate` add physical diffusion; the pressure solver can be switched from SOR to preconditioned conjugate-gradient (`pressure_solver = PressureSolver.MICPCG`) for large grids. ## Sizing and cost The solver is pure JavaScript and steps on the fixed timestep, so budget by cell count: the wake-field example runs a 51×11×34 grid (~19k cells) alongside rendering, trails, and 140 sampling consumers without drama. Coarse grids are usually the right call - gameplay reads the field through its consumers (bending trees, drifting particles), which forgive far lower resolution than direct volumetric rendering would. Solid cells (`field.setSolidAt`) let flow route around level geometry. For splashy, free-surface liquids - water you can pour, mud, granular material - the grid solver is the wrong tool; that's the domain of the separate MLS-MPM material-point solver under `engine/physics/mls-mpm/`. ## Running the solve off-thread `WorkerFluidSystem` is a drop-in alternative to `FluidSystem` that moves the expensive half of the step - diffusion, projection, transport, scalars - onto a worker thread. It's built on [`WorkerSystem`](https://meep.company-named.com/docs/ecs/systems/), so the field lives in a `SharedArrayBuffer` the worker steps in place: nothing is copied, and a fixed-step gate keeps the simulation deterministic. ```js import { WorkerFluidSystem } from "@woosh/meep-engine/src/engine/physics/fluid/ecs/WorkerFluidSystem.js"; import { makeFluidWorker } from "@woosh/meep-engine/src/engine/physics/fluid/ecs/makeFluidWorker.js"; fluid.field.shared_memory = true; // before build() fluid.field.build(); em.addSystem(new FluidEffectorsSystem()); em.addSystem(new WorkerFluidSystem({ worker_factory: makeFluidWorker })); ``` Re-anchoring, the AABB broad-phase, and `effector.apply(...)` stay on the main thread, as does `FluidEffectorsSystem`'s effector sync - effectors are arbitrary user classes, and keeping them here is what makes the swap transparent. The worker runs the same `simulator.step` over the same data in the same order, so results are bit-for-bit identical to `FluidSystem`'s. What changes: - **The page must be cross-origin isolated** (`Cross-Origin-Opener-Policy: same-origin` + `Cross-Origin-Embedder-Policy: require-corp`), or `SharedArrayBuffer` doesn't exist and startup throws. - **The worker owns the field outside the fixed pass.** Reading a field from `update()` or at render time is not supported - which rules out exactly the render-time `sampleVelocityAtWorld` reads (vegetation sway, dust drift) that most scenes use fluid for. Systems that touch fields must be registered *before* this one so they run earlier in the fixed pass. - **Results lag by one tick**: at tick `T` the field holds step `T - 1`. The sequence of states is unchanged, it's observed one tick later. - A newly linked field isn't stepped until the worker acknowledges it (a cold-plane round trip - at least one tick, in practice a few). It's still re-anchored in that window. So: reach for it when fluid is consumed inside the fixed pass and the pressure solve is your frame budget's problem. Stay on `FluidSystem` when anything samples the field from rendering - which today is most scenes, including the wake-field example. ## Related - [Wake field example](https://meep.company-named.com/examples/wake-field/) - the full loop: volume, wake effector, 140 read-side consumers - [Physics overview](https://meep.company-named.com/docs/physics/overview/) - the rigid-body side of the physics package - Source: `engine/physics/fluid/` - `FluidSimulator.js` carries extensive doc comments on every knob --- # First-person controller Section: Gameplay Source: https://meep.company-named.com/docs/first-person/ Description: A kinematic-capsule first-person controller - mouse-look and movement, the procedural camera and locomotion feel on top, an opt-in movement-ability set, and read-only state for HUDs and AI. `FirstPersonPlayerController` is a single component (plus its system) that turns an entity into a first-person character. The visible part is what you'd expect - a capsule that walks, sprints, crouches, and jumps under mouse-look. Underneath, it also drives a procedural camera, exposes a clean control surface, and carries an optional movement-ability vocabulary. Out of the box you get the capsule and the camera feel; the abilities and the mastery layer are opt-in. ## Intent, not input The controller never touches the keyboard or mouse. It exposes an **intent** surface that input bindings or an AI script write each frame: ```js const intent = controller.intent; intent.move.set(x, y); // forward+ / right+, in body-local space intent.look._add(dYaw, dPitch); intent.jump = held; // hold-state - the system edge-detects intent.sprint = held; intent.crouch = held; ``` `move`, `jump`, `sprint`, and `crouch` are latched hold-states; `look` accumulates deltas and is consumed once per fixed step. Edge detection is internal - holding the jump button produces exactly one jump, and its release drives variable jump height. The same fields serve mouse-and-keyboard, gamepad, or an AI agent with no changes to the controller. ## Body and eye The controller drives **two** transforms. The entity's own `Transform64` is the body: ground-projected, yaw only, physics-clean - what the collider integrates. The system creates a separate **eye** entity (its own `Transform64` + `Camera`) on link, and that's where the feel lives: - gait-driven **head bob** - an under-damped spring kicked at each footfall, not a sine - **breathing** whose rate and amplitude scale with an exertion signal that rises while you sprint and jump and decays when you stop - **jump anticipation** (a small squash before take-off) and **landing recovery** (a spring that dips and rings on impact) - **lean** roll into lateral acceleration, and an **FOV** kick at sprint speed, sprung into the eye camera's `fov` with `camera.fov.set(v)` - forgiveness: **coyote time**, **jump buffer**, and a faster fall gravity for **variable jump height** Splitting the two keeps body kinematics clean for collision and AI line-of-sight while the camera is free to dip and oscillate. Every effect above is a config knob, tunable per entity - a heavy soldier and a light scout are data, not code - and bob, lean, and the FOV kick have explicit off switches for motion sensitivity. ```pintora componentDiagram [Input or AI intent] --> [FirstPersonPlayerControllerSystem] [FirstPersonSensorsSystem] --> [FirstPersonPlayerControllerSystem] package "Body entity" { [Body Transform64 (yaw only)] [KinematicPosition capsule] } package "Eye entity" { [Eye Transform64 (full 6DOF)] [Camera] } [FirstPersonPlayerControllerSystem] --> [Body Transform64 (yaw only)] [FirstPersonPlayerControllerSystem] --> [Eye Transform64 (full 6DOF)] ``` ## Movement abilities Abilities are opt-in modules added to `controller.abilities`. The set is empty by default; base locomotion is unchanged until you add them: ```js controller.abilities.add(new Slide()); controller.abilities.add(new Mantle()); controller.abilities.add(new WallRun()); controller.abilities.add(new WallJump()); controller.abilities.add(new LedgeGrab()); ``` At most one is active at a time; they activate by priority and can preempt or queue. They share a **sensor** layer - a small set of raycast probes (walls to the left/right/front, an obstacle-ahead probe, a ledge probe) computed once per step and reused - so registering the sensors system is all the abilities need to read the world. They engage on their own against the right geometry; there are no ability buttons beyond move, jump, sprint, and crouch. ## Mastery (optional) `controller.mastery` is a registry of timing evaluators, also empty by default. Each returns a multiplier at a **decision point** - jump impulse, ground acceleration, slide entry, wall-jump - and they compose multiplicatively. The shipped evaluators are physically motivated (stride phase, foot side, breath rhythm), small in magnitude, and feed a telemetry score a HUD can read. Add it for skill-timed depth; leave it empty and nothing changes. ## Reading state The controller publishes read-only outputs every step: - `controller.state` - `grounded`, `speed`, `verticalSpeed`, `airborneTime`, `exertion`, `breathPhase`, `stridePhase`, and more, for HUDs and AI. - `controller.signals` - `onFootStep`, `onJumpStart`, `onLand`, `onBreathIn` / `onBreathOut`, and more, for audio and FX. - `controller.pose` - head/root channels and a locomotion phase, a stable contract a skeleton or networked rig can drive itself from. Only `config` is serialized; everything else is rebuilt on link. ## Using it The player is a `KinematicPosition` body with a capsule collider - the controller writes the `Transform64` and a collision mover keeps it out of walls. Register `FirstPersonPlayerControllerSystem` (and `FirstPersonSensorsSystem` if you use abilities); the system creates the camera for you. Ground is resolved by the built-in flat baseline, a downward physics raycast you wire in, or the collision mover when a physics system is present. The **[first-person example](https://meep.company-named.com/examples/first-person/)** is a complete, runnable setup - the capsule, the systems, input bindings, a physics-backed ground resolver, and all five abilities across a parkour gym. Start there. --- # Input devices Section: Gameplay Source: https://meep.company-named.com/docs/gameplay/input-devices/ Description: InputMap bindings, InputController gestures, and keyboard, pointer, gamepad and WebXR devices. Meep exposes four input devices on `engine.devices`: `keyboard`, `pointer`, `gamepad` and `xr`. All four are started by the engine at boot. Two binding layers sit on top of them, and which one you want depends on what you are binding: - **`InputMap`** - the Input Map System. Typed triggers (keys, mouse buttons, gamepad buttons, and chords, sequences, holds and releases built out of them) and analog channels bind to *action names*, and an action fires as an ECS entity event. Keyboard and pointer-button bindings belong here. - **`InputController`** - string paths from `engine.devices` to callbacks. Not deprecated: it is the only way to bind a pointer *gesture* - `tap`, `drag`, `dragStart`, `dragEnd`, `move`, `pinch` - which `PointerDevice` synthesizes on top of its buttons and which the binding layer does not model. Neither system is registered by default - add the one you use to the entity manager yourself. (`EngineHarness.buildBasics` is one exception: its orbital camera controller registers `InputControllerSystem` if nothing else has.) The `Input` / `InputSystem` / `InputBinding` trio is [deprecated](#deprecated-input-inputsystem-inputbinding). ## The Input Map System An `InputMap` is a component holding bindings. A binding names an **action**; what the action *does* is an entity event listener on the owning entity. Nothing behavioural is stored in the map, which is the seam that lets bindings be data. ```js import Entity from "@woosh/meep-engine/src/engine/ecs/Entity.js"; import { InputMap } from "@woosh/meep-engine/src/engine/input/ecs/ism/map/InputMap.js"; import { InputMapSystem } from "@woosh/meep-engine/src/engine/input/ecs/ism/InputMapSystem.js"; import { KeyboardInputDeviceAdapter } from "@woosh/meep-engine/src/engine/input/ecs/ism/device/KeyboardInputDeviceAdapter.js"; import { PointerInputDeviceAdapter } from "@woosh/meep-engine/src/engine/input/ecs/ism/device/PointerInputDeviceAdapter.js"; import { GamepadInputDeviceAdapter } from "@woosh/meep-engine/src/engine/input/ecs/ism/device/GamepadInputDeviceAdapter.js"; import { InputTriggerKey } from "@woosh/meep-engine/src/engine/input/ecs/ism/trigger/InputTriggerKey.js"; import { InputTriggerChord } from "@woosh/meep-engine/src/engine/input/ecs/ism/trigger/InputTriggerChord.js"; await em.addSystem(new InputMapSystem([ new KeyboardInputDeviceAdapter(engine.devices.keyboard), new PointerInputDeviceAdapter(engine.devices.pointer), new GamepadInputDeviceAdapter(engine.devices.gamepad) ])); const map = new InputMap(); map.bind("jump", InputTriggerKey.from("space")); map.bind("undo", InputTriggerChord.from(InputTriggerKey.from("ctrl"), InputTriggerKey.from("z"))); const entity = new Entity().add(map).build(ecd); ecd.addEntityEventListener(entity, "jump", () => player.jump()); ecd.addEntityEventListener(entity, "undo", () => editor.actions.undo()); ``` `bind(action, ...triggers)` takes several triggers for one action - any of them firing fires the action. `unbind(action)` removes it. Lifetime is entity lifetime: bindings go live when the component links and stop when it unlinks, so a mode that owns an entity needs no enable/disable bookkeeping. Structural edits are picked up automatically - the system recompiles a map whose bindings or layers changed, including edits made through a layer handle you kept. One `InputMap` instance backs one entity. Sharing an instance across two entities is asserted against: the component holds a single compiled program, so the second link would hijack it. `InputMap.serializable` is `false` in 3.71.0. The binding format is designed to serialize and the component is shaped for it, but the adapter is not built yet - build maps in code. ### Two orderings, and they are different Conflating these is what makes input systems muddy, so the map keeps them apart: | Ordering | Scope | Arbitrates over | Use it for | |---|---|---|---| | **Layers** | within one map | action names | a user keymap rebinding an action the defaults also bind | | **`order` + `occlusion`** | between maps | physical switches | a modal dialog taking a key away from the scene underneath | ### Layers cascade by action name `map.layers` is an array; index 0 is the base, higher indices are higher in the cascade. `bind`, `bindCoordinate` and `unbind` on the map itself operate on the base layer; `map.layer(i)`, `map.pushLayer()` and `map.popLayer()` reach the rest. The cascade works exactly like CSS layers: the **topmost layer that binds an action supplies all of that action's triggers**, and lower layers' entries for it are inert. Layers carry no name - a stack is addressed by index, so there is nothing to look up and nothing to mistype. ```js map.bind("fire", InputTriggerMouseButton.from(MouseButtons.left)); // defaults, layer 0 const userKeymap = map.pushLayer(); // layer 1 userKeymap.bind("fire", InputTriggerKey.from("f")); // replaces, does not add userKeymap.unbind("crouch"); // masks the default entirely ``` Re-binding an action already bound *in the same layer* replaces its triggers - one entry per action per layer is what makes the cascade well defined. `unbind` in a higher layer leaves an empty entry behind on purpose: the cascade stops at the topmost layer that mentions the action, and that layer supplies no triggers. An action cannot be a trigger action and a coordinate action in the same layer. ### `order` and `occlusion` arbitrate between maps Every linked map is evaluated in descending `order` (higher first), ties going to the oldest-linked. A trigger that fires **consumes** the switches it matched, so a map's own bindings arbitrate by specificity - more sequence steps first, then wider chords, then declaration order - and `Ctrl`+`Z` beats a bare `Z`. `occlusion` decides whether that consumption is still standing when the next map down is walked. ```pintora dotDiagram digraph { switch_edge -> dialog_map [label="order 10, first refusal"] dialog_map -> scene_map [label="switches it did not consume"] scene_map -> entity_event [label="dispatch"] } ``` `InputOcclusion` (`.../ism/InputOcclusion.js`): | Value | Effect on maps below | |---|---| | `Pass` (0) | Sees everything, blocks nothing. HUD overlays, debug readouts, recorders. | | `BlockMatched` (1) | **Default.** Switches consumed by this map's fired triggers are invisible below, *for that edge only*. A lower map's `isActive` and coordinate reads are untouched - a dialog binding Escape stops the scene's Escape while the camera keeps panning behind it. | | `BlockAll` (2) | Every map below is suppressed outright: no dispatch, `isActive` reads false, coordinate reads return zero, sequences do not advance and holds do not run. The modal hammer - this is the one that stops a pause menu leaving the world drifting. | `BlockAll` suppression is static, recomputed when the linked map set, any `order` or any `occlusion` changes. Coming back out from under it resets every trigger against current reality, so a half-matched sequence cannot complete on one further step. ### Triggers All named exports under `@woosh/meep-engine/src/engine/input/ecs/ism/trigger/`. They compose: a chord's children are triggers, not sources, so a chord of a hold, or a chord spanning a keyboard and a mouse, needs no special case. | Class | Factory | What it is | |---|---|---| | `InputTriggerKey` | `.from(key)` | True while a keyboard key is held. `key` is a [`KeyCodes`](#keyboarddevice) name or value; a typo asserts where it is written instead of never firing. | | `InputTriggerMouseButton` | `.from(button)` | True while a pointer **button** is held. `button` is a `MouseButtons` name or value. Not a gesture. | | `InputTriggerGamepadButton` | `.from(button)` | True while a gamepad button is held. Binds against `gamepad.main`, so it resolves before any pad is plugged in and survives a hot-swap. | | `InputTriggerChord` | `.from(...children)` | AND. True while every child is true. | | `InputTriggerSequence` | `.from(...steps)` | True on the single evaluation point at which its steps complete in order. | | `InputTriggerHold` | `.from(child, duration)` | True once `child` has been continuously true for `duration` seconds. | | `InputTriggerRelease` | `.from(child)` | NOT. True while `child` is not - this is how "on release" is expressed. | | `InputTriggerSwitch`, `InputTrigger` | - | Base classes. | ```js map.bind("interact", InputTriggerHold.from(InputTriggerKey.from("e"), 0.5)); map.bind("charge_release", InputTriggerRelease.from(InputTriggerKey.from("space"))); map.bind("konami_start", InputTriggerSequence .from(InputTriggerKey.from("up_arrow"), InputTriggerKey.from("up_arrow")) .withStepTimeout(0.25)); ``` A sequence advances on a step's **rising** edge, not on its satisfaction, so one long press of A cannot satisfy both steps of `[A, A]`. Its window is measured from when the previous step *stopped* being true - which is what makes a charge input work - and defaults to `INPUT_SEQUENCE_DEFAULT_STEP_TIMEOUT`, 1 second; `withStepTimeout(seconds)` tightens it (0.15-0.25 for fighting-game motions). A mismatch never resets a sequence; only the window does. Two things worth knowing before you reach for them: - A hold's maturity is announced by no device edge, so it is detected on the tick that crosses the duration. Its latency is bounded by the frame. - Do not wrap a sequence in `InputTriggerRelease`. A sequence's test is a single-edge pulse, so negating it is true almost always and rises again right after each completion - an echo of the fire, not "the sequence stopped matching". ### Analog channels `map.bindCoordinate(action, ...channels)` binds an N-dimensional analog value rather than an edge. Read it with `map.axis1(vector1, action)`, `map.axis2(vector2, action)`, `map.axis3(vector3, action)`, or the raw `map.coordinate(array, offset, action)`. ```js import { InputCoordinateDevice } from "@woosh/meep-engine/src/engine/input/ecs/ism/coordinate/InputCoordinateDevice.js"; import { InputCoordinateSwitches } from "@woosh/meep-engine/src/engine/input/ecs/ism/coordinate/InputCoordinateSwitches.js"; import { GamepadCoordinates } from "@woosh/meep-engine/src/engine/input/devices/gamepad/GamepadCoordinates.js"; import { PointerCoordinates } from "@woosh/meep-engine/src/engine/input/devices/PointerCoordinates.js"; // Stick first, WASD as the fallback - one action, two devices. map.bindCoordinate("move", InputCoordinateDevice.fromGamepad(GamepadCoordinates.left_stick), InputCoordinateSwitches.from([ InputTriggerKey.from("a"), InputTriggerKey.from("d"), // x: negative, positive InputTriggerKey.from("w"), InputTriggerKey.from("s") // y: negative, positive ]) ); map.bindCoordinate("look", InputCoordinateDevice.fromPointer(PointerCoordinates.move)); // ... in a system, once per frame map.axis2(move, "move"); map.axis2(look, "look"); ``` Several channels on one action resolve by **priority**: the first with any non-zero component wins, and the last is the fallback. That is what a consumer hand-writes when fusing a stick with WASD, and it avoids the arithmetic nonsense of summing a keyboard's 1 with a stick's 0.3. Every channel bound to one action must agree on dimensionality (asserted). | Channel | Components | Kind | |---|---|---| | `InputCoordinateDevice.fromGamepad(GamepadCoordinates.left_stick \| right_stick \| dpad)` | 2 | Normalized, hardware frame (+x right, +y **down**) | | `InputCoordinateDevice.fromPointer(PointerCoordinates.position)` | 2 | Absolute, viewport pixels | | `InputCoordinateDevice.fromPointer(PointerCoordinates.move)` | 2 | Delta, latched per frame | | `InputCoordinateDevice.fromPointer(PointerCoordinates.wheel)` | 3 | Delta, latched per frame | | `InputCoordinateSwitches.from(triggers)` | `triggers.length / 2` | 2 triggers per axis, negative then positive | Relative channels **latch**: the adapter sums arriving events into an accumulator and publishes it once per frame, so every reader in a frame sees the same number regardless of system order, and events arriving mid-frame belong to the next one. Wheel components are the *sign* of each delta, so accumulating that channel counts ticks rather than measuring scroll distance. Both directions of a switch axis held reads zero for that axis. Channels report raw composed values. Dead zones, response curves and sensitivity are gameplay policy and stay at the call site - see [`apply_radial_dead_zone`](#gamepaddevice). Hardware error has already been corrected by the device. ### Dispatch, timing and lifetime Dispatch is **eager**: an edge is evaluated and dispatched inside the device signal that produced it. There is no input buffer and no added frame of latency - and the consequence is that your handler runs inside a DOM event handler, so keep it short and do not assume you are on the tick. `InputMapSystem.update(dt)` dispatches no edge-driven action. It services only what changes without an edge: hold maturity, sequence windows, delta-coordinate latching and reset, and suppression recomputation. Time is advanced there and nowhere else, so every window in the system is **simulation** time - holds do not mature while the game is paused, and they stretch under slow motion. A handler receives one `InputActionEvent`: | Field | Meaning | |---|---| | `action` | the action name | | `source` | an `InputSource` - `device` (`"keyboard"`, `"pointer"`, `"gamepad"`) and `code`. The switch whose edge completed the trigger; for a hold maturing, the hold's first source. | | `time` | seconds since the system started, in simulation time | | `value` | `Vector3`, reserved for the driving coordinate; zero for a trigger with no analog source | **One instance is reused and mutated in place.** Reading it inline is correct; retaining it is not - copy anything you need to keep. `map.isActive(action)` polls the level instead. It reads false for an unlinked map and for a suppressed one. A sequence has no meaningful level - its trigger is true for a single evaluation point - so bind a listener rather than polling one. ### Device adapters An adapter presents a concrete device to the binding layer as switches and coordinates. The contract that matters is **totality**: an adapter answers for every code it declares whether or not hardware is present, and absent hardware reads as up and as zero - never undefined, never a throw. That is what lets a gamepad binding resolve on a machine with no gamepad. | Adapter | Device id | Notes | |---|---|---| | `KeyboardInputDeviceAdapter(keyboard)` | `"keyboard"` | Codes are `KeyCodes`. | | `PointerInputDeviceAdapter(pointer)` | `"pointer"` | Buttons are `MouseButtons` (`MouseEvent.button` ordinals). Gestures are deliberately absent. | | `GamepadInputDeviceAdapter(gamepad)` | `"gamepad"` | Presents `gamepad.main`. Codes are `GamepadButtons`. | | `ManualInputDeviceAdapter(id, device)` | your choice | Wraps a `ManualInputDevice`. | | `InputDeviceAdapter` | - | Base class. | The id constants are exported as `KEYBOARD_INPUT_DEVICE_ID`, `POINTER_INPUT_DEVICE_ID` and `GAMEPAD_INPUT_DEVICE_ID` from the same directory. `system.registerDevice(adapter)` may be called after maps are linked; every linked map is recompiled, so bindings on a device that was missing become live. `ManualInputDeviceAdapter` takes its id as a constructor argument, which is the point: two manual devices registered as `"keyboard"` and `"gamepad"` let a cross-device chord be driven, recorded or replayed with no hardware and no DOM. ```js import { ManualInputDevice } from "@woosh/meep-engine/src/engine/input/devices/ManualInputDevice.js"; import { ManualInputDeviceAdapter } from "@woosh/meep-engine/src/engine/input/ecs/ism/device/ManualInputDeviceAdapter.js"; import { KEYBOARD_INPUT_DEVICE_ID } from "@woosh/meep-engine/src/engine/input/ecs/ism/device/KEYBOARD_INPUT_DEVICE_ID.js"; const device = new ManualInputDevice(); const adapter = new ManualInputDeviceAdapter(KEYBOARD_INPUT_DEVICE_ID, device); ``` One keyboard-specific consequence worth knowing: `KeyboardDevice` suppresses a browser default only for a key whose `down` signal has handlers, so browser suppression follows the bound key set automatically. It is per **key**, not per chord - binding only `Ctrl`+`S` also suppresses a bare `S`. ## `InputController` - pointer gestures `InputController` connects binding-path strings to callback functions. When the component links, the system wires each binding to the corresponding signal; when it unlinks, the wiring is removed. It is not deprecated, and it is the right tool for exactly one thing: pointer gestures. A tap is not a button press - it fires on **release**, and only if the pointer moved under 10 px and was held under a second - and `drag`, `dragStart`, `dragEnd`, `move` and `pinch` are the same kind of stateful construction. The binding layer models buttons, not gestures. Keyboard keys and pointer buttons belong in an `InputMap`. ```js import InputController from "@woosh/meep-engine/src/engine/input/ecs/components/InputController.js"; import InputControllerSystem from "@woosh/meep-engine/src/engine/input/ecs/systems/InputControllerSystem.js"; // Register the system once (it needs access to engine.devices). await em.addSystem(new InputControllerSystem(engine.devices)); const ic = new InputController(); ic.bind("pointer/on/tap", (position) => selectAt(position)); ic.bind("pointer/on/drag", (position, origin, lastPosition) => panBy(position, lastPosition)); new Entity().add(ic).build(ecd); ``` Both are default exports. Bindings can also be supplied at construction time: ```js const ic = new InputController([ { path: "pointer/on/dragStart", listener: (origin) => beginBoxSelect(origin) }, { path: "pointer/on/dragEnd", listener: (position) => endBoxSelect(position) }, ]); ``` `ic.bind(path, listener)` returns the `InputBinding` so it can be referenced later. ### Binding-path syntax A path is a `/`-delimited property walk from `engine.devices` to the `Signal` to subscribe to. The system calls `signal.add(listener)` when the component links and `signal.remove(listener)` when it unlinks. ``` pointer/on/tap pointer/on/drag pointer/on/dragStart pointer/on/dragEnd pointer/on/move pointer/on/wheel pointer/on/pinch pointer/on/pinchStart pointer/on/pinchEnd pointer/on/down pointer/on/up pointer/on/globalUp ``` Paths to keyboard and gamepad signals (`keyboard/keys//down`, `gamepad/main/buttons//down`, and so on) resolve, but prefer an `InputMap` for those: a string path is resolved with `resolvePath`, which *throws* when it cannot be resolved, and a path names exactly one signal, so no combination of inputs is expressible. ### Cleanup on unlink `InputController` exposes an `on.unlinked` signal that fires when the entity is destroyed (or the component is removed). Use it to zero out any state the bindings accumulated: ```js ic.on.unlinked.add(() => { intent.move.set(0, 0); dragging = false; }); ``` `InputControllerSystem` also carries an `enabled` `ObservedValue`; setting it `false` holds every binding out of the device signals without unlinking any component. It is one of only two systems in the engine that define `enabled` - it is not part of the `System` contract. ## Devices ### `KeyboardDevice` `engine.devices.keyboard` listens for native DOM key events on the view stack's element (`engine.viewStack.el`), which carries `tabindex` because only a focused element receives keyboard events. `Engine` focuses it when the view stack links, and again on any `pointerdown` inside it that did not land on a focusable control of your own - an input, a button, a link - so clicking a DOM overlay and clicking back restores the keyboard. When the window loses focus, every held key is forcibly released with its `up`, because no release can be observed after that; focus moving to another element inside the page leaves held keys down, and their release is picked up at the window. Key-repeat events are not new presses: `on.down` skips them and a key already down ignores them, so each press fires one `down` and one `up`. A repeat does press a key that is held but not down - one a window blur released, or whose key-down went to another element - so a key held through a focus change comes back with its next repeat. Two access patterns are available: - **Per-key signals** - `keyboard.keys..down` and `keyboard.keys..up` are `Signal` instances that fire when the key transitions. `keyboard.keys..is_down` is a live boolean. Key names match `KeyCodes` (lowercase, underscored): `w`, `space`, `shift`, `ctrl`, `up_arrow`, `f1`, `numpad_0`, etc. - **Any-key signals** - `keyboard.on.down` and `keyboard.on.up` fire for every key transition and receive the raw `KeyboardEvent`. Every member of `KeyCodes` is materialized as a switch in the constructor, so every key resolves before anything is pressed. ### `PointerDevice` `engine.devices.pointer` unifies mouse and touch into one interface. It listens for **Pointer** events (`pointerdown`, `pointermove`) on the view stack's element, not `mousedown`/`mousemove` - a synthesized `MouseEvent` reports nothing; pointer-up is also captured on `window` so drag releases register even if the cursor leaves the element. The engine's view-stack root uses `pointer-events: none` so DOM UI can overlay the game. The render viewport opts back in with `auto`; `GraphicsEngine.adopt_canvas` preserves that inline setting when the renderer mounts a canvas, including on restart. Events on the canvas bubble to the view-stack listener. Custom overlays still need appropriate pointer-event styling so they do not intercept game input. `PointerDevice` exposes: | Signal | Arguments | When | |---|---|---| | `on.down` | `(position: Vector2, event: PointerEvent)` | pointer pressed | | `on.up` | `(position: Vector2, event: PointerEvent)` | pointer released over the element | | `on.globalUp` | `(position: Vector2, event)` | a release anywhere on the page. `on.up` only fires for a release over the element, so a gesture that began on it and ended off it is never closed by that one | | `on.move` | `(position: Vector2, event: PointerEvent, delta: Vector2)` | pointer moved. `delta` is the pointer-lock movement, from `movementX`/`movementY` - what a first-person camera reads | | `on.tap` | `(position: Vector2, event: PointerEvent)` | short press, no significant movement | | `on.dragStart` | `(origin: Vector2, event: PointerEvent)` | drag begins | | `on.drag` | `(position, origin, lastPosition, event)` | drag in progress | | `on.dragEnd` | `(position: Vector2)` | drag released | | `on.wheel` | `(delta: Vector3, position: Vector2, event: WheelEvent)` | scroll; delta components are ±1 (sign only, normalized across browsers) | | `on.pinchStart` | `(extents: Vector2)` | a second touch lands; `extents` is the mean half-size of the touch box | | `on.pinch` | `(extents: Vector2, startExtents: Vector2)` | pinch in progress; compare the two for a scale factor | | `on.pinchEnd` | - | fewer than two touches remain | `pointer.position` is the current pointer position as a live `Vector2`. The `buttons` array (32 slots) holds one `InputDeviceSwitch` per mouse button, indexed by `MouseEvent.button` ordinals - the same order `MouseButtons` names: `left` is 0, `middle` is 1, `right` is 2, then `back` and `forward`. Convenience accessors `mouseButtonLeft`, `mouseButtonMiddle`, and `mouseButtonRight` alias the same switches. ### `GamepadDevice` `engine.devices.gamepad` sits on top of the browser's Gamepad API. That API is poll-only - it fires no events for button or axis changes - so the device polls once per animation frame while running and turns the snapshots into the same signal-and-switch surface the other devices expose. `poll()` can also be called by hand from a fixed-rate loop. On disconnect every held button is released with its normal signals, so nothing gets stuck. The device reports what the hardware reports, corrected for what the hardware gets wrong. Dead zones, response curves, and which world direction a stick means are game policy and stay in your code. - `pads` - known pads indexed by `Gamepad.index`, possibly sparse. Handles are retained across disconnects and reused on reconnect, so they're safe to hold. - `main` - the active pad, for the common single-player case. It always exists (check `main.connected` for hardware), binds to the first pad that connects, and rebinds to the oldest still-connected pad when that one is lost. It's a separate handle fed from the same snapshot, which makes it a stable binding target: `InputTriggerGamepadButton` and `InputCoordinateDevice.fromGamepad` both go through it, so a gamepad binding resolves before any hardware exists and never goes stale. - `on.connected` / `on.disconnected` - `(pad)`. `on.down` / `on.up` - `(buttonIndex, pad)`. `on.axis` - `(axisIndex, value, pad)`. Each `GamepadHandle` carries `buttons` (an `InputDeviceSwitch` per index - every slot of the standard mapping is materialized up front, so reads need no guard), `buttonValues` (analog `[0,1]`, for triggers), `axes` (raw, `[-1,1]`, indexed by `GamepadAxes`), and `stickLeft` / `stickRight`. A `GamepadStick` exposes `raw` and `value`. Read `value`: it is `raw` with the stick's *learned* rest position removed, reading exactly neutral inside the learned noise radius - a real fix for drifting sticks that a fixed per-axis gate guesses at. Calibration describes one physical stick, so it is dropped when `main` moves to a different pad. `value` is otherwise unshaped - no dead zone, no curve. Shape it at the call site with `apply_radial_dead_zone`, whose circular boundary is isotropic (a per-axis gate lets through up to `inner * sqrt(2)` on the diagonal) and which rescales the remainder over the full `[0,1]` range, so speed ramps from zero instead of popping as the stick leaves the dead zone: ```js import { apply_radial_dead_zone } from "@woosh/meep-engine/src/engine/input/analog/apply_radial_dead_zone.js"; import { gamepad_write_dpad_vector } from "@woosh/meep-engine/src/engine/input/devices/gamepad/gamepad_write_dpad_vector.js"; import { GamepadButtons } from "@woosh/meep-engine/src/engine/input/devices/gamepad/GamepadButtons.js"; import Vector2 from "@woosh/meep-engine/src/core/geom/Vector2.js"; const stick = new Vector2(); const dpad = new Vector2(); const pad = engine.devices.gamepad.main; if (pad.connected) { const jump = pad.buttons[GamepadButtons.a].is_down; apply_radial_dead_zone(stick, pad.stickLeft.value.x, pad.stickLeft.value.y, 0.15, 0.95); gamepad_write_dpad_vector(dpad, pad); // digital view of the D-pad } ``` An `InputMap` does the stick-or-D-pad fusion for you - bind both as channels on one coordinate action and the priority rule picks - but the dead zone stays yours either way. `GamepadButtons` names the standard-mapping indices after the Xbox layout (`a` = bottom, `b` = right, `x` = left, `y` = top, plus bumpers, triggers, `back` / `start` / `home`, stick clicks, and the four `dpad_*` entries). ### `InputDeviceSwitch` Each pressable control - a keyboard key, a mouse button, a gamepad button - is represented by an `InputDeviceSwitch`: ```js const sw = engine.devices.keyboard.keys.space; sw.is_down // boolean: currently held? sw.is_up // boolean: inverse of is_down sw.down // Signal - fires on press sw.up // Signal - fires on release ``` ## Locational interaction Every pointer signal carries a `Vector2` position as its first argument, and `PointerCoordinates.position` reports the same thing as a channel. The position is in canvas-local pixel coordinates - relative to the element's bounding rect, matching the device's `position` property. For world interaction (hit-testing, picking), convert the position to clip space and project a ray: ```js engine.devices.pointer.on.down.add((position) => { engine.graphics.normalizeViewportPoint(position, ndc); engine.graphics.viewportProjectionRay(ndc.x, ndc.y, raySource, rayDir); // ... raycast into the physics world, or hand the ray to PickingSystem }); ``` `normalizeViewportPoint` writes −1…1 with +Y up; `viewportProjectionRay` writes a world-space origin and a unit direction. For drag, `pointer.position` provides the live position between events. The `tap` signal fires only when pointer travel between down and up is below 10 pixels and elapsed time is below 1 second, making it a reliable click/tap detector across mouse and touch. ## Programmatic cursor control Meep doesn't provide an abstraction for cursor type - set it directly on the canvas element from the game loop or from pointer event handlers: ```js const canvas = engine.graphics.domElement; canvas.style.cursor = "grab"; // during hover canvas.style.cursor = "grabbing"; // during drag canvas.style.cursor = ""; // default ``` For pointer lock (mouse-look), call the browser API on the canvas element: ```js canvas.requestPointerLock(); // capture - hides cursor, provides raw deltas document.exitPointerLock(); // release ``` Check `document.pointerLockElement === canvas` before consuming look deltas, whether you read them from `pointer/on/move` or from the `move` coordinate channel. ## WebXR input `engine.devices.xr` is an `XRInputDevice`. The application owns the WebXR session, reference space and frame loop; Meep reads their input without creating a session or an XR renderer. Controls remain neutral until a session is attached. ```js const xr = engine.devices.xr; xr.right.select.completed.add(() => useTool()); xr.setSession(session, referenceSpace); // In the application's existing XR requestAnimationFrame callback: // xr.poll(frame); // before reading controls and poses ``` The `left`, `right` and `none` slots keep stable control objects across source changes; `xr.sources` exposes a handle for each live source. Session end, disconnection, blur, hidden visibility and `stop()` clear controls and cancel unfinished actions. Tracking loss invalidates poses without clearing controls. Register an adapter per handedness slot to use `InputMap` bindings: ```js import { XRInputDeviceAdapter } from "@woosh/meep-engine/src/engine/input/ecs/ism/device/XRInputDeviceAdapter.js"; import { InputTriggerXRButton } from "@woosh/meep-engine/src/engine/input/ecs/ism/trigger/InputTriggerXRButton.js"; import { InputCoordinateDevice } from "@woosh/meep-engine/src/engine/input/ecs/ism/coordinate/InputCoordinateDevice.js"; import { XRInputCoordinates } from "@woosh/meep-engine/src/engine/input/devices/xr/XRInputCoordinates.js"; await em.addSystem(new InputMapSystem([ new XRInputDeviceAdapter(engine.devices.xr, "right"), ])); const xrMap = new InputMap(); xrMap.bind("fire", InputTriggerXRButton.from("right", 0)); xrMap.bindCoordinate("pressure", InputCoordinateDevice.fromXR("right", XRInputCoordinates.select)); new Entity().add(xrMap).build(ecd); ``` `InputTriggerXRButton.from(handedness, index, touched?)` reads a native gamepad button's pressed switch, or its touched switch when the third argument is `true`. Semantic select/squeeze completion is separate: subscribe to `.completed` on the slot's action, or bind an `InputController` path such as `xr/right/select/completed`. ## Deprecated: `Input`, `InputSystem`, `InputBinding` `Input` (`.../input/ecs/components/Input.js`) binds a device signal *path* to an entity event name, and `InputSystem` (`.../input/ecs/systems/InputSystem.js`) drives it. Both are marked `@deprecated` in favour of `InputMap` and `InputMapSystem`; they export and work, because an unreferenced export is still public surface. `InputBinding` at `.../input/ecs/ism/InputBinding.js` is `Input`'s record type and is deprecated with it - the binding layer's own record type is `.../ism/map/InputBinding.js`. Two defects, beyond the string paths themselves, are why the binding layer is the one to use: - A path is resolved with `resolvePath`, which **throws** when it cannot be resolved - so a gamepad binding cannot link until the player has plugged in and pressed something. An adapter's totality rule fixes exactly this. - A binding names exactly one signal, so no combination of inputs is expressible. Chords, sequences, holds and releases have nowhere to live. ## Related - [First-person controller](https://meep.company-named.com/docs/first-person/) - the intent surface that input bindings write. - [Control contexts](https://meep.company-named.com/docs/gameplay/control-contexts/) - state-machine wrappers that group input entities and activate/deactivate them together. - [Picking](https://meep.company-named.com/docs/rendering/picking/) - async, batched world picks from a ray. --- # Control contexts Section: Gameplay Source: https://meep.company-named.com/docs/gameplay/control-contexts/ Description: State-machine wrappers that group ECS entities under a named state and activate or deactivate them as one unit when the state is entered or left. A `ControlContext` groups the entities that belong to one logical mode - on-foot, in-vehicle, in-menu, cutscene - and activates or deactivates those entities atomically when the game transitions between modes. A `StatefulController` ties one or more contexts to a `SimpleStateMachine` so that entering a state starts its context and leaving it shuts it down. ## The problem Input bindings, cameras, UI overlays, and other mode-specific entities are easy to build but awkward to manage. Without a coordination layer you end up with ad-hoc flags, mixed teardown code, and entities that forget to unlink when the player climbs into a vehicle. `ControlContext` formalizes the lifecycle so activation and deactivation happen as one step via the state machine. ## `ControlContext` `ControlContext` is a base class. Subclass it and set up your entities in `initialize`: ```js import { ControlContext } from "@woosh/meep-engine/src/engine/control/ControlContext.js"; import { InputMap } from "@woosh/meep-engine/src/engine/input/ecs/ism/map/InputMap.js"; import { InputTriggerKey } from "@woosh/meep-engine/src/engine/input/ecs/ism/trigger/InputTriggerKey.js"; class OnFootContext extends ControlContext { initialize(ecd) { super.initialize(ecd); const map = new InputMap(); map.bind("jump", InputTriggerKey.from("space")); // ... the rest of the on-foot bindings ... // makeEntity() registers the entity with the context. // It will be built on startup() and destroyed on shutdown(). this.makeEntity() .add(map) .add(SerializationMetadata.Transient); } } ``` The lifecycle is: | Method | Trigger | What it does | |---|---|---| | `initialize(ecd)` | Called once before first use | Creates entity builders via `makeEntity()`; transitions state to `Ready` | | `startup()` | Called when its state is entered | Calls `.build(ecd)` on every registered entity; transitions to `Running` | | `shutdown()` | Called when its state is left | Calls `.destroy()` on every built entity; transitions back to `Ready` | | `dispose()` | Called when the context is no longer needed | Cleans up; transitions to `Disposed` | States are `Initial → Ready → Running → Ready → Disposed`. Calling `startup()` or `shutdown()` twice is safe (idempotent). The `transientEntities` flag (default `true`) marks every managed entity as `SerializationMetadata.Transient` automatically. ```pintora dotDiagram digraph { Initial -> Ready [label="initialize(ecd)"] Ready -> Running [label="startup()"] Running -> Ready [label="shutdown()"] Ready -> Disposed [label="dispose()"] } ``` ## `ControlContextState` The four states are integers from the `ControlContextState` enum: ```js import { ControlContextState } from "@woosh/meep-engine/src/engine/control/ControlContextState.js"; // ControlContextState.Initial = 0 // ControlContextState.Ready = 1 // ControlContextState.Running = 2 // ControlContextState.Disposed = 3 ``` Read the current state with `context.getState()`. ## `StatefulController` `StatefulController` binds contexts to a `SimpleStateMachine` so that state transitions wire context activation automatically. ```js import { StatefulController } from "@woosh/meep-engine/src/engine/control/StatefulController.js"; import { SimpleStateMachine } from "@woosh/meep-engine/src/core/fsm/simple/SimpleStateMachine.js"; import { SimpleStateMachineDescription } from "@woosh/meep-engine/src/core/fsm/simple/SimpleStateMachineDescription.js"; const desc = new SimpleStateMachineDescription(); const STATE_ON_FOOT = desc.createState(); const STATE_VEHICLE = desc.createState(); desc.createEdge(STATE_ON_FOOT, STATE_VEHICLE); desc.createEdge(STATE_VEHICLE, STATE_ON_FOOT); const sm = new SimpleStateMachine(desc); const controller = new StatefulController(sm); const onFootCtx = new OnFootContext(); const vehicleCtx = new VehicleContext(); // Initialize before binding so makeEntity() has ecd access. onFootCtx.initialize(ecd); vehicleCtx.initialize(ecd); // Register: entering STATE_ON_FOOT calls onFootCtx.startup(), // leaving it calls onFootCtx.shutdown(). controller.addContext(STATE_ON_FOOT, onFootCtx); controller.addContext(STATE_VEHICLE, vehicleCtx); // Drive the machine. sm.setState(STATE_ON_FOOT); // starts on-foot context sm.setState(STATE_VEHICLE); // shuts down on-foot, starts vehicle context ``` `removeContext` reverses the binding if a context needs to be detached at runtime. ## `SimpleStateMachine` and `SimpleStateMachineDescription` The underlying state machine is generic and not specific to control. Its description defines the graph; the machine traverses it. ```js const desc = new SimpleStateMachineDescription(); // States are plain non-negative integers allocated by the description. const stateA = desc.createState(); // returns e.g. 0 const stateB = desc.createState(); // returns e.g. 1 // Edges define legal transitions. desc.createEdge(stateA, stateB); desc.createEdge(stateB, stateA); // Optionally assign a selector function that picks the next state given input. desc.setAction(stateA, (input) => input.wantsVehicle ? stateB : stateA); const sm = new SimpleStateMachine(desc); // Explicit transition. sm.setState(stateB); // Advance - calls the selector for the current state and transitions. sm.advance(myInput); // Shortest-path navigation (BFS over the edge graph). sm.navigateTo(stateB); ``` Entry and exit handlers can be registered directly on the machine without going through `StatefulController`: ```js sm.addEventHandlerStateEntry(stateA, () => console.log("entered A")); sm.addEventHandlerStateExit(stateA, () => console.log("left A")); ``` ## Relationship to input bindings A control context is the clean way to manage the lifetime of an input entity. Both binding components go live on link and stop on unlink, so a context that owns the entity needs no enable/disable bookkeeping of its own: create the entity inside `initialize` with `makeEntity()`, and the context builds it on `startup()` and destroys it on `shutdown()`. Bindings activate and deactivate exactly when the state changes. Which component goes on the entity depends on what the mode binds: - **`InputMap`** for keyboard keys, pointer buttons and gamepad buttons, and for anything needing a chord, a sequence, a hold or an analog channel. A context's map can also set `order` and `occlusion` so an in-menu context takes keys away from the on-foot context underneath rather than racing it. - **`InputController`** for pointer *gestures* - `tap`, `drag`, `dragStart`, `dragEnd`, `move`, `pinch`. It is **not** deprecated, and it is the only way to bind those: `PointerDevice` synthesizes them on top of its buttons and the binding layer does not model them. A context that needs both puts both components on the entity. The `transientEntities` default is worth keeping on for input entities. A map built by a controller rather than authored into a scene should not end up in a save file; `makeEntity()` marks it `SerializationMetadata.Transient` for you. See [Input devices](https://meep.company-named.com/docs/gameplay/input-devices/) for both APIs. --- # AI & simulation tools Section: AI Source: https://meep.company-named.com/docs/ai-and-simulation/ Description: Behavior trees, finite state machines, Monte-Carlo Tree Search, a resource-allocation planner, blackboards, and navmesh pathfinding - decision-making and planning primitives most JavaScript engines don't ship. Most web engines stop at rendering and physics and leave agent logic to you. Meep ships the decision-making layer too: a full behavior-tree toolkit, finite state machines, a Monte-Carlo Tree Search planner, a resource-allocation solver, blackboards for shared state, a couple of optimizers, and navmesh pathfinding. These are the same primitives you'd reach for in a native engine, written in plain JavaScript and wired through the ECS. Almost everything below lives under `@woosh/meep-engine/src/engine/intelligence/`, with one self-contained subdirectory per subsystem and its own tests. Pick the tool that fits the problem - reactive moment-to-moment AI wants a behavior tree or a state machine; turn-based or adversarial planning wants MCTS; budgeting limited resources across competing actions wants the allocation solver. ## Behavior trees A behavior tree is a hierarchy of nodes that runs top-down each tick. Every node's `tick(dt)` returns a **status**, and parent nodes route control based on what their children return. The base type is `Behavior`; the status values are: | Status | Meaning | |---|---| | `Running` | still working - tick me again next frame | | `Succeeded` | finished, success | | `Failed` | finished, failure | | `Initial` / `Suspended` / `Invalid` | lifecycle states, set by the framework | A tree has three lifecycle calls. `initialize(context)` runs once and recursively seeds every node with a shared **context** object (commonly a [blackboard](#blackboards)). `tick(dt)` advances the tree and returns a status. `finalize()` cleans up when the tree completes or is interrupted. Trees are stateful - a sequence remembers which child it's on, a delay remembers how long it's waited - so a tree resumed next frame picks up exactly where it left off. ### The node catalog **Composites** run multiple children. Each has a `.from([...])` factory: | Node | Logic | |---|---| | `SequenceBehavior` | AND - run children in order; fail fast, succeed only if all succeed | | `SelectorBehavior` | OR (fallback) - try children in order; succeed on the first success | | `ParallelBehavior` | run all children together; `RequireOne` or `RequireAll` success/failure policies | **Decorators** wrap a single child and transform its result: | Node | Effect | |---|---| | `InvertStatusBehavior` | swap Succeeded ↔ Failed | | `RepeatBehavior` | loop the child N times (default forever) | | `RepeatUntilSuccessBehavior` | retry the child until it succeeds (optional attempt cap) | | `IgnoreFailureBehavior` | turn Failure into Success | | `OverrideContextBehavior` | run the child against a different context object | **Leaves** do the actual work: | Node | Purpose | |---|---| | `ActionBehavior` | run a synchronous function `(dt, context) => …`; succeeds (fails if it throws) | | `ConditionBehavior` | test a predicate; Succeeded if true, Failed if false | | `PromiseBehavior` | wrap a promise - Running until it settles, then Succeeded / Failed | | `DelayBehavior` / `RandomDelayBehavior` | wait a fixed or random number of seconds | | `SucceedingBehavior` / `FailingBehavior` | constant results | | `BranchBehavior` | if/else - run a condition, then one of two branches | | `ConditionalBehavior` / `FilterBehavior` | gate an action (or a set of actions) behind condition(s) | | `LogMessageBehavior` | print a message (debugging) | ### A worked example ```js import { SelectorBehavior } from "@woosh/meep-engine/src/engine/intelligence/behavior/SelectorBehavior.js"; import { SequenceBehavior } from "@woosh/meep-engine/src/engine/intelligence/behavior/composite/SequenceBehavior.js"; import { ActionBehavior } from "@woosh/meep-engine/src/engine/intelligence/behavior/primitive/ActionBehavior.js"; import { ConditionBehavior } from "@woosh/meep-engine/src/engine/intelligence/behavior/util/ConditionBehavior.js"; import { DelayBehavior } from "@woosh/meep-engine/src/engine/intelligence/behavior/util/DelayBehavior.js"; import { BehaviorStatus } from "@woosh/meep-engine/src/engine/intelligence/behavior/BehaviorStatus.js"; const guard = { player_visible: false /* …shared state… */ }; // Chase if the player is visible; otherwise patrol with a pause between waypoints. const tree = SelectorBehavior.from([ SequenceBehavior.from([ new ConditionBehavior(() => guard.player_visible), ActionBehavior.from(() => chasePlayer(guard)), ]), SequenceBehavior.from([ ActionBehavior.from(() => moveToNextWaypoint(guard)), DelayBehavior.from(2.0), ]), ]); tree.initialize(guard); // recursively seeds the context // each frame: const status = tree.tick(dt); // Running | Succeeded | Failed if (status !== BehaviorStatus.Running) tree.finalize(); ``` ```pintora dotDiagram digraph { sel [label="Selector (fallback)"] chase [label="Sequence: chase"] patrol [label="Sequence: patrol"] cond [label="Condition: player_visible"] act1 [label="Action: chasePlayer"] act2 [label="Action: moveToNextWaypoint"] wait [label="Delay: 2.0s"] sel -> chase sel -> patrol chase -> cond chase -> act1 patrol -> act2 patrol -> wait } ``` The selector tries the chase branch first; its condition fails while the player is hidden, so control falls through to the patrol branch. The moment `player_visible` flips true, the next tick takes the chase branch instead - that re-evaluation every tick is what makes a behavior tree *reactive* rather than a fixed script. ### Running trees on entities `BehaviorComponent` attaches a tree to an entity, and `BehaviorSystem` ticks every such component each frame: ```js import { BehaviorComponent } from "@woosh/meep-engine/src/engine/intelligence/behavior/ecs/BehaviorComponent.js"; import { BehaviorSystem } from "@woosh/meep-engine/src/engine/intelligence/behavior/ecs/BehaviorSystem.js"; await entityManager.addSystem(new BehaviorSystem(engine)); new Entity() .add(BehaviorComponent.from(tree)) .add(transform) .build(ecd); ``` `BehaviorComponent.from(tree)` wraps an existing tree; `BehaviorComponent.loop(fn)` is shorthand for "run this function every tick, forever". Components tick on the simulation clock by default (`ClockChannelType.Simulation`), so tree timing is deterministic and pause-aware; switch to `System` time for UI-driven logic. A set of **entity behaviors** lets a tree act on the world directly: `SendEventBehavior` and `WaitForEventBehavior` (fire and await entity events - the basis for cross-agent coordination), `DieBehavior` and `KillBehavior` (destroy self or another entity), and `OrbitingBehavior` / `RotationBehavior` (drive simple motion). Because event behaviors can suspend a branch until a signal arrives, multi-agent choreography - "wait for the door to open, then advance" - is just a sequence. ### Weighted choice, serialization, and debugging `WeightedRandomBehavior` (with `WeightedElement`) picks one child at random by weight and runs it to completion - variety without hand-authored randomness. Every stateful node has a serialization adapter, and `BehaviorComponent` saves the **in-flight** tree - mid-delay, mid-sequence, pending promises and all - so a save made while an agent is halfway through an action restores to exactly that point. `behavior_to_dot()` renders a tree to GraphViz DOT for inspection, and `syncExecuteBehaviorToCompletion()` ticks a tree to completion in a loop for tests. ## Blackboards A `Blackboard` is a typed key-value store for the state a tree (or several agents) shares. Values are *observed* - reading and writing goes through small wrappers that emit change events, so other systems can react without polling: ```js import { Blackboard } from "@woosh/meep-engine/src/engine/intelligence/blackboard/Blackboard.js"; const bb = new Blackboard(); const health = bb.acquireNumber("health", 100); // observed number bb.acquireBoolean("alerted", false); health.set(80); // observable write bb.on.added.add((name, value) => console.log(`+${name}`)); ``` `acquireNumber` / `acquireBoolean` / `acquireString` create or fetch a typed slot; `contains`, `getKeys`, and `traverse` introspect it. A `Blackboard` is the natural `context` to hand a behavior tree - every node then reads and writes the same shared state. `BlackboardStack` cascades several blackboards into a scope chain (look-ups fall through from the top down, writes land in a designated slot), which is how you give an agent both shared squad state and private per-agent state without copying. ## Finite state machines When behavior is better described as discrete *modes* with explicit transitions between them - idle, chase, attack - a state machine is clearer than a tree. You declare the graph once, attach a transition function per state, then feed it input: ```js import { SimpleStateMachineDescription } from "@woosh/meep-engine/src/core/fsm/simple/SimpleStateMachineDescription.js"; import { SimpleStateMachine } from "@woosh/meep-engine/src/core/fsm/simple/SimpleStateMachine.js"; const d = new SimpleStateMachineDescription(); const IDLE = d.createState(), CHASE = d.createState(), ATTACK = d.createState(); d.createEdge(IDLE, CHASE); d.createEdge(CHASE, ATTACK); d.createEdge(CHASE, IDLE); d.createEdge(ATTACK, CHASE); // each state maps the current input to the next state id d.setAction(IDLE, (i) => i.sees_player ? CHASE : IDLE); d.setAction(CHASE, (i) => i.in_range ? ATTACK : (i.sees_player ? CHASE : IDLE)); d.setAction(ATTACK, (i) => i.in_range ? ATTACK : CHASE); const fsm = new SimpleStateMachine(d); fsm.setState(IDLE); fsm.addEventHandlerStateEntry(ATTACK, () => startAttackAnimation()); fsm.advance({ sees_player, in_range }); // each frame - fires entry/exit hooks on change ``` States and edges are plain integer ids; `advance(input)` runs the current state's action and transitions if it returns a different state, firing the state's exit hook and the new state's entry hook. `findPath` and `navigateTo` route the machine through intermediate states when you want to reach a target without enumerating every transition. For ECS use, `StateGraph` wraps a machine and `StateGraphSystem` drives it per entity. ## Monte-Carlo Tree Search For turn-based and adversarial decisions - board games, card games, tactical planning - `MonteCarloTreeSearch` finds strong moves by simulating thousands of random playouts and concentrating its search where the rewards are. It's the AlphaGo family of algorithm, and it's domain-agnostic: you describe your game through six callbacks and the search does the rest. ```js import { MonteCarloTreeSearch } from "@woosh/meep-engine/src/engine/intelligence/mcts/MonteCarlo.js"; import { MoveEdge } from "@woosh/meep-engine/src/engine/intelligence/mcts/MoveEdge.js"; import { StateType } from "@woosh/meep-engine/src/engine/intelligence/mcts/StateNode.js"; const search = new MonteCarloTreeSearch(); search.initialize({ rootState: position, numPlayers: 2, cloneState: (s) => s.clone(), // MUST return a fresh copy computeActivePlayer: (s) => s.turn, // whose move it is (0-based) computeTerminalFlag: (s) => s.isOver() ? StateType.Terminal : StateType.Undecided, computeOutcome: (s) => s.payoffs(), // Float64Array, one entry per player computeValidMoves: (s) => s.legalMoves().map( (m) => MoveEdge.fromFunction((state) => m.applyTo(state)), ), }); for (let i = 0; i < 5000; i++) search.playout(); // selection → expansion → rollout → backup const best = search.root.pickBestMoves(); // best move(s) for the active player ``` Each `playout()` walks the tree by UCB1 (balancing exploitation of good moves against exploration of untried ones), expands a new node, rolls out to a terminal state, and backs the result up the path it took. Outcomes are **per-player payoff vectors**, so the same engine handles zero-sum duels, n-player free-for-alls, and cooperative or asymmetric games - you decide the shape of the reward. The only hard rule is that `cloneState` returns a genuinely independent copy, since every playout mutates its own branch. Playouts run on a seeded RNG, so a given search is reproducible. ## Resource-allocation planner A recurring strategic problem: many possible actions compete for a limited pool of resources - action points, ammo, mana, currency, time - and you want the combination that maximises value without overspending. The `resource/` solver models this directly. You describe each candidate action as a **bid**: the resources it needs, a normalized value in `[0, 1]`, and the action(s) to run if it wins. The solver takes the available resources and the bids and greedily allocates by `value × weight`, committing each bid all-or-nothing if its resources are still available. ```js import { Resource } from "@woosh/meep-engine/src/engine/intelligence/resource/Resource.js"; import { ResourceAllocation } from "@woosh/meep-engine/src/engine/intelligence/resource/ResourceAllocation.js"; import { ResourceAllocationBid } from "@woosh/meep-engine/src/engine/intelligence/resource/ResourceAllocationBid.js"; import { ResourceAllocationSolver } from "@woosh/meep-engine/src/engine/intelligence/resource/ResourceAllocationSolver.js"; const fireball = new ResourceAllocationBid( new ResourceAllocation([new Resource(3, "ap"), new Resource(30, "mana")]), 0.9, // value ); fireball.actions.add("CAST_FIREBALL"); const solver = new ResourceAllocationSolver(); solver.addResources([new Resource(10, "ap"), new Resource(50, "mana")]); solver.addBids([fireball /* , … */]); const winners = solver.solve(); // the bids that fit, highest value first ``` For larger AI, `TacticalModule`s generate bids from the current situation (`collectBids(resources)`), and a `StrategicResourceAllocator` runs every module, pools their bids, solves, sorts the resulting actions by priority, and applies any post-processing transformers - turning "what does each part of my AI want, and what can I afford?" into a single ordered plan. ## Optimization `optimization/` holds two general-purpose optimizers. `RandomOptimizer` is a hill climber: give it a state, a `cloneState`, a `scoreFunction`, and either a list of valid moves or a `randomAction`, then call `step()` (apply a random move, keep it if the score improved) or `stepThrough(n)`. `OptimizationTask` wraps it for the engine's async task system, stopping after a number of no-improvement steps or a time limit. `optimize_cyclic_sequence_pairwise` does pairwise local search over a cyclic sequence (its original use was scheduling sample jitter). They're handy for procedural placement, scheduling, and any "good enough, fast" combinatorial tuning. ## Moving agents through the world Once an agent has *decided* where to go, navigation gets it there. `NavigationMesh` bakes a walkable mesh from scene geometry - parameterised by agent radius, height, and maximum climb angle - and accelerates queries with a BVH: ```js const out = new Float32Array(256 * 3); const count = navmesh.find_path(out, sx, sy, sz, gx, gy, gz); // packed XYZ triples ``` `find_path` snaps the endpoints onto the mesh, then runs Polyanya to get the exact any-angle geodesic across the surface - turning only at obstacle corners, and subdivided at every face boundary it crosses so no segment leaves its triangle. It returns the number of points written. To make an entity follow a path, add a `Path` (the waypoints, linearly or Catmull-Rom interpolated) and a `PathFollower` (speed, rotation, looping) component; `PathFollowingSystem` advances the entity along it and fires an event when it arrives. For grid-based worlds, `find_path_on_grid_astar` is a direct A* over a 2D field. (The navmesh also appears under the engine's [navigation features](https://meep.company-named.com/features/#physics-nav) - this section is the AI-agent view of it.) ## Determinism and persistence Two properties run through all of these. **Determinism**: behavior trees tick on the simulation clock, FSM transitions are pure functions of input, and MCTS playouts use a seeded RNG - so the same inputs produce the same decisions across runs and across V8 builds, the foundation the engine's [determinism guarantees](https://meep.company-named.com/docs/physics/determinism/) extend to AI for lockstep netcode and replays. **Persistence**: behavior trees and their in-flight state serialize through the same binary save system as everything else, so an agent mid-decision survives a save/load without losing its place. --- # Animation graphs Section: Animation Source: https://meep.company-named.com/docs/animation/graphs/ Description: How meep drives skeletal animation through state machines, cross-faded transitions, clip notifications and per-clip blend weights - with the clock on the CPU and the deformation on the GPU. An entity that needs state-driven animation carries an `AnimationGraphController` component: a state machine that decides which clips of its model are playing, what each one weighs, and where in its timeline each one is. `AnimationGraphSystem` ticks every controller once a frame and hands the result to the renderer's `GPUAnimationManager`, which does the deformation on the GPU. The state machine - `AnimationState`, `AnimationTransition`, `BlendStateMatrix` and the graph-definition/JSON layer - is plain CPU data. There is no mixer, no action object, and no graph runtime object separate from the component. ## Setting up the system ```js import { AnimationGraphSystem } from "@woosh/meep-engine/src/engine/graphics3/AnimationGraphSystem.js"; import { MeshSystem } from "@woosh/meep-engine/src/engine/graphics3/MeshSystem.js"; import { EngineHarness } from "@woosh/meep-engine/src/engine/EngineHarness.js"; import { load_model_scene_bundle } from "@woosh/meep-engine/src/engine/asset/load_model_scene_bundle.js"; const scene = EngineHarness.shadeScene(engine); const meshes = new MeshSystem( engine.graphics, scene, url => load_model_scene_bundle(engine.assetManager, url) ); await em.addSystem(meshes); await em.addSystem(new AnimationGraphSystem(engine.graphics, scene)); ``` The system's `dependencies` are `[AnimationGraphController, AnimationClips]` - an entity needs both components before the system touches it. A model `MeshSystem` loads carries its clips as an `AnimationClips` on the entity that placed it, and a rig built in code puts one there the same way; the system does not care which. It takes the scene because the scene's GPU context is what issues the clip ids. A skinned model also needs `MeshSkinSystem` to deform - see [Skeletons & skinning](https://meep.company-named.com/docs/animation/skeletons/#who-registers-what). `AnimationGraphSystem3` is removed; import the unsuffixed `AnimationGraphSystem`. ## The CPU owns the clock The renderer can advance clip time itself, in its tick shader, and neither animation system ever asks it to. `AnimationClipFlags.Playing` is left clear and each playing clip's time is written down every frame with `GPUAnimationManager.set_time`. The reason is that the pose gameplay reads - a socket, an effect anchor, the muzzle a projectile leaves from - has to be the pose that is on screen, and two clocks drift. One clock, on the CPU, is what makes [`query_entity_node_world_pose`](https://meep.company-named.com/docs/ecs/hierarchy/) answer with the pose the frame was drawn from. ```pintora sequenceDiagram System->>Controller: tick(dt) Controller->>Entity: notification events Controller-->>System: weights + clip times System->>GPUAnimationManager: set_playback_weight / set_time ``` Two consequences worth knowing: - **Nothing is culled.** `AnimationGraphFlag.MeshSizeCulling` and `AnimationFlags.MeshSizeCulling` exist as constants and deserialize, but nothing reads them: a clock that camera framing can stop is a simulation that camera framing can change. Drawing is culled, and that is the renderer's job. - **A finished one-shot holds its last frame.** The renderer's pose accumulator has no rest-pose term to fall back to, so there is nothing else it could do. ## Defining a graph A graph definition is authored as JSON and loaded with `readAnimationGraphDefinitionFromJSON`: ```js import { readAnimationGraphDefinitionFromJSON } from "@woosh/meep-engine/src/engine/graphics/ecs/animation/animator/graph/definition/serialization/readAnimationGraphDefinitionFromJSON.js"; const def = readAnimationGraphDefinitionFromJSON({ clips: [ { name: "idle", duration: 2.0 }, { name: "run", duration: 0.8 } ], notifications: [ { event: "foot-plant-left" }, { event: "foot-plant-right" } ], states: [ { name: "Idle", type: 2 /* AnimationStateType.Clip */, motion: { def: 0, weight: 1, timeScale: 1, flags: 1 /* Repeat */ }, tags: ["idle"] }, { name: "Run", type: 2, motion: { def: 1, weight: 1, timeScale: 1, flags: 1 }, tags: ["run"] } ], transitions: [ { event: "start-run", source: 0, target: 1, duration: 0.2 }, { event: "stop-run", source: 1, target: 0, duration: 0.3 } ], startingSate: 0 }); ``` Note the key: the reader destructures `startingSate` (the spelling in the source), an index into `states`. Anything else falls back to `0`, so the first state becomes the starting state. The `duration` written in the JSON is not what plays. Durations are the clips', not the graph's, and `AnimationGraphSystem` overwrites them from the entity's `AnimationClips` - for a model, the loaded `.glb`'s - before the first tick. See below. The loader calls `AnimationGraphDefinition.build()` for you, which populates `clipIndex`: the flat list of distinct `AnimationClipDefinition`s the graph names. Every per-clip array in the runtime - weights, time scales, times, GPU ids - is in `clipIndex` order. `AnimationGraphDefinitionAssetLoader`, beside the reader, is the `AssetLoader` that turns a JSON asset into a built definition - register it with the asset manager to load graphs by path. ## Core objects | Class | Role | |---|---| | `AnimationGraphDefinition` | Immutable blueprint - states, transitions, `clipIndex` | | `AnimationGraphController` | **The ECS component.** Current state, active transitions, per-clip blend state, per-clip clock | | `AnimationState` | Runtime node - owns a `BlendStateMatrix`, tracks playback time | | `AnimationTransition` | Directed edge - fires on an entity event, cross-fades over `duration` seconds | | `AnimationClip` | Motion on a state - an `AnimationClipDefinition` plus `weight`, `timeScale` and `flags` | | `AnimationClipDefinition` | Clip metadata - name, `duration`, sorted `notifications[]`, `tags[]` | `AnimationGraphController` lives at `@woosh/meep-engine/src/engine/graphics3/animation/AnimationGraphController.js` (named export, `typeName = "AnimationGraphController"`); everything else is under `engine/graphics/ecs/animation/animator/`. **The controller does not round-trip.** It has no serialization adapter and is not in `populateEngineSerializationRegistry` - it is built transiently from the graph definition each time an entity is decorated. The `typeName` exists so the registry can name the class, not because anything writes one to disk. ## Attaching a controller ```js import { AnimationGraphController } from "@woosh/meep-engine/src/engine/graphics3/animation/AnimationGraphController.js"; import { SGMesh } from "@woosh/meep-engine/src/engine/graphics/ecs/mesh-v2/aggregate/SGMesh.js"; import { Transform64 } from "@woosh/meep-engine/src/engine/ecs/transform/Transform64.js"; const controller = new AnimationGraphController(); controller.initialize(def); controller.start_phase = Math.random(); // fraction of the starting clip ecd.addEntity([ SGMesh.fromURL("data/models/knight.glb"), new Transform64(), controller ]); ``` `initialize(def)` builds one `AnimationState` per state definition and one `AnimationTransition` per transition, and wires them to each other. Do not call it on a linked controller. `start_phase` is where the graph begins inside its starting clip, as a **fraction** of that clip's duration - a fraction rather than a time because the duration comes from the model, which loads long after the entity does. It is applied once, at link, without dispatching the notifications it skips over, so a unit that spawns mid-stride does not also spawn the footstep it missed. Its purpose is to keep identical units from moving in lockstep. You do not call `link` yourself. `AnimationGraphSystem` does it in the first update after the entity's `AnimationClips` arrives: 1. It resolves each entry of `def.clipIndex` to one of the entity's clips **by name**. A name the entity does not carry throws `Animation clip '' is not among the clips of entity `, from the system's tick rather than from whoever added the component. 2. It calls `controller.link(entity, ecd, durations)` with the durations those clips actually have. `link` writes them onto the shared clip definitions, which is where notification timing reads them. 3. It registers **only the clips the graph names** with the GPU animation manager, and re-registers when the clips change. That last point is a rule, not an optimisation - see [Skeletons & skinning](https://meep.company-named.com/docs/animation/skeletons/) for why a clip nobody plays must not be bound. ## States and state types `AnimationStateType` has three values: | Value | Constant | Meaning | |---|---|---| | `1` | `Unknown` | placeholder / uninitialised | | `2` | `Clip` | single clip - the only type anything evaluates | | `4` | `Blend` | blend space (see below) | Each `AnimationStateDefinition` carries a `tags` string array. Tags do not drive transitions; `AnimationGraphDefinition.matchStateWithMostTags(tags)` returns the definition matching the most of them - preferring the state with the fewest tags on a tie, and `undefined` when no state shares a tag. That is how you pick an idle or a movement state at runtime without hard-coding event names. `AnimationGraphController` also offers `state_by_name(name)`, `state_by_clip_name(name)` and `state_by_definition(def)` for finding the runtime state that corresponds to one. ## Transitions An `AnimationTransitionDefinition` has three fields that matter at runtime: | Field | Type | Purpose | |---|---|---| | `event` | `string` | Entity event name that triggers this transition | | `duration` | `number` (seconds) | Cross-fade length. The class default is `0.2`, but the JSON reader writes `0` for any transition that omits it - so always author it | | `source` / `target` | `AnimationStateDefinition` | The directed edge | When a state is entered, each of its outgoing transitions registers an entity event listener. When the event fires, `AnimationTransition.transition()` starts the cross-fade and pushes itself onto the controller's `activeTransitions`; the target becomes `state` immediately, while the source keeps ticking in `simulatedStates` until the transition finishes. Cross-fades interpolate with `BlendStateMatrix.lerp` over the transition's normalised time - weights and time scales both. The transition's own clock advances at a rate lerped between the source's and the target's `timeScale`. Multiple transitions can be active at once: the controller sums their blend states and divides by the count. ```js // fire a transition from gameplay code: ecd.sendEvent(entityId, "start-run"); ``` ## Clip flags and playback `AnimationClipFlag.Repeat = 1` - set this bit in `motion.flags` to loop the clip. Without it, the clip plays once, clamps at its end, and dispatches `AnimationEventTypes.ClipEnded` (`"animation-event-clip-ended"`) with the `AnimationClip` as the event payload. `AnimationClip.timeScale` multiplies the playback rate; `AnimationState.timeScale` is a second multiplier at the state level. Both are composited into the `BlendStateMatrix` row, and both are consumed **on the CPU** - the time they scale is already integrated into the state's clock, so they have no GPU counterpart. `AnimationGraphController.clip_time(clip_index)` gives the time a clip is at, in seconds from its own start, wrapped for a looping clip and clamped for a one-shot. That is exactly the value written to the renderer and exactly what a pose query has to be asked at. It is only meaningful for a clip the blend gives weight to; a clip nothing is playing keeps whatever time it last stopped at. ## Clip notifications Notifications let a clip fire game events at authored times - foot-plant contacts, attack windows, sound cues. Each `AnimationClipDefinition` holds a `notifications` array of `AnimationNotification` objects sorted by `time`, each referencing an `AnimationNotificationDefinition` that stores an `event` string and a `data` payload. `AnimationClip.dispatchNotifications(entity, ecd, time0, time1)` runs during `AnimationState.tick` and dispatches everything in the **half-open** interval `[time0, time1)`, calling `ecd.sendEvent(entity, event, data)` for each. The interval is half-open so consecutive steps tile the timeline without overlap: a step's end time is carried forward verbatim as the next step's start time, and accumulated frame times do land exactly on authored notification times. By the same rule a clip spans `[0, duration)`, so a notification authored at exactly `duration` belongs to the next cycle - which a non-repeating clip never plays. Use `ClipEnded` for the end of a one-shot. A looping clip re-enters the list at `time = 0` on each cycle boundary, and a single step that spans several cycles fires each cycle's notifications in order. ```js // listen for a foot-plant notification on the entity: ecd.addEntityEventListener(entityId, "foot-plant-left", onFootPlant); ``` ## Blend spaces `BlendSpace`, `BlendSpaceDefinition` and `BlendSpacePoint` ship under `engine/graphics/ecs/animation/animator/blending/`, and `AnimationStateType.Blend` is still a constant - but **nothing evaluates them**. `AnimationState.updateBlendState` handles `AnimationStateType.Clip` and nothing else, `readAnimationGraphDefinitionFromJSON` always builds an `AnimationClip` for a state's `motion`, and no module in the engine imports `BlendSpace`. Treat the types as unwired scaffolding, not as a feature. For blending today, use overlapping transitions, or drive several clips directly through the [`Animation` component](https://meep.company-named.com/docs/animation/skeletons/) and its `AnimationSystem`, where per-clip weights are shares of one pose. ## Related - [Skeletons & skinning](https://meep.company-named.com/docs/animation/skeletons/) - `Skin`, `GPUAnimationManager`, per-entity model instancing - [Inverse kinematics](https://meep.company-named.com/docs/animation/inverse-kinematics/) - post-processing the pose against terrain - [Hierarchy](https://meep.company-named.com/docs/ecs/hierarchy/) - how a bone is addressed, and querying a socket's world pose - [Meshes & materials](https://meep.company-named.com/docs/rendering/meshes-materials/) - `SGMesh` and `MeshSystem` - Source: `engine/graphics3/animation/`, `engine/graphics/ecs/animation/animator/` --- # Skeletons & skinning Section: Animation Source: https://meep.company-named.com/docs/animation/skeletons/ Description: How the renderer deforms skinned meshes on the GPU - MeshSkin and AnimationClips components, the systems that register them with GPUAnimationManager, and models spawned per entity from a compiled prefab. Skinning belongs to the renderer and runs on the GPU. In the ECS a skinned model is components: a `MeshSkin` on each mesh entity a skeleton deforms (the joints, as entities, and their inverse-bind matrices), and an `AnimationClips` on the entity that plays the model's `ShadeAnimationClip`s. `MeshSkinSystem` registers every skin with a `GPUAnimationManager`, the animation systems register the clips they play, and the manager evaluates curves, accumulates the pose, builds skin matrices and deforms vertices in compute passes. The GPU-side types live under `@woosh/meep-engine/src/shade/renderer/animation/`. The components, the systems that register them, and the prefab layer that turns a loaded model into entities live under `@woosh/meep-engine/src/engine/`. ## The per-frame chain ```pintora activityDiagram start :advance clip time; :evaluate curves, add into the pose accumulator; :resolve the accumulator into node TRS; :compose the transform hierarchy; :build skin matrices; :deform the per-instance vertex clone; end ``` `GPUSceneContext` runs all of it - it calls `GPUAnimationManager.update()` to flush pending uploads and `GPUAnimationManager.tick(cmd_ctx, dt)` to encode the passes. Application code never drives those directly; it registers data and sets playback state. ## Skin `@woosh/meep-engine/src/shade/renderer/animation/Skin.js` (named export). Pure data - it knows nothing about the GPU. | Member | Type | Meaning | |---|---|---| | `name` | `string` | Optional, empty by default | | `joints` | `number[]` | Ordered joints. A joint's **index in this array** is the index the per-vertex `SkinningJoints` attribute refers to. What each number *is* depends on where the skin lives - see below | | `inverse_bind_matrices` | `Float32Array` | Joint-count x 16, flat, **column-major**. Joint `j` occupies `[j*16, j*16+16)`. glTF already stores them this way, so loaders copy straight in | | `meshes` | `number[]` | The meshes that deform against this skin, addressed the same way as `joints` | **A skin's `joints` and `meshes` are indices, and which index depends on where the skin is.** In a loader's `SceneBundle` they index `bundle.nodes`; in a compiled `Prefab` they are that prefab's node indices. A placement carries no `Skin`: [`prefab_instantiate`](#per-entity-instancing) turns each into a `MeshSkin` on the mesh entities it deforms, with the joints as entities. `Skin.from({ name?, joints, inverse_bind_matrices, meshes? })` validates lengths and shape; `copy(other)` and `clone()` share `inverse_bind_matrices` outright. Several meshes can share one skin: a character's body and its hair, both bound to the same joints. ## MeshSkin `@woosh/meep-engine/src/engine/graphics/ecs/mesh-v2/MeshSkin.js` (named export). The component that makes the geometry beside it deform, and it lives on the mesh entity: the geometry's per-vertex joint indices index `joints`, and an inverse bind belongs to the pair of this mesh and that joint. | Member | Type | Meaning | |---|---|---| | `joints` | `Int32Array` | The joints, as **entities**, in the order the geometry's `SkinningJoints` attribute addresses them | | `inverse_bind_matrices` | `Float32Array` | `joints.length` x 16, column-major, shared - every placement of a model holds the one array its prefab compiled | `MeshSkin.from(joints, inverse_bind_matrices)` builds one. The joints are entities like any other, so a clip, IK, a ragdoll or cloth moves them and the skin follows. - **The geometry must draw a clone.** The `ShadedGeometry` beside it carries `ShadedGeometryFlags.Skinned`; without the flag it draws the shared source and nothing deforms. - **Replaced, never edited.** A skin is registered once with the joints and matrices it has then. To change either, take the component off and put another on. - **One skeleton, one registration.** Meshes bound to the same joints with the same inverse binds - a body and its hair - share one GPU skin whether or not they share the arrays, so the skeleton's matrices are built once a frame. - **Not saved.** The joint indices address a vertex attribute no save holds, so whatever builds the geometry builds its skin. `MeshSkinSystem` (`engine/graphics3/MeshSkinSystem.js`) is what deforms it - see [Who registers what](#who-registers-what). ## The skinned primitive A skinned mesh is an entity like any other primitive: a `transforms` row, a `meshes` row, and a `ShadedGeometry` naming what it draws with the `Skinned` flag set - plus the `MeshSkin` that says which joints it is weighted to. On the CPU it points at the **unmodified** source `MeshletGeometry`, exactly like any other instance of that mesh. The GPU allocates a per-instance vertex clone inside the meshlet buffers, registers it as its own geometry id, and a compute pass writes the deformed result into the clone each frame - every other instance still points at the source and is untouched. Skin matrices follow the glTF formula - the inverse of the mesh's world, times the joint's world, times the joint's inverse-bind matrix - and the rasterizer re-applies the mesh entity's own world transform to the result, so it cancels out exactly. Which frame a skin deforms in is settled **once per model**, at compile time, by `prefab_normalize_skin_frames` - not once per placement, and not at registration. The GPU-side **skin id** is a table row and lives in `GPUMeshSkinningContext`; nothing on the CPU stamps it onto anything. ### Which bounds to believe There is one answer, and it is the GPU's. The **deformed** world box is refreshed every frame from the vertices the skinning pass just moved, and published into the scene database's `meshes` row by that pass's bounds-refresh chain. Nothing on the CPU keeps a copy, and nothing could: a joint driven by the pose accumulator has its local offset resolved on the GPU, so the CPU never holds the pose that is on screen. `GPUSceneContext.bounds` reads the row back, a frame or two behind. ## Clips, channels and properties **`ShadeAnimationClip`** (`shade/renderer/animation/ShadeAnimationClip.js`, named export) is a bundle of channels sharing one clock. The `Shade` prefix is there because the engine already exports an unrelated `AnimationClip` used by the [graph and clip-list drivers](https://meep.company-named.com/docs/animation/graphs/). | Member | Notes | |---|---| | `name` | Optional | | `channels` | `ShadeAnimationChannel[]`; order does not matter | | `get start_time` / `get end_time` | Earliest and latest keyframe times across every channel's curves; used as the clip's `time_start` / `time_end` at registration | | `get duration` | `end_time - start_time` | | `static from({ name?, channels })` | Builder | | `copy(other)` / `clone()` | Channels are deep-cloned; the curves inside them are shared | | `apply(t)` | CPU stepping helper - **mutates** the targets | | `optimize()` | See [Optimising a clip](#optimising-a-clip) | **`ShadeAnimationChannel`** (same directory, named export) is one binding: `{ target: number, property: number, curves: { x?, y?, z?, w? } }`, plus `static from(...)`, `copy`, `clone`, `apply(t)`, `get curve_count` and `optimize()`. `target` is addressed exactly as a skin's joints are - a bundle node index, a prefab node index, or an **entity** in a placement's `AnimationClips`, which is what `register_clip` takes. `property` comes from **`Node3DProperty`** (`shade/renderer/object_property/Node3DProperty.js`, named export): | Constant | Value | Curve slots | Masking | |---|---|---|---| | `Translation` | `0` | `x`, `y`, `z` | Per-axis; an absent slot leaves that axis alone | | `Rotation` | `1` | `x`, `y`, `z`, `w` | None - the quaternion is written whole and normalised. Supply all four | | `Scale` | `2` | `x`, `y`, `z` | Per-axis. For a uniform pulse, point all three slots at one curve | Rotation needs the normalise because cubic-Hermite interpolation of four scalar curves drifts off the unit 4-sphere; `apply` and the GPU apply shader both do it. ## GPUAnimationManager `shade/renderer/animation/GPUAnimationManager.js`, named export. `new GPUAnimationManager(device, label, scene_context)`. You do not normally construct one - `GPUSceneContext` owns it, and `graphics.scene_context(scene).animation_manager` is where it comes from. | Level | Methods | |---|---| | Registration (high level) | `register_skin(joints, inverse_bind_matrices) -> number`, `bind_skin_mesh(entity, skin_id)`, `unbind_skin_mesh(entity)`, `register_clip(clip) -> number`, `unregister_skin(id)`, `unregister_clip(id)` | | Registration (low level) | `add_curve(curve)`, `add_track({x?,y?,z?,w?})`, `add_skin({ joints: [{ node, inverse_bind }] })`, `add_clip({ time?, time_start?, time_end?, bindings: [{ track, instance, property }] })` | | Playback state | `start(id)`, `stop(id)`, `set_time(id, t)`, `set_playback_rate(id, rate)`, `set_playback_weight(id, w)`, `set_flags(id, bits)` (OR), `clear_flags(id, bits)` (AND-NOT) | | Per frame | `update(cmd_ctx)`, `tick(cmd_ctx, dt)`, `dispatch_skin_matrix_prep(cmd_ctx)`, `ensure_pose_accumulator_capacity(row_count)` - all driven by the scene context | | Buffers and lookups | `get skin_matrices_buffer`, `get prev_skin_matrices_buffer`, `get skin_matrix_count`, `get pose_accumulator_buffer`, `get_skin(id)`, `get_skin_matrix_offset(id)`, `get_skin_joint_count(id)`, `get database` | `register_skin` takes the joints as entities and their inverse binds, and each call is one hold on the skin. A second registration with the same joint entities in the same order under the same inverse binds answers with the first one's id, and the last `unregister_skin` frees it. `bind_skin_mesh` deforms a mesh entity against an issued skin - one skin per mesh, so `unbind_skin_mesh` first to move it. `AnimationClipFlags` (same directory, named export) is `{ Playing: 1 << 0, Loop: 1 << 1 }` and applies to a **GPU** clip record. Do not confuse it with either ECS-side `AnimationClipFlag`: `graphics/ecs/animation/animator/AnimationClipFlag.js` is `{ Repeat: 1 }` and belongs to graphs, `ecs/animation/AnimationClipFlag.js` is `{ ClampWhenFinished: 1 }` and belongs to the `Animation` component. Three similar names, three different enums. ### Registration is eventually consistent `register_skin` and `register_clip` return an id **synchronously**, and every state mutator and the matching `unregister_*` accept it immediately. If a joint entity or a channel target has not taken its `transforms` row yet, the driving chain is queued and built on the next `update()` that sees every one of them there. Until then the registration is **inert, not wrong**: the table row holds a placeholder head pointer, so no deformation runs and the apply pass produces no contributions. That is what makes registration callable the moment an instance exists rather than at some later moment when the scene is known to be built. Curves and tracks are interned synchronously - they are pure data with no scene dependency. ### Do not register clips nobody plays The pose accumulator marks a joint dirty for every **bound** clip that writes to it, whatever that clip's weight. So a bound clip at weight zero resolves the joints only it drives to **zero** rather than leaving them at rest, and a model whose every clip was registered renders the sum of all of them. Register only what a driver actually plays, and re-register when that changes. A clip no driver claims is never bound and so moves nothing. `register_clips` takes the set of clips for exactly this reason. ### Skin matrix buffers ping-pong `skin_matrices_buffer` holds this frame's matrices; `prev_skin_matrices_buffer` holds the previous frame's, which the skinning pass reads to produce `position_prev` for the velocity pass. The two **swap roles every frame**, and either can be reallocated on grow. Re-fetch both every frame. Caching either reference across frames reads the wrong buffer. The same applies to `pose_accumulator_buffer`, which is invalidated when `ensure_pose_accumulator_capacity` grows it. ## Per-entity instancing A loader hands back a `SceneBundle` - `{ nodes: SceneNode[], skins: Skin[], clips: ShadeAnimationClip[], lights: {light, node}[] }` (`shade/renderer/loader/SceneBundle.js`). That is **the model as loaded, not a placement of it**: records addressed by node index, with no transform state anyone could pose. It is compiled once and spawned per placement: ```js import { prefab_compile } from "@woosh/meep-engine/src/engine/graphics3/prefab/prefab_compile.js"; import { prefab_instantiate } from "@woosh/meep-engine/src/engine/graphics3/prefab/prefab_instantiate.js"; const prefab = prefab_compile(bundle); // once per model const instance = prefab_instantiate(prefab, dataset, root); // once per placement ``` `prefab_compile(bundle) -> Prefab` reads the bundle and never writes it. Geometry, materials, inverse-bind matrices and the animation curves are referenced, not copied - none of them is per-placement state, which is what makes a prefab cheap to spawn. Two things are settled here, once per model rather than once per placement: each skin's meshes are put into the frame that skin deforms in (`prefab_normalize_skin_frames`), and each clip that scales something is checked against each skin (`prefab_skin_clip_scale_conflicts`). `prefab_instantiate(prefab, dataset, root) -> PrefabInstance` spawns the model under an entity you already have. Every node becomes an entity carrying a `Transform64`, a `Name`, a `TransformAttachment` naming its parent and a `ParentEntity` naming the root. An entity whose local offset a clip drives is granted `GPUStateAuthority` for `TransformAttachment` (`engine/ecs/gpu/`), because the pose accumulator resolves that offset on the GPU and a CPU that also wrote it would race the animation. A primitive a skin deforms gets the `Skinned` flag and a `MeshSkin` naming this placement's joint entities. The model's clips, every channel re-addressed to this placement's entities, go on the root as one `AnimationClips` - empty when the model has none - added last, once every entity they key exists. The root must not carry an `AnimationClips` already: one root holds one placement. | `PrefabInstance` member | Meaning | |---|---| | `prefab` | the model it was spawned from | | `root` | the entity that placed the model - node 0, which was there already | | `entities` | `Int32Array` - the entity of each node, by node index; `entities[0]` is `root` | | `mesh_entities` | `Int32Array` - the entities that draw, one per primitive, in the prefab's primitive order | | `entity_of(name)` | **the entity of the node the asset calls `name`**, or `-1`. This is where a socket, an effect anchor or a projectile spawn is looked up | Nothing a model needs in order to work is only on the instance. Its skins are the `MeshSkin`s on its mesh entities and its clips are the `AnimationClips` on its root, which is where a rig built in code puts both too: ```js import { MeshSkin } from "@woosh/meep-engine/src/engine/graphics/ecs/mesh-v2/MeshSkin.js"; import { AnimationClips } from "@woosh/meep-engine/src/engine/graphics3/animation/AnimationClips.js"; const skinned = instance.mesh_entities.find(e => dataset.getComponent(e, MeshSkin) !== undefined); const joints = dataset.getComponent(skinned, MeshSkin).joints; // entities const clips = dataset.getComponent(instance.root, AnimationClips).clips; const dance = clips.find(clip => clip.name === "Dance"); ``` Instantiation registers nothing with the GPU. A placement is components, and the systems that read them register what they need. ### Who registers what The split follows ownership. A **skin** belongs to the mesh it deforms, so `MeshSkinSystem` registers every `MeshSkin`, binds its mesh to it and holds a row for each joint and everything above it, so a joint under a clip-driven ancestor composes on the GPU. Register it beside `ShadedGeometrySystem`, which draws the clone. Without it a skinned primitive draws undeformed, in its bind pose: ```js import { ShadedGeometrySystem } from "@woosh/meep-engine/src/engine/graphics3/ShadedGeometrySystem.js"; import { MeshSkinSystem } from "@woosh/meep-engine/src/engine/graphics3/MeshSkinSystem.js"; const scene = EngineHarness.shadeScene(engine); await em.addSystem(new ShadedGeometrySystem(engine.graphics, scene)); await em.addSystem(new MeshSkinSystem(engine.graphics, scene)); ``` It does not care where a skin came from - a model `MeshSystem` loaded, or a mesh built in code. Registration waits for its `update`, never happening at link, because a spawn adds components node by node and there may be no device yet. A renderer restart voids every id the old context issued; they are forgotten rather than handed back, and every skin registers again in the new context. A **clip** belongs to whatever plays it, so the animation drivers register clips: | Driver | Component | System | |---|---|---| | State machine | `AnimationGraphController` | [`AnimationGraphSystem`](https://meep.company-named.com/docs/animation/graphs/) | | Clip list | `Animation` (`engine/ecs/animation/Animation.js`) | `AnimationSystem` (`engine/graphics3/AnimationSystem.js`), which plays it through `ClipListPlayer` | Both take `(graphics, scene)` and drive an entity while it carries their component and an `AnimationClips` - whoever put them there. New clips are a new `AnimationClips`, which a driver sees as its entity leaving and coming back. In the clip-list path the per-clip weights are **shares of one pose** - each clip's weight over the list's total - which is why a walk clip at weight 1000 against an idle at 1 means "the walk". Both call `register_clips(context, clips, slots)` (`engine/graphics3/register_clips.js`), which registers the named slots of an entity's clips and returns a `ClipRegistration` = `{ context, ids: Int32Array }`, indexed by the clip's place with `CLIP_NOT_REGISTERED` wherever this driver does not play that clip. Duplicate slots are ignored - two graph states naming one clip is one GPU row, and registering it twice would be two rows the accumulator adds together. A registration carries the `GPUSceneContext` it was issued by, and that is the point of the field: **an id may only be handed back to the manager that issued it.** A renderer restart builds a new context and voids every id the old one gave out, so a holder compares with `===` before calling `unregister_clips`, and forgets the ids otherwise rather than corrupting a stranger's table. Both systems also expose `write_pose_playbacks(target, entity) -> boolean`, which appends `PosePlayback` entries (`{ clip, time, weight }`) for whatever the entity is playing. That is the input to the CPU pose evaluator. ## Bounds One thing answers the bounds question, and it is measured on the GPU. The deformed world box is computed by the skinning pass's bounds-refresh chain - from the vertices that pass has just moved - and published into the scene database's `meshes` row. There is no CPU-side bound to keep in step with it, no call that computes one, and nothing an author writes down: a skinned silhouette is wherever the pose put it, and the pose is the GPU's. Read it back through `GPUSceneContext.bounds`, which is asynchronous and a frame or two behind by construction. An outcome that has to be decided this tick cannot depend on it - for "where is this bone", evaluate the pose instead, which is what [Addressing a bone](#addressing-a-bone) is about. ## Optimising a clip `ShadeAnimationClip.optimize()` calls `ShadeAnimationChannel.optimize()` on every channel and drops any whose `curve_count` collapses to zero. Applying the clip afterwards is observationally identical, with less per-frame work and a smaller upload - each surviving channel still costs a track row and a binding row. Identity gating is per property, and every drop is additionally gated on the target's **rest** value already sitting at that identity (within an epsilon), because an absent slot leaves the rest value in place while a constant-identity curve would overwrite it: | Property | Identity | Granularity | |---|---|---| | `Translation` | `(0, 0, 0)` | Per axis | | `Scale` | `(1, 1, 1)` | Per axis | | `Rotation` | identity orientation - `x`, `y`, `z` all constant zero, `w` free | All four curves or none | Survivors are key-reduced with `animation_curve_optimize` on a **clone**, so a curve shared by sibling clips is never mutated underneath them. The clip itself is mutated in place - clone first if you need the original. The natural place to call it is clip-load time, right after `load_gltf`, for assets whose authoring tool dumped redundant bind-pose channels. `optimize()` returns nothing on purpose. For before/after numbers, compare `clip.channels.length` and the sum of `channel.curve_count` yourself. ## Addressing a bone There is no `Skeleton` object and no `SkeletonUtils`. A model expands into entities, each carrying a `Name` and a `TransformAttachment` pointing at its parent, so naming a bone is naming an entity: ```js import { transform_attachment_find_descendant_by_name } from "@woosh/meep-engine/src/engine/ecs/transform-attachment/transform_attachment_find_descendant_by_name.js"; const bone = transform_attachment_find_descendant_by_name(ecd, entity, "hand.R"); // -1 when there is no such descendant - the model may simply not have arrived ``` To ask where that node **is** in world space, use `query_entity_node_world_pose(result, entityManager, entity, node_name)` from `engine/graphics3/pose/query_entity_node_world_pose.js`. It evaluates the pose from the clips the animation systems are driving, off the same clock they write to the renderer with - it never reads back from the GPU, because readback is a frame late and asynchronous, and an outcome that depended on it would depend on frame pacing. See [Hierarchy](https://meep.company-named.com/docs/ecs/hierarchy/). A name is only how a loaded model is asked. For a joint you already hold - one of a rig built in code - call `collect_entity_playbacks(playbacks, entityManager, entity)` (`engine/graphics3/pose/collect_entity_playbacks.js`) for the entity playing its clips, then `t64_evaluate_world(result, dataset, joint, playbacks)` for the joint, which is all the query does once the name is resolved. ## CPU skinning `IKGoal` addresses its effector and target by entity ID. The CPU skinner is `mesh_apply_skeletal_vertex_skinning` (`engine/graphics/geometry/skining/`). ## Related - [Animation graphs](https://meep.company-named.com/docs/animation/graphs/) - the state machine that decides which clips play - [Inverse kinematics](https://meep.company-named.com/docs/animation/inverse-kinematics/) - placing bones at entity targets after the pose is evaluated - [Hierarchy](https://meep.company-named.com/docs/ecs/hierarchy/) - bones as entities, and querying a socket's world pose - [Meshes & materials](https://meep.company-named.com/docs/rendering/meshes-materials/) - `SGMesh`, `MeshSystem` and model loading - Source: `shade/renderer/animation/`, `engine/graphics3/prefab/`, `engine/graphics3/` --- # Inverse kinematics Section: Animation Source: https://meep.company-named.com/docs/animation/inverse-kinematics/ Description: Entity-target IK goals with joint limits, FABRIK chains, and two-joint limb solvers. meep's IK lives in two places: - `engine/physics/inverse_kinematics/` - the solver algorithms, written as plain functions against `Transform64` / `Vector3` / `Quaternion`. - `engine/ecs/ik/` - the ECS layer that binds those solvers to entities, to the transform hierarchy, and to entity targets. The algorithms are pure maths. In the ECS layer **a bone is an entity**, not an object inside a renderer's skeleton. The goal system evaluates world poses from the hierarchy and live animation clips, then writes local corrections back. ## Entity-target goals `IKGoal` places an effector bone at a target entity's world pose through the `TransformAttachment` hierarchy. Add the component to the effector and register `IKGoalSystem`; the chain root rotates but stays in place. Physics `Joint` components on the chain supply joint limits. This path does not require a terrain. ```js import { IKGoal } from "@woosh/meep-engine/src/engine/ecs/ik/IKGoal.js"; import { IKGoalSystem } from "@woosh/meep-engine/src/engine/ecs/ik/IKGoalSystem.js"; await em.addSystem(new IKGoalSystem()); ecd.addComponentToEntity(effectorEntity, IKGoal.from({ target: targetEntity, chain_root: rootBoneEntity, position_weight: 1, rotation_weight: 0, })); ``` All four fields passed to `IKGoal.from` are required. Both weights range from 0 to 1: zero position weight restores the pose without the goal, while rotation weight blends the effector's chain rotation towards the target's rotation. `IKGoalSystem` depends on `[IKGoal, TransformAttachment]`; `max_iterations` defaults to 16 and `tolerance` to `1e-6` world units. Target and chain-root entity references stay fixed while the component is attached. Remove and re-add it to change them. Destroying the target or a bone in the chain removes the goal. `IKGoal.serializable` is `false`; recreate goals after spawning the model's bones. ### Physics contact targets `ContactProbe` and `ContactProbeSystem` under `src/engine/physics/ecs/` place a target entity through its `TransformAttachment`. A probe casts from a reference entity's world pose plus a world-axis offset. `radius: 0` uses a ray; a positive radius uses a sphere cast. Its unit-length `direction`, positive `distance` and non-negative `radius` define the query. A hit places the target on the surface and aligns its up axis with the contact normal; a miss places it at the reference pose. The `hit` field reports the last result. Register `ContactProbeSystem` before `IKGoalSystem` so contact targets are placed before IK consumes them. A probe reference can be an animated bone, but must not be a bone held by a CPU writer such as IK or cloth: that would feed the previous correction back into the target. Probes skip the character's own colliders by following `ParentEntity` lifetime roots. `ContactProbe.serializable` is `false`. ## FABRIK - arbitrary chains `fabrik_solve` in `engine/physics/inverse_kinematics/fabrik/fabrik_solve.js` implements FABRIK (_Forward And Backward Reaching Inverse Kinematics_) for chains of arbitrary length. Use this low-level helper for chains you drive yourself; `IKGoalSystem` owns its own goal-solving path. ```js import { fabrik_solve } from "@woosh/meep-engine/src/engine/physics/inverse_kinematics/fabrik/fabrik_solve.js"; fabrik_solve( joints, // Transform64[] - updated in place lengths, // number[] - distance to the next joint origin, // Vector3 - where the root must stay target, // Vector3 - where the tip should reach 4, // max_iterations (default) 1e-7 // distance_tolerance (default) ); ``` **Parameters** | Parameter | Type | Notes | |---|---|---| | `joints` | `Transform64[]` | Chain joints, root first. Translations, rotations and matrices are written - the announcement is not: call `t64_announce_change(ecd, entity)` per joint afterwards, or the meshes built on those transforms stay where they were | | `lengths` | `number[]` | `lengths[i]` is the distance from joint `i` to joint `i+1` | | `origin` | `Vector3` | Root anchor - the first joint is pinned here | | `target` | `Vector3` | Goal position for the tip joint | | `max_iterations` | `number` | Default 4 - the solver exits early once the tolerance is met | | `distance_tolerance` | `number` | Squared distance threshold for early exit; default `1e-7` | The underlying primitive `fabrik3d_solve_primitive` works entirely on a flat `Float32Array` of packed XYZ positions to avoid allocation in the inner loop. Chains up to 64 joints use a pre-allocated scratch buffer; longer chains allocate a temporary array. When the target is unreachable - the distance from origin to target exceeds the summed link lengths - the primitive stretches the chain in a straight line toward the target instead of iterating. After the position pass, `fabrik_solve` computes each joint's rotation delta by comparing the before-and-after bone direction with `Quaternion.fromUnitVectors` and applies it with `multiplyQuaternions`. --- ## Two-bone IK The low-level two-joint helper turns a three-joint limb towards a target. ### Algorithm `two_joint_ik` in `engine/physics/inverse_kinematics/two_joint_ik.js` is based on the analytic two-joint solution described in ["Simple Two-Joint IK"](http://theorangeduck.com/page/simple-two-joint), which the source cites. ```js import { two_joint_ik } from "@woosh/meep-engine/src/engine/physics/inverse_kinematics/two_joint_ik.js"; import Vector3 from "@woosh/meep-engine/src/core/geom/Vector3.js"; two_joint_ik( a, b, c, // Vector3 world positions of root, mid, effector t, // Vector3 target position new Vector3(0, 0, 1), // unit hinge axis in the mid joint's local frame a_gr, b_gr, // Quaternion global rotations of root and mid bone a_lr, b_lr // Quaternion local rotations - updated in place ); ``` The hinge axis must be normalized. The solver transforms it by the mid joint's global rotation, preserves each bone's component along that hinge, clamps the target to the resulting reachable interval, and writes local rotation deltas. ## Related - [Skeletons & skinning](https://meep.company-named.com/docs/animation/skeletons/) - how a bone is addressed, and the GPU skinning path IK writes into - [Animation graphs](https://meep.company-named.com/docs/animation/graphs/) - clip-driven animation that IK post-processes - [Hierarchy](https://meep.company-named.com/docs/ecs/hierarchy/) - `TransformAttachment`, and why a solver writes local transforms - [Physics queries](https://meep.company-named.com/docs/physics/queries/) - casts used to produce contact targets - Source: `engine/physics/inverse_kinematics/`, `engine/ecs/ik/` --- # Procedural generation Section: Generation Source: https://meep.company-named.com/docs/generation/overview/ Description: How Meep's marker-and-rule model generates levels - GridData, layers, the task pipeline, generation resources, and where generation fits in the ECS. Meep's procedural-generation system lives under `@woosh/meep-engine/src/generation/`. The central idea is a two-phase pipeline: first, rules visit every cell of a grid and emit typed **markers** into a spatial index; second, a processing pass matches those markers against rules and instantiates ECS entities or paints terrain. The grid itself can carry multiple typed data layers, each independently sized and sampled. ## GridData - the shared workspace `GridData` is the mutable workspace that every generator reads and writes. It has three parts: - **`width` / `height`** - cell dimensions of the grid. - **`layers`** - an array of `GridDataLayer` objects, each a named typed raster. - **`markers`** - a `QuadTreeNode` spatial index of `MarkerNode` objects placed during generation. ```js import { GridData } from "@woosh/meep-engine/src/generation/grid/GridData.js"; import { GridDataLayer } from "@woosh/meep-engine/src/generation/grid/layers/GridDataLayer.js"; import { BinaryDataType } from "@woosh/meep-engine/src/core/binary/type/BinaryDataType.js"; const grid = new GridData(); grid.resize(128, 128); grid.computeScale(1.0); // tileSize → world-space offset/scale transform const obstacleLayer = GridDataLayer.from("obstacles", BinaryDataType.Uint8); grid.addLayer(obstacleLayer); ``` `GridDataLayer.from(id, type, resolution)` creates a named layer backed by a `Sampler2D`. The optional `resolution` multiplier lets a layer carry higher-resolution data than the grid cell count - useful for splat maps that need sub-cell precision. Once added, `grid.getLayerById(id)` retrieves it by name, and layers resize automatically when `grid.resize(w, h)` is called. `grid.addMarker(node)` inserts a `MarkerNode` into the spatial index. `grid.containsMarkerInCircle(x, y, radius, matcher)` and `grid.countMarkerInCircle(x, y, radius, matcher)` query the index spatially, using a `MarkerNodeMatcher` to filter by type or tag. ## Markers A `MarkerNode` is a lightweight record that the generation pipeline places in the grid: | Field | Type | Purpose | |---|---|---| | `type` | `string` | Semantic type identifier - matched by rules | | `tags` | `string[]` | Arbitrary labels for matcher predicates | | `position` | `Vector2` | Grid-space position | | `transform` | `Transform64` | World-space position, rotation, scale | | `size` | `number` | Radius - used for spatial queries and overlap rejection | | `priority` | `number` | Higher-priority nodes are processed first | | `properties` | `Object` | Arbitrary key-value data for downstream rules | Markers are emitted by `GridCellActionPlaceMarker`, which is a `GridCellAction` that runs when a rule fires on a grid cell. Multiple related markers can be emitted atomically with `GridCellActionPlaceMarkerGroup`, which writes a shared `groupId` into all `properties`. ## The rule-and-action loop `GridActionRuleSet` is the engine of the emission phase. It iterates over every cell (or sub-sample, given a `resolution` parameter), selects rules by the configured `policy`, and for each rule: 1. Tests the rule's `pattern` (`CellMatcher`) against the current cell at up to four 90° rotations if `allowRotation` is true. 2. Rolls against the rule's `probability` (`CellFilter`, default 1.0). 3. If both pass, calls the rule's `GridCellAction.execute(grid, x, y, rotation)`. ```js import { GridActionRuleSet } from "@woosh/meep-engine/src/generation/markers/GridActionRuleSet.js"; import { GridCellPlacementRule } from "@woosh/meep-engine/src/generation/placement/GridCellPlacementRule.js"; import { RuleSelectionPolicyType } from "@woosh/meep-engine/src/generation/markers/RuleSelectionPolicyType.js"; import { CellFilterLiteralFloat } from "@woosh/meep-engine/src/generation/filtering/numeric/CellFilterLiteralFloat.js"; const ruleSet = GridActionRuleSet.from({ rules: [myRule], policy: RuleSelectionPolicyType.Sequential, // or Random pattern: [0, 0], // sub-sample offsets within each cell }); const task = ruleSet.process(grid, seed, /* resolution= */ 1); ``` `RuleSelectionPolicyType.Sequential` tries rules in order and stops at the first match; `Random` shuffles before each cell, producing more varied output at higher cost. `process()` returns an async `Task` suitable for Meep's task scheduler. ## Task generators For larger pipelines, `GridTaskGenerator` subclasses compose generation stages. Each generator has a `build(grid, ecd, seed)` method that returns a `Task` or `TaskGroup`, and dependencies can be wired between generators with `addDependency` / `addDependencies`. | Generator | Purpose | |---|---| | `GridTaskSequence` | Run a list of child generators in order | | `GridTaskApplyActionToCells` | Apply a `GridCellAction` to every cell returned by a `CellSupplier` | | `GridTaskExecuteRuleTimes` | Execute a `GridCellPlacementRule` exactly N times at random cells | | `GridTaskDensityMarkerDistribution` | Scatter markers according to a density `CellFilter`, with collision rejection | | `GridTaskCellularAutomata` (discrete) | Advance a cellular automaton over a grid layer | | `GridTaskConnectRooms` (discrete) | Corridor generation between room cells | | `GridTaskGenerateRoads` | Connect marker groups with a road network | | `NoopGridTaskGenerator` | Does nothing - useful as a dependency anchor | `GridTaskDensityMarkerDistribution` is the primary tool for organic scatter. It tiles the grid into 16×16 blocks to approximate blue-noise distribution, samples the density filter at random positions, rolls against the density value, and rejects candidates that overlap an existing marker's radius. The expected marker count is estimated analytically before the run. ## Generation resources and `computeWrites()` Generators inside a `GridTaskGroup` are scheduled concurrently: the task executor interleaves whatever is ready, by wall-clock time slices. Two generators that write the same store therefore produce a result that depends on how the scheduler happened to cut them - the same seed yields a different world on a different machine, or in the same session behind different asset traffic. **Resources** are how a generator declares what it writes so that the group can serialise the ones that collide. A `GridDataLayer` is already a resource under its own layer id; the two stores that are not layers get an `@`-prefixed name, which keeps them disjoint from layer ids (those are plain words): ```js import { GridGenerationResource } from "@woosh/meep-engine/src/generation/GridGenerationResource.js"; GridGenerationResource.Markers; // '@markers' - the marker index, GridData#markers GridGenerationResource.Dataset; // '@dataset' - the EntityComponentDataset written into, // including the terrain entity's components ``` `GridTaskGenerator.computeWrites()` returns that list, and it is **abstract - the base implementation throws `Not Implemented`**. Every custom generator must implement it: ```js import { GridTaskGenerator } from "@woosh/meep-engine/src/generation/grid/GridTaskGenerator.js"; import { GridGenerationResource } from "@woosh/meep-engine/src/generation/GridGenerationResource.js"; class PlaceShrines extends GridTaskGenerator { computeWrites() { return [GridGenerationResource.Markers, "obstacles"]; } build(grid, ecd, seed) { /* … returns a Task or TaskGroup … */ } } ``` Implement it from what the generator actually holds - the layer it targets, the actions it runs, its children - never from a guess about how it will be used. **An under-reported write is a race; an over-reported one only costs a little ordering.** `GridCellAction.computeWrites()` is the same idea one level down, and there the base returns `[]` rather than throwing, matching its no-op `execute`. Any action that writes must override it: `GridCellActionPlaceMarker` returns `[GridGenerationResource.Markers]`, `GridCellActionWriteFilterToLayer` returns `[this.layerId]`. Generators that simply run an action usually delegate - `GridTaskApplyActionToCells`, `GridTaskDensityMarkerDistribution` and `GridTaskCellularAutomata` all return `this.action.computeWrites()`. For a generator or action that composes several children, `compute_writes_union` collects the union: ```js import { compute_writes_union } from "@woosh/meep-engine/src/generation/compute_writes_union.js"; computeWrites() { return compute_writes_union(this.children); } ``` ### The ordering contract `GridTaskGroup.build` walks its children in a topological order of the dependencies they already declare (ties broken by declaration order, so the result is a function of the group alone), and for each resource links every writer to the one immediately before it. The chain makes the rest transitive. Two consequences worth holding on to: - **Generators writing disjoint resources stay concurrent.** They cannot observe each other's writes, so interleaving them is safe and faster. - **Every added edge points the same way as an existing one**, so declaring writes can never introduce a cycle. A cycle among the *declared* dependencies still throws, as does naming a dependency that is not a direct sibling in the same group - use `GridTaskSequence`, or restructure the groups, for ordering across group boundaries. ## Multi-layer grids Layers are independent: a `Uint8` obstacle layer can coexist with a `Float32` heightmap layer and a `Uint16` biome-index layer on the same `GridData`. `CellFilterSampleLayerLinear` and `CellFilterSampleLayerCubic` read back from any named layer inside a filter expression. `CellMatcherLayerBitMaskTest` tests a bitmask against an integer layer directly inside a matcher. This lets rules in one pass use data written by a previous pass. ## Where generation fits The procedural pipeline is separate from the ECS but operates on the same `EntityComponentDataset`. A typical sequence is: 1. Allocate a `GridData` and add layers. 2. Run one or more `GridActionRuleSet` passes to populate markers. 3. Optionally apply cellular automata or room-connection passes. 4. Apply a `ThemeEngine` - see [Themes, matchers & rules](https://meep.company-named.com/docs/generation/rules/) - which converts markers into ECS entities and paints the terrain. ```pintora activityDiagram start :rules visit every grid cell; :emit typed markers into a spatial index; :ThemeEngine matches the markers; :instantiate entities and paint terrain; end ``` The filter algebra used in every step is described in [Cell filters & automata](https://meep.company-named.com/docs/generation/filters/). --- # Cell filters & automata Section: Generation Source: https://meep.company-named.com/docs/generation/filters/ Description: The CellFilter algebra - composable per-cell scalar functions - plus cellular automata rules and distance fields over grid layers. A `CellFilter` is a function `(grid, x, y, rotation) → number`. Every filter in the library extends this base class, has a static `.from(...)` factory, and must be `initialize(grid, seed)` before use. Filters compose - the output of one becomes the input of the next - so complex terrain masks, density fields, and probability functions are all built from the same small set of primitives. Source: `@woosh/meep-engine/src/generation/filtering/` ## Filter lifecycle ```js import { CellFilter } from "@woosh/meep-engine/src/generation/filtering/CellFilter.js"; // All filters share this interface: filter.initialize(grid, seed); // called once; sets __initialized = true const v = filter.execute(grid, x, y, rotation); // called per cell filter.finalize(); // resets __initialized for re-use ``` `ensureInitialized(grid, seed)` is a safe guard that calls `initialize` only if not yet initialized; composable filters call this on their children before executing. ## Complete filter catalog The library groups into seven families. The map below is a quick index; the tables that follow give every class and its import path. ```pintora mindmap * CellFilter algebra ** Constants and reads ** Arithmetic ** Range and interpolation ** Spatial convolution ** Noise ** Lookup and gradient ** Boolean logic ``` ### Constants and layer reads | Class | Import path (under `filtering/`) | Description | |---|---|---| | `CellFilterLiteralFloat` | `numeric/CellFilterLiteralFloat.js` | Returns a constant. `CellFilterLiteralFloat.ONE` and `.ZERO` are pre-built singletons. | | `CellFilterSampleLayerLinear` | `numeric/sampling/CellFilterSampleLayerLinear.js` | Bilinear sample of a named `GridDataLayer`. | | `CellFilterSampleLayerCubic` | `numeric/sampling/CellFilterSampleLayerCubic.js` | Bicubic sample of a named `GridDataLayer`. | | `CellFilterLiteralBoolean` | `boolean/CellFilterLiteralBoolean.js` | Returns a constant boolean (as 0/1). | ### Arithmetic | Class | Import path | Operation | |---|---|---| | `CellFilterAdd` | `numeric/math/algebra/CellFilterAdd.js` | `left + right` | | `CellFilterSubtract` | `numeric/math/algebra/CellFilterSubtract.js` | `left - right` | | `CellFilterMultiply` | `numeric/math/algebra/CellFilterMultiply.js` | `left * right` | | `CellFilterDivide` | `numeric/math/algebra/CellFilterDivide.js` | `left / right` | | `CellFilterNegate` | `numeric/math/algebra/CellFilterNegate.js` | `-value` | | `CellFilterAbsolute` | `numeric/math/CellFilterAbsolute.js` | `Math.abs(v)` | | `CellFilterPower` | `numeric/math/CellFilterPower.js` | `Math.pow(value, power)` | | `CellFilterMax2` | `numeric/math/CellFilterMax2.js` | `max(a, b)` | | `CellFilterMin2` | `numeric/math/CellFilterMin2.js` | `min(a, b)` | | `CellFilterOneMinus` | `numeric/math/CellFilterOneMinus.js` | `1 - v` | ### Range and interpolation | Class | Import path | Description | |---|---|---| | `CellFilterClamp` | `numeric/math/CellFilterClamp.js` | `clamp(value, min, max)` | | `CellFilterSaturate` | `numeric/math/CellFilterSaturate.js` | `clamp(v, 0, 1)` | | `CellFilterStep` | `numeric/math/CellFilterStep.js` | Returns 0 if `x < edge`, else 1 | | `CellFilterLerp` | `numeric/math/CellFilterLerp.js` | `lerp(a, b, f)` - linear interpolation | | `CellFilterInverseLerp` | `numeric/math/CellFilterInverseLerp.js` | Inverse of lerp: given `a`, `b`, `value`, returns `f` | | `CellFilterSmoothStep` | `numeric/math/CellFilterSmoothStep.js` | GLSL `smoothstep(edge0, edge1, x)` - smooth Hermite interpolation | | `CellFilterMembershipGeneralizedBell` | `numeric/math/CellFilterMembershipGeneralizedBell.js` | Generalized bell membership function `1 / (1 + |((x-c)/a)|^(2b))` - controls window width (`a`), slope (`b`), center (`c`) | | `CellFilterCubicFunction` | `numeric/math/poly/CellFilterCubicFunction.js` | Evaluates a cubic polynomial | ### Spatial / convolution | Class | Import path | Description | |---|---|---| | `CellFilterDilate` | `numeric/complex/CellFilterDilate.js` | 3×3 morphological dilation - returns `max` of the 3×3 neighborhood | | `CellFilterSobel` | `numeric/complex/CellFilterSobel.js` | Sobel edge-detection: magnitude of the gradient vector from the 3×3 Sobel kernel | | `CellFilterGaussianBlur` | `numeric/complex/CellFilterGaussianBlur.js` | Gaussian blur with configurable sigma and sample count | | `CellFilterFXAA` | `numeric/complex/CellFilterFXAA.js` | FXAA anti-aliasing filter adapted from the NVIDIA algorithm | | `CellFilterCurvature` | `numeric/complex/CellFilterCurvature.js` | Approximate surface curvature at a cell, based on cross-products of neighbouring normals | | `CellFilterAngleToNormal` | `numeric/complex/CellFilterAngleToNormal.js` | Builds the surface normal of another filter and returns the angle to a fixed 3D reference vector | | `CellFilterDisplaced` | `numeric/util/CellFilterDisplaced.js` | Samples another filter at a position offset by two displacement filters | ### Noise | Class | Import path | Description | |---|---|---| | `CellFilterSimplexNoise` | `numeric/complex/CellFilterSimplexNoise.js` | 2D simplex noise in `[0, 1]`, seeded. `.fractal(octaves, scale, seed, persistence, lacunarity)` builds an fBm chain automatically. | ### Lookup and gradient | Class | Import path | Description | |---|---|---| | `CellFilterLookupTable` | `numeric/complex/CellFilterLookupTable.js` | Legacy LUT hook: requires a one-channel object with `isParameterLookupTable: true`, `itemSize: 1` and `sample(v, out)`. No LUT implementation ships. | | `computeCellFilterGradient` | `numeric/process/computeCellFilterGradient.js` | Utility function: computes the normalized gradient vector `[dx, dy]` at `(x, y)` using the Sobel kernel; returns `false` when magnitude is zero | ### Boolean / logic filters | Class | Import path | Description | |---|---|---| | `CellFilterAnd` | `boolean/logic/CellFilterAnd.js` | `left && right` (Boolean data type) | ### Composing filters All binary filters have `left` / `right` children; ternary filters have `a`, `b`, `c`; unary filters have `source`. Use the static factories - they assert `isCellFilter` on every argument: ```js import { CellFilterSimplexNoise } from "@woosh/meep-engine/src/generation/filtering/numeric/complex/CellFilterSimplexNoise.js"; import { CellFilterSaturate } from "@woosh/meep-engine/src/generation/filtering/numeric/math/CellFilterSaturate.js"; import { CellFilterLerp } from "@woosh/meep-engine/src/generation/filtering/numeric/math/CellFilterLerp.js"; import { CellFilterLiteralFloat } from "@woosh/meep-engine/src/generation/filtering/numeric/CellFilterLiteralFloat.js"; import { CellFilterGaussianBlur } from "@woosh/meep-engine/src/generation/filtering/numeric/complex/CellFilterGaussianBlur.js"; // Fractal noise, blurred, saturated - a smooth terrain mask const noise = CellFilterSimplexNoise.fractal(4, 32); const blurred = CellFilterGaussianBlur.from(noise, 3, 3); const mask = CellFilterSaturate.from(blurred); // Blend two noise fields const noiseLow = CellFilterSimplexNoise.from(64, 64); const noiseHigh = CellFilterSimplexNoise.from(8, 8); const blend = CellFilterLerp.from(noiseLow, noiseHigh, mask); ``` ## Cellular automata `CellularAutomata` is the base class; subclasses override `step(data, width, height)` where `data` is a `Uint8Array` of the grid cells. The supplied concrete implementation is `CaveGeneratorCellularAutomata`: ```js import { CaveGeneratorCellularAutomata } from "@woosh/meep-engine/src/generation/automata/CaveGeneratorCellularAutomata.js"; const ca = new CaveGeneratorCellularAutomata(); ca.random = seededRandom(42); // data is a Uint8Array of width*height cells, pre-filled with 0/1 for (let i = 0; i < 5; i++) { ca.step(data, width, height); } ``` `CaveGeneratorCellularAutomata` applies a survival/birth rule: a live cell dies if it has fewer than 4 live neighbours (8-connected); a dead cell is born if it has more than 5 live neighbours. Running 4–6 iterations on randomly seeded data produces cave-like open regions. The `GridTaskCellularAutomata` generator wraps this as a task stage. ## Distance fields `AreaMask` computes a per-pixel unsigned distance field over a binary `Sampler2D`: ```js import { AreaMask } from "@woosh/meep-engine/src/generation/theme/AreaMask.js"; const mask = new AreaMask(); mask.resize(128, 128); // fill mask.mask.data with 0/1 painted regions … mask.updateDistanceField(); // fills mask.distanceField via computeUnsignedDistanceField mask.updateBounds(); // computes the AABB2 of all set pixels ``` `ThemeEngine` uses the distance fields on `AreaTheme` masks to blend terrain weights at biome boundaries: when multiple themes overlap a cell, each theme's influence is proportional to its distance-field value divided by the overlap count. See [Themes, matchers & rules](https://meep.company-named.com/docs/generation/rules/). ## Caching `CellFilterCache` wraps any filter and memoizes its output at every `(x, y)` for the lifetime of one initialization. Use it around expensive multi-sample filters (Gaussian blur, simplex noise chains) that are evaluated many times per cell from multiple downstream consumers. --- # Themes, matchers & rules Section: Generation Source: https://meep.company-named.com/docs/generation/rules/ Description: The theme and biome system, pattern matchers for grid cells and markers, predicate combinators, and weighted random placement. Once markers are in the grid, a `ThemeEngine` drives the final placement pass. It organises `Theme` objects into `AreaTheme` regions with binary masks, applies terrain layer rules, and processes each `MarkerNode` against a rule set. The matching and predicate layer is a small algebra of composable types, all verified in source. Source: `@woosh/meep-engine/src/generation/` ## Theme structure A `Theme` holds three independent rule sets: | Field | Type | Purpose | |---|---|---| | `terrain` | `TerrainTheme` | List of `TerrainLayerRule` objects that paint terrain layer weights | | `nodes` | `MarkerNodeProcessingRuleSet` | Rules that consume `MarkerNode` objects and produce ECS entities | | `cells` | `CellProcessingRuleSet` | Per-cell rules applied during `ThemeEngine.applyCellRules` | `theme.initialize(seed, ecd, grid)` initialises all three sub-sets in one call. ### Terrain layer rules `TerrainLayerRule` binds a `CellFilter` (the weight function) to a `TerrainLayerDescription` (which texture/material to use). The `ThemeEngine` evaluates every rule's filter at each grid cell, normalises the weights across all active themes at that cell (accounting for distance-field blending at biome boundaries), and writes the result into the terrain's splat map. ```js import { TerrainLayerRule } from "@woosh/meep-engine/src/generation/theme/TerrainLayerRule.js"; import { TerrainLayerDescription } from "@woosh/meep-engine/src/generation/theme/TerrainLayerDescription.js"; import { CellFilterSimplexNoise } from "@woosh/meep-engine/src/generation/filtering/numeric/complex/CellFilterSimplexNoise.js"; import { CellFilterSaturate } from "@woosh/meep-engine/src/generation/filtering/numeric/math/CellFilterSaturate.js"; const rule = TerrainLayerRule.from( CellFilterSaturate.from(CellFilterSimplexNoise.fractal(3, 40)), new TerrainLayerDescription() // fill in texture asset refs ); theme.terrain.rules.push(rule); ``` ## ThemeEngine and area masks `ThemeEngine` stores `AreaTheme` objects in a quad-tree. Each `AreaTheme` pairs a `Theme` with an `AreaMask`: ```js import { ThemeEngine } from "@woosh/meep-engine/src/generation/theme/ThemeEngine.js"; import { AreaTheme } from "@woosh/meep-engine/src/generation/theme/AreaTheme.js"; import { AreaMask } from "@woosh/meep-engine/src/generation/theme/AreaMask.js"; const engine = new ThemeEngine(); engine.seed = 42; engine.assetManager = assetManager; const area = new AreaTheme(); area.theme = myTheme; area.mask.resize(128, 128); // paint area.mask.mask.data with 0/1 … engine.add(area); // auto-computes bounds + distance field const taskGroup = engine.apply(grid, ecd); ``` `engine.apply(grid, ecd)` returns a `TaskGroup` holding: initialise themes, process markers into nodes, apply per-cell rules, and - only when the dataset contains a `Terrain` - apply terrain themes, ensure every terrain tile is built, and re-synchronise the terrain's GPU state. Dependencies between them are declared rather than sequential, so independent stages interleave. When multiple areas overlap a cell, each area's distance-field value is used to proportionally blend the terrain weights. There is **no lightmap or ambient-occlusion bake step**, and generation needs no GPU at all. `engine.assetManager` must be set before `apply` - the terrain pass asserts on it. `engine.getThemesByPosition(result, x, y)` returns all `AreaTheme` objects whose mask contains the point - used internally during both terrain and node passes, and accessible for custom logic. ## CellMatcher - pattern predicates on grid cells `CellMatcher` is the base class for predicates over `GridData`. Its interface is `match(grid, x, y, rotation) → boolean`. It is used as the `pattern` field of `GridCellPlacementRule`. ### Primitive matchers | Class | Import path | Matches when | |---|---|---| | `CellMatcherAny` | `rules/CellMatcherAny.js` | Always - use as a wildcard | | `CellMatcherFromFilter` | `rules/CellMatcherFromFilter.js` | The underlying `CellFilter.execute` returns > 0 | | `CellMatcherLayerBitMaskTest` | `rules/CellMatcherLayerBitMaskTest.js` | A bit-mask test on an integer `GridDataLayer` passes at the cell | | `CellMatcherContainsMarkerWithinRadius` | `rules/cell/CellMatcherContainsMarkerWithinRadius.js` | A marker matching a given `MarkerNodeMatcher` exists within a radius of the cell | | `CellMatcherRemovalPreservesConnectivity` | `rules/cell/CellMatcherRemovalPreservesConnectivity.js` | Taking this cell out of a region would not break the region apart | ### Keeping a region connected `CellMatcherRemovalPreservesConnectivity.from(region)` wraps another `CellMatcher` that defines the region - traversable ground, buildable ground, anything connected - and matches only cells that can be removed from it without splitting it. ```js import { CellMatcherRemovalPreservesConnectivity } from "@woosh/meep-engine/src/generation/rules/cell/CellMatcherRemovalPreservesConnectivity.js"; import { CellMatcherAnd } from "@woosh/meep-engine/src/generation/rules/logic/CellMatcherAnd.js"; const safeToBuildOn = CellMatcherAnd.from( myPlacementPattern, CellMatcherRemovalPreservesConnectivity.from(walkable) ); ``` Placement rules that clear traversability - a town footprint, an interactable that occupies its tile - decide from purely local evidence, and local evidence cannot see that a tile is the only way through. Composing this matcher in makes "keeps the region connected" a *precondition* of placement instead of something checked afterwards, or not at all. The test is the classical simple-point criterion of digital topology, read from the 3×3 neighbourhood, so it is O(1) regardless of region size. Three conditions must hold: the region cells of the 8-ring form exactly one contiguous arc (so any path through this cell can be re-routed along the ring); no orthogonally adjacent region cell is left with no other region neighbour; and the cell has an orthogonal neighbour at all, so it is not a component of its own. The ring is traversed in cycle order under the same 4-adjacency an agent walks with. It is a **sufficient** condition, not a necessary one: a cell whose ring splits into two arcs that reconnect somewhere far away is rejected even though a long detour exists. Rejecting costs a placement opportunity and the rule fires on another cell; accepting wrongly costs the level. ### Pattern matcher `CellMatcherGridPattern` matches a multi-cell neighbourhood. Each cell in the pattern is described by a `GridPatternMatcherCell` - a `(x, y)` local offset plus a child `CellMatcher` to evaluate at that offset. The whole pattern is tested after rotating each offset by `rotation`, so a single rule fires regardless of orientation when `allowRotation` is true. ```js import { CellMatcherGridPattern } from "@woosh/meep-engine/src/generation/rules/cell/CellMatcherGridPattern.js"; import { GridPatternMatcherCell } from "@woosh/meep-engine/src/generation/rules/cell/GridPatternMatcherCell.js"; import { CellMatcherFromFilter } from "@woosh/meep-engine/src/generation/rules/CellMatcherFromFilter.js"; const pattern = CellMatcherGridPattern.from([ GridPatternMatcherCell.from(someFilter, 0, 0), // origin GridPatternMatcherCell.from(edgeFilter, 1, 0), // one cell to the right GridPatternMatcherCell.from(edgeFilter, -1, 0), // one cell to the left ]); ``` ### Logic combinators for CellMatcher | Class | Import path | Behaviour | |---|---|---| | `CellMatcherAnd` | `rules/logic/CellMatcherAnd.js` | Both children must match | | `CellMatcherOr` | `rules/logic/CellMatcherOr.js` | Either child must match | | `CellMatcherNot` | `rules/logic/CellMatcherNot.js` | Inverts a single child | All three have a `static from(left, right)` / `static from(source)` factory that asserts `isCellMatcher`. ## MarkerNodeMatcher - predicates over marker nodes `MarkerNodeMatcher` evaluates a `MarkerNode` - not a grid position - and is used in `MarkerProcessingRule` and as the filter argument to spatial queries like `countMarkerInCircle`. ### Primitive marker matchers | Class | Import path | Matches when | |---|---|---| | `MarkerNodeMatcherAny` | `markers/matcher/MarkerNodeMatcherAny.js` | Always | | `MarkerNodeMatcherNone` | `markers/matcher/MarkerNodeMatcherNone.js` | Never | | `MarkerNodeMatcherByType` | `markers/matcher/MarkerNodeMatcherByType.js` | `node.type === type` | | `MarkerNodeMatcherContainsTag` | `markers/matcher/MarkerNodeMatcherContainsTag.js` | `node.tags` contains the given tag string | ### Logic combinators for MarkerNodeMatcher | Class | Import path | Behaviour | |---|---|---| | `MarkerNodeMatcherAnd` | `markers/matcher/MarkerNodeMatcherAnd.js` | Both children match | | `MarkerNodeMatcherOr` | `markers/matcher/MarkerNodeMatcherOr.js` | Either child matches | | `MarkerNodeMatcherNot` | `markers/matcher/MarkerNodeMatcherNot.js` | Inverts child | ## GridDataNodePredicate - spatial node predicates `GridDataNodePredicate` evaluates both a `GridData` and a `MarkerNode` together - useful for decisions that depend on spatial context. Its `evaluate(grid, node) → boolean` method receives the full grid. | Class | Import path | Behaviour | |---|---|---| | `GridDataNodePredicateAny` | `markers/predicate/GridDataNodePredicateAny.js` | Always true; `.INSTANCE` singleton | | `GridDataNodePredicateNot` | `markers/predicate/GridDataNodePredicateNot.js` | Inverts a child predicate | | `GridDataNodePredicateAnd` | `markers/predicate/GridDataNodePredicateAnd.js` | Both children must be true | | `GridDataNodePredicateOverlaps` | `markers/predicate/GridDataNodePredicateOverlaps.js` | True if any marker matching a `MarkerNodeMatcher` overlaps the node's circle | ## Marker processing rules `MarkerProcessingRule` is the rule that binds a matcher, optional transformers, and an action for the marker processing pass: ```js import { MarkerProcessingRule } from "@woosh/meep-engine/src/generation/markers/actions/MarkerProcessingRule.js"; import { MarkerNodeMatcherByType } from "@woosh/meep-engine/src/generation/markers/matcher/MarkerNodeMatcherByType.js"; import { MarkerNodeActionEntityPlacement } from "@woosh/meep-engine/src/generation/markers/actions/MarkerNodeActionEntityPlacement.js"; const rule = MarkerProcessingRule.from({ matcher: MarkerNodeMatcherByType.from("tree"), transformers: [], action: MarkerNodeActionEntityPlacement.from({ blueprint: treeBlueprint }), consume: true, // stop processing this node after this rule fires }); theme.nodes.add(rule); ``` `MarkerNodeActionEntityPlacement` reads the marker's `transform` and `properties` to position the entity blueprint. It copies the marker's `GridPosition` if the entity has one, then multiplies the node's world transform with the rule's base transform. ### Marker transformers Transformers mutate a `MarkerNode` clone before the action runs: | Transformer | Import path | Effect | |---|---|---| | `MarkerNodeTransformRotateRandom` | `markers/transform/` | Random Y rotation | | `MarkerNodeTransformerYRotateByFilter` | `markers/transform/` | Y rotation driven by a `CellFilter` value | | `MarkerNodeTransformerYRotateByFilterGradient` | `markers/transform/` | Y rotation aligned to the gradient direction of a `CellFilter` | | `MarkerNodeTransformerAddPositionYFromFilter` | `markers/transform/` | Adds filter value to the marker's world Y position (terrain snap) | | `MarkerNodeTransformerOffsetPosition` | `markers/transform/` | Translates position by a fixed offset | | `MarkerNodeTransformerRecordProperty` | `markers/transform/` | Writes a filter value into `node.properties` | | `MarkerNodeTransformerRecordUniqueRandomEnum` | `markers/transform/` | Picks a unique random value from a set and stores it in `properties` | | `MarkerNodeTransformerRemoveTag` | `markers/transform/` | Removes a tag from the node | ## Weighted random placement `MarkerNodeActionSelectWeighted` picks one action from a list based on per-position weights. Each option is a `MarkerNodeActionWeightedElement` - an action paired with a `CellFilter` that returns the weight at the marker's position. The selection is deterministic given the seed. ```js import { MarkerNodeActionSelectWeighted } from "@woosh/meep-engine/src/generation/markers/actions/probability/MarkerNodeActionSelectWeighted.js"; import { MarkerNodeActionWeightedElement } from "@woosh/meep-engine/src/generation/markers/actions/probability/MarkerNodeActionWeightedElement.js"; const selector = MarkerNodeActionSelectWeighted.from([ MarkerNodeActionWeightedElement.from(placeOak, highElevationFilter), MarkerNodeActionWeightedElement.from(placePine, lowElevationFilter), MarkerNodeActionWeightedElement.from(placeShrub, CellFilterLiteralFloat.from(0.3)), ]); ``` The weight filters are evaluated at the marker's grid position and accumulated into a cumulative distribution; a seeded random roll selects the bucket. A weight of 0 or less is skipped. Weights do not need to sum to 1 - the selector normalises by total weight automatically. ## Putting it together ```js import { GridCellPlacementRule } from "@woosh/meep-engine/src/generation/placement/GridCellPlacementRule.js"; import { GridCellActionPlaceMarker } from "@woosh/meep-engine/src/generation/markers/GridCellActionPlaceMarker.js"; import { CellMatcherFromFilter } from "@woosh/meep-engine/src/generation/rules/CellMatcherFromFilter.js"; import { CellFilterSimplexNoise } from "@woosh/meep-engine/src/generation/filtering/numeric/complex/CellFilterSimplexNoise.js"; import { CellFilterSaturate } from "@woosh/meep-engine/src/generation/filtering/numeric/math/CellFilterSaturate.js"; import { CellFilterLiteralFloat } from "@woosh/meep-engine/src/generation/filtering/numeric/CellFilterLiteralFloat.js"; import { GridActionRuleSet } from "@woosh/meep-engine/src/generation/markers/GridActionRuleSet.js"; // 1. A filter that is high in noisy forest areas const forestMask = CellFilterSaturate.from(CellFilterSimplexNoise.fractal(3, 40)); // 2. A rule that emits a "tree" marker when the forest mask is > 0 const treeRule = GridCellPlacementRule.from({ matcher: CellMatcherFromFilter.from(forestMask), action: GridCellActionPlaceMarker.from({ type: "tree", size: 1.5 }), probability: forestMask, // denser near high forest values allowRotation: false, }); // 3. Run the rule set over the grid const ruleSet = GridActionRuleSet.from({ rules: [treeRule] }); const emitTask = ruleSet.process(grid, seed); // 4. After emission, theme engine converts "tree" markers to entities theme.nodes.add(MarkerProcessingRule.from({ matcher: MarkerNodeMatcherByType.from("tree"), action: MarkerNodeActionEntityPlacement.from({ blueprint: treeBlueprint }), consume: true, })); ``` See [Procedural generation overview](https://meep.company-named.com/docs/generation/overview/) for how to run the full pipeline and [Cell filters & automata](https://meep.company-named.com/docs/generation/filters/) for the complete filter reference. --- # Terrain Section: World Source: https://meep.company-named.com/docs/world/terrain/ Description: Tile-based heightfield terrain - meshlet tile entities with splat materials, streamed into the scene, and a cling-to-terrain component that pins entities to the surface. `Terrain` is an ECS component holding a heightfield, a splat weight map and a list of material layers. `TerrainSystem` creates a `ShadedGeometry` entity for each tile, built in a worker and streamed in as the camera sees it. `ShadedGeometrySystem` places those tiles in the scene, and their shared `TerrainShadeMaterial` mixes the splat layers and grid overlay during G-buffer shading. Register both systems to draw a terrain. The [terrain example](https://meep.company-named.com/examples/terrain/) builds a 540 x 540 heightfield with four splat-mapped layers loaded from PNGs. ## Two `TerrainSystem`s, and only one of them draws The package carries a second system beside the component, and it resolves: ```js // Imports, constructs, links, and renders nothing. import TerrainSystem from "@woosh/meep-engine/src/engine/ecs/terrain/ecs/TerrainSystem.js"; ``` `src/engine/ecs/terrain/ecs/TerrainSystem.js` is a **default** export and a working `System`: it builds the component, keeps a BVH, culls tiles against the active camera and ticks `terrain.update()`. It puts nothing in front of the renderer - it adds no mesh to a `Scene` and registers no render extension, and `Terrain.link()` only starts the tile build worker. An app that registers this system gets a terrain that answers height queries perfectly and is invisible. The system that draws is a **named** export from `graphics3/`: ```js import { TerrainSystem } from "@woosh/meep-engine/src/engine/graphics3/TerrainSystem.js"; ``` Everything below describes that one. Its tile entities require `ShadedGeometrySystem` on the same scene. ## Setup ```js import { EngineHarness } from "@woosh/meep-engine/src/engine/EngineHarness.js"; import { TerrainSystem } from "@woosh/meep-engine/src/engine/graphics3/TerrainSystem.js"; import { ShadedGeometrySystem } from "@woosh/meep-engine/src/engine/graphics3/ShadedGeometrySystem.js"; const engine = await EngineHarness.bootstrap({ configuration: (config, engine) => { const scene = EngineHarness.shadeScene(engine); config.addSystem(new ShadedGeometrySystem(engine.graphics, scene)); config.addSystem(new TerrainSystem( engine.graphics, // GraphicsEngine scene, engine.assetManager, )); }, }); ``` `dependencies = [Terrain]`. Three things about that constructor are worth stating outright: - **The scene is the second argument and it must be the right one.** `EngineHarness.shadeScene(engine)` hands out the one `Scene` per engine, the same one `MeshSystem` and `LightSystem` write into. Give `TerrainSystem` a scene nothing draws and the terrain is simply absent from the frame, with no error. - **No image loader registration is needed.** `startup()` calls `assetManager.tryRegisterLoader(GameAssetType.Image, new ImageRGBADataLoader())` itself. There is no `TextureAssetLoader`, and `GameAssetType.Texture` is an enum entry with no loader behind it - layer diffuse maps and the overlay sprite load as `GameAssetType.Image`, which decodes to a `Sampler2D`. - **You do not call `terrain.build()` or `terrain.link()`.** The system's `link()` builds the component if its `Built` flag is clear and then calls `startBuildService()` directly, subscribes to the tile manager's `tileBuilt` / `tileDestroyed` signals, and adopts any tile that was already standing. `EngineHarness.buildBasics({ enableTerrain: true })` registers `TerrainSystem` and builds a small terrain for you. Register `ShadedGeometrySystem` in your configuration as above so its tiles render. The example above is what you write when you want to author the heightfield yourself. Decals run at `AfterGBuffer`, after the terrain material has shaded its surface, so they composite on top of textured ground. See [Render extensions](https://meep.company-named.com/docs/rendering/render-extensions/). ## Building a terrain ```js import Terrain from "@woosh/meep-engine/src/engine/ecs/terrain/ecs/Terrain.js"; import { TerrainLayer } from "@woosh/meep-engine/src/engine/ecs/terrain/ecs/layers/TerrainLayer.js"; import { Transform64 } from "@woosh/meep-engine/src/engine/ecs/transform/Transform64.js"; import Entity from "@woosh/meep-engine/src/engine/ecs/Entity.js"; const CELLS = 64; // grid cells per side const GRID_SCALE = 10; // world units per cell -> 640 unit world const SAMPLES = 128; // height sampler resolution, independent of CELLS const terrain = new Terrain(); terrain.size.set(CELLS, CELLS); terrain.gridScale = GRID_SCALE; terrain.resolution = 2; // render quads per cell // Height field: Float32, one channel. Sampled bicubically in UV space, so its // resolution is free - it does not have to match `size` or the collision grid. terrain.samplerHeight.resize(SAMPLES, SAMPLES); for (let r = 0; r < SAMPLES; r++) { for (let c = 0; c < SAMPLES; c++) { terrain.samplerHeight.data[r * SAMPLES + c] = myHeightFn(c, r); } } // One splat layer, full weight everywhere. terrain.splat.resize(CELLS, CELLS, 1); terrain.splat.fillLayerWeights(0, 255); terrain.layers.addLayer(TerrainLayer.from("./textures/grass.png", 10, 10)); const t = new Transform64(); t.setTranslation(-CELLS * GRID_SCALE / 2, 0, -CELLS * GRID_SCALE / 2); new Entity().add(t).add(terrain).build(ecd); ``` `Terrain` is a **default** export; `TerrainLayer` is **named**. The `Transform64` is optional as far as linking goes - a terrain links without one - but it is what places the tiles and what the raycasts invert, so in practice every terrain has one. ## Key properties | Property | Type | Default | Description | |---|---|---|---| | `size` | `Vector2` | `(0,0)` | Grid dimensions in cells. World footprint is `size x gridScale`. | | `gridScale` | `number` | `1` | World units per cell. | | `resolution` | `number` | `4` | Render quads per grid cell. A tile of `E` cells carries `(E x resolution)^2` vertices. | | `samplerHeight` | `Sampler2D` | `1x1` | Float32, one channel, world-unit heights. Sampled bicubically in UV, so any resolution works. | | `splat` | `SplatMapping` | empty | Per-cell `Uint8` weights, one layer deep per material layer. | | `layers` | `TerrainLayers` | empty | The material layers and the texture array they are packed into. | | `overlay` | `TerrainOverlay` | - | Per-cell RGBA painted over the terrain. See [Water & overlays](https://meep.company-named.com/docs/world/water/). | | `clouds` | `Clouds` | - | Cloud-shadow settings. **Data only - nothing draws them.** See [Water & overlays](https://meep.company-named.com/docs/world/water/). | | `gridTransformKind` | `GridTransformKind` | `Direct` | How grid coordinates map to world. See [Grid transform](#grid-transform). | | `frustumCulled` | `boolean` | `true` | **Inert.** Only the non-drawing system reads it; the drawing system always culls. | | `lightMapURL` | `string\|null` | `null` | **Inert.** Round-trips through serialization; no renderer reads it. Terrain ambient occlusion is the renderer's GTAO. | There is no per-terrain shadow bias - bias is the renderer's, see [Lights & shadows](https://meep.company-named.com/docs/rendering/lights-shadows/#filtering) - and no working `buildLightMap()`, see [Ambient occlusion](#ambient-occlusion). ## How a terrain is drawn ```pintora activityDiagram start :camera frustum queried against the tile BVH; :worker builds tile vertices, normals, uvs, BVH; :tile_geometry_to_meshlets on the main thread; :one ShadedGeometry entity per tile, sharing the terrain material; :ShadedGeometrySystem places the tiles in the scene; :rasterizer writes visibility, terrain material shades the G-buffer; end ``` **The tile is the unit, not the terrain.** Tiles are up to 32 x 32 cells, subdivided further when `resolution` pushes a tile past the 65,536-vertex budget - the edge works out as `max(1, min(32, floor(256 / resolution)))` cells, and the last row and column of the grid are whatever is left over. Each built tile becomes one meshlet-encoded `ShadedGeometry` entity, removed when the tile manager destroys it. Tile geometry is built in the background worker (`bundle-worker-terrain.js`), which also relaxes the planar UVs against 3D edge length and builds the per-tile BVH the CPU raycasts use. Meshlet encoding happens on the main thread when the tile arrives. The terrain material derives its planar coordinates from geometry-space position so splat weights and the overlay stay aligned with the gameplay grid. Tile vertices are already in terrain space, so every tile carries a copy of the terrain entity's `Transform64`, together with `ShadedGeometry`, `Name`, `ParentEntity` and transient serialization metadata. The system polls the terrain transform each frame and writes it only when it differs. The tile belongs to the terrain for lifetime management and is rebuilt from terrain data on load. `terrainSystem.tiles_of(entity)` returns its current tile entity IDs. **Every tile shares its terrain's `TerrainShadeMaterial`.** Its `TERRAIN_MATERIAL_TEMPLATE` evaluates the splat mix and overlay as the G-buffer is shaded. Roughness is 1, metalness is 0, the normal comes from the geometry, and there is no emission. Each terrain has its own material and textures; equal settings do not merge two terrains. `TerrainSystem` keeps the parameters current, and sampler versions control texture uploads. Lighting, ambient occlusion and screen-space reflections read the resulting surface through the usual G-buffer. ## Splat layers Layer weights live in `terrain.splat`, one `Uint8` channel per layer per cell; the layer diffuse maps live in `terrain.layers`, packed into a single `texture_2d_array`. ```js const grass = terrain.layers.addLayer(TerrainLayer.from("grass.png", 8, 8)); const rock = terrain.layers.addLayer(TerrainLayer.from("rock.png", 12, 12)); const sand = terrain.layers.addLayer(TerrainLayer.from("sand.png", 6, 6)); // The splat map carries one weight channel per layer - keep the depth in step. terrain.splat.resize(CELLS, CELLS, 3); terrain.splat.fillLayerWeights(grass, 255); terrain.splat.fillLayerWeights(rock, 0); terrain.splat.fillLayerWeights(sand, 0); // Or write a mask in from a Sampler2D of any resolution. Sizes that match copy // straight across; anything else is bilinearly resampled into the splat grid. terrain.splat.writeLayerFromSampler(myMask, rock, /* channel */ 0); ``` Weights are **normalised by their own sum** in the shader, so masks may overlap freely and do not have to add up to 255. An unclaimed pixel has black ground colour; the material forces the ground opaque before applying the overlay. `terrain.replaceLayers(layers, assetManager)` swaps the whole set on an already-built terrain without throwing away tile geometry; `addLayer` grows the splat map by one channel for you. | `TerrainLayer` field | Description | |---|---| | `textureDiffuseURL` | Asset URL of the diffuse map, loaded as `GameAssetType.Image`. | | `size` | `Vector2` - world units per texture repeat. The material derives the tiling as `world size / layer.size`. | | `diffuse` | The decoded `Sampler2D`. Assigning one directly works; layers with an empty URL skip the rescale cache. | | `extra` | Free-form JSON that survives serialization. | Sampler settings the material declares: | Texture | Filtering | Wrap | |---|---|---| | Layer diffuse array | trilinear over a full mip chain, `maxAnisotropy: 8` | repeat - the layers tile | | Splat weights | linear magnification, nearest minification, no mips | clamp to edge | | Overlay sprite | linear | clamp to edge | Two limits: - **The layer count is a uniform, not a `#define`.** Adding or removing a layer recompiles nothing; the mix loop reads the material's `layer_count`. - **The ceiling is the device's texture-array depth.** All layers are slices of one `texture_2d_array`, so the hard bound is `maxTextureArrayLayers`. The renderer does not raise that limit, so what you get is the adapter's - 256 under the WebGPU defaults. Every layer is resampled to `terrain.layers.resolution` (512 x 512 by default) before it goes into the array, in linear light rather than on sRGB bytes. The CPU-side array costs `resolution.x * resolution.y * 4 * layerCount` bytes, so 1 MB per layer at the default. Layer diffuse maps are uploaded as sRGB, so the hardware decodes each texel before filtering and the splat blend averages in linear space. ## Height queries `Terrain` keeps a BVH per tile and answers raycasts synchronously against it, on the CPU, with no renderer involvement: ```js import { SurfacePoint3 } from "@woosh/meep-engine/src/core/geom/3d/SurfacePoint3.js"; const hit = new SurfacePoint3(); // Vertical ray down through world (x, z). if (terrain.raycastVerticalFirstSync(hit, x, z)) { console.log(hit.position.y, hit.normal); } // Arbitrary ray. terrain.raycastFirstSync(hit, ox, oy, oz, dx, dy, dz); ``` Both return `false` if the tile under that point has not been built yet. `terrain.promiseAllTiles()` resolves once every tile is built, which is the way to guarantee an answer for off-screen ground. `sampleHeight(x, z, onHit, onMiss, onError)` wraps the vertical cast in callbacks and hands `onHit` the height, and `projectPointsVertical` / `mapGridPoints` drop whole arrays of points onto the surface, interpolating over any that miss. Grid and world coordinates convert through `mapPointGrid2World(x, y, v3)` and `mapPointWorld2Grid(v3, result)`. This path is entirely separate from [`PickingSystem`](https://meep.company-named.com/docs/rendering/picking/) - terrain picking does not go through the renderer. ## Editing heights at runtime The build worker holds its own copy of the height field, so writing into `samplerHeight.data` changes nothing on its own: ```js terrain.samplerHeight.data[index] = newHeight; terrain.samplerHeight.version++; await terrain.updateHeights(); // ships the field to the worker ``` `updateHeights()` sends the snapshot and hands the tile manager the new version. Tiles built against an older snapshot are marked unbuilt, and the ones the camera can see are rebuilt on the next frames; the tile mesh in the scene is replaced rather than duplicated. To limit the work to a region, `terrain.tiles.rebuildTilesByUV(u0, v0, u1, v1)` retires only the tiles overlapping a normalised rectangle. ## Ambient occlusion `terrain.buildLightMap()` **throws if called**: there is no terrain AO bake. Terrain ambient occlusion is the renderer's GTAO, on by default (`renderer.feature_ssao_enabled`); see [Frame features](https://meep.company-named.com/docs/rendering/frame-features/). `lightMapURL` round-trips so level data that carries it still loads, but nothing reads it. ## Cling to terrain `ClingToTerrain` + `ClingToTerrainSystem` pins an entity's Y to the terrain surface as its XZ changes. Both are **default** exports, and it is the primitive that makes trees, rocks and units sit on the land. ```js import ClingToTerrain from "@woosh/meep-engine/src/engine/ecs/terrain/ecs/cling/ClingToTerrain.js"; import ClingToTerrainSystem from "@woosh/meep-engine/src/engine/ecs/terrain/ecs/cling/ClingToTerrainSystem.js"; await em.addSystem(new ClingToTerrainSystem()); const cling = new ClingToTerrain(); cling.normalAlign = true; // rotate to match the surface normal cling.rotationSpeed = 3; // rad/s cap on that correction entity.add(cling); ``` | Property | Type | Default | Description | |---|---|---|---| | `normalAlign` | `boolean` | `false` | Align the entity's up axis with the surface normal. | | `rotationSpeed` | `number` | `3` | Maximum angular correction in rad/s. Non-finite values snap instantly. Deserializing JSON that omits the field yields `Infinity`. | `dependencies = [ClingToTerrain, Transform64]`. The system listens for `TRANSFORM64_EVENT_CHANGE` on the entity and queues it whenever the transform is announced, then processes up to `updateBatchLimit` (default 1024) per tick, so a level's worth of static props spreads over several frames. It announces the transform itself after each clamp, so whatever draws the prop follows. It finds the terrain with `obtainTerrain(dataset)`, which returns any single `Terrain` in the dataset. An entity over an unbuilt tile is put back in the queue and retried. ## Grid transform Grid coordinates map to world through `terrain.gridTransform`, rebuilt from `size`, `gridScale` and `gridTransformKind`: | `GridTransformKind` | Scale | Offset | |---|---|---| | `Direct` (default) | `gridScale` | `gridScale / 2` - cell centres land on cell indices | | `Legacy` | `size / (size - 1) * gridScale` | `0` | The grid's origin is a corner, not the centre, and the entity's `Transform64` shifts and scales the whole thing. Offsetting by `(-worldWidth / 2, 0, -worldHeight / 2)` is the usual way to centre a terrain on the origin; a collision `HeightMapShape3D` built for the same field is a separate entity and has to be placed to match. See [Colliders](https://meep.company-named.com/docs/physics/colliders/). ## Serialization `Terrain` has `toJSON()` and `fromJSON(json, engine)` - the second argument is the engine, because deserializing rebuilds the terrain through `engine.assetManager`. The JSON form carries `size`, `scale`, `resolution`, `preview`, heights (base-64 float32), layers, splat weights and the overlay's tile image URL, plus a `material` blob that is stored and handed back untouched; nothing reads it. `TerrainSerializationAdapter` (binary, version 2) is what the engine's own save path uses. It writes the same fields plus a small metadata blob holding `gridTransformKind` and `lightMapURL`. Neither form stores painted overlay cells or cloud state: the overlay is a runtime surface, and `Clouds` is settings that nothing currently draws. --- # Water & overlays Section: World Source: https://meep.company-named.com/docs/world/water/ Description: Author meshlet water surfaces with physical optical media and GPU waves; TerrainOverlay paints per-cell RGBA over the ground. Water surfaces and terrain overlays are separate rendering features. Water uses authored geometry and a physical optical medium; `TerrainOverlay` paints the [Terrain](https://meep.company-named.com/docs/world/terrain/) grid. Cloud shadows are authored settings that nothing renders - see [Cloud shadows](#cloud-shadows). ## Water `Water` holds the surface's index of refraction, roughness, participating medium and hidden-simulation policy. The same entity needs `MeshletGeometry` for its shape and `Transform64` for its placement. `WaterSystem` registers those bodies with the renderer's shared AVBOIT transparency pipeline; it queues authored edits through change signals rather than scanning every body each frame. Four examples each show one part of this: [Shallow to deep](https://meep.company-named.com/examples/water-depth/) fills one body with each medium preset over a sloping bed, [Many waters](https://meep.company-named.com/examples/water-bodies/) runs three bodies at once, [Refraction and reflection](https://meep.company-named.com/examples/water-optics/) puts the optical controls on sliders, and [Splashes](https://meep.company-named.com/examples/water-splash/) drives `splash`. ```js import Water from "@woosh/meep-engine/src/engine/graphics/ecs/water/Water.js"; import { WaterSystem } from "@woosh/meep-engine/src/engine/graphics3/WaterSystem.js"; import { EngineHarness } from "@woosh/meep-engine/src/engine/EngineHarness.js"; const waterSystem = new WaterSystem(engine.graphics, EngineHarness.shadeScene(engine)); await em.addSystem(waterSystem); ``` The component is a **default** export. The system is a **named** export under `src/engine/graphics3/`, and its constructor takes `(graphics, scene)`. Here `engine` and `em` are your running engine and entity manager, and `EngineHarness` is imported from `src/engine/EngineHarness.js`. The system registers `WaterSurfaceExtension` at `FrameStart` to prepare surface data and `WaterExtension` at `BeforePresent` for diagnostics. `EngineHarness.buildTerrain` creates a separate water entity unless you pass `enableWater: false`, and registers the system if necessary. Its plane is twice the terrain size in each horizontal dimension, translated to `(size.x, waterLevel, size.y)`. ### Rendering through AVBOIT `WaterSystem` registers a `GPUWaterRenderer` transparency channel. Water contributes extinction and radiance alongside transparent meshes, particles and trails; the shared AVBOIT resolve composites it once. Keep `renderer.transparency_mode` set to `ShadeTransparencyMode.AVBOIT`: the MBOIT path does not draw this channel. The exported `WaterExtension` runs at `FramePhase.BeforePresent` for optional inspection views. It does not draw the normal water surface. See [Render extensions](https://meep.company-named.com/docs/rendering/render-extensions/). - **Scene depth and water-interface depth are separate.** Water samples opaque scene depth and writes its own interface depth for receiver selection; it does not replace the scene's opaque depth buffer. - **The surface uses meshlet geometry.** The renderer tessellates it on the GPU, with optional wave displacement. Water stays out of the opaque mesh table and its TLAS. - **Edits have explicit notification rules.** `ior.set()` and `roughness.set()` notify automatically. After changing a medium's absorption, priority or lobe fields in place, set `water.medium.needsUpdate = true`. Announce pose edits with `t64_announce_change(ecd, entity)` as for other `Transform64` entities. ### Shape and placement Water does not require a `Terrain`. Its system dependencies are `[Water, MeshletGeometry, Transform64]`; the mesh defines the extent and the transform defines the pose, including parent attachments. A body missing either geometry or transform does not link to the system. Separate entities can have different shapes, placements and optical media. **Author the area with the fewest triangles that cover it.** The renderer tessellates the surface on the GPU from the view, so subdividing a flat area adds no wave detail and costs every frame: the lattice is clipped against each authored triangle, so every internal edge adds clipped cells. A rectangle of water is two triangles. Add triangles only where the area needs them - its outline, a hole, a crease, a change of normal. ### Creating a water body ```js import Water from "@woosh/meep-engine/src/engine/graphics/ecs/water/Water.js"; import WaterWaves from "@woosh/meep-engine/src/engine/graphics/ecs/water/WaterWaves.js"; import { FluidEffectorsComponent } from "@woosh/meep-engine/src/engine/physics/fluid/ecs/FluidEffectorsComponent.js"; import { GlobalFluidEffector } from "@woosh/meep-engine/src/engine/physics/fluid/effector/GlobalFluidEffector.js"; import { Transform64 } from "@woosh/meep-engine/src/engine/ecs/transform/Transform64.js"; import Entity from "@woosh/meep-engine/src/engine/ecs/Entity.js"; import { StandardAttributes } from "@woosh/meep-engine/src/shade/renderer/geometry/StandardAttributes.js"; import { make_plane_geometry } from "@woosh/meep-engine/src/shade/renderer/geometry/primitives/make_plane_geometry.js"; import { meshlet_geometry_build_from_geometry } from "@woosh/meep-engine/src/shade/renderer/geometry/meshlet_geometry_build_from_geometry.js"; import { MeshoptClusterizer } from "@woosh/meep-engine/src/shade/renderer/geometry/meshlet/build/meshoptimizer/meshopt_clusterizer.js"; const water = new Water(); water.ior.set(1.333); water.roughness.set(0.02); await MeshoptClusterizer.ready; const plane = make_plane_geometry(40, 20); const positions = plane.getAttribute(StandardAttributes.Position).data; const normals = plane.getAttribute(StandardAttributes.Normal).data; // Plane geometry starts in XY; author the rest surface in local XZ, facing up. for (let i = 0; i < positions.length; i += 3) { positions[i + 2] = -positions[i + 1]; positions[i + 1] = 0; normals[i] = 0; normals[i + 1] = 1; normals[i + 2] = 0; } const geometry = meshlet_geometry_build_from_geometry(plane); const transform = new Transform64(); transform.setTranslation(20, 2, 10); const waves = new WaterWaves(); waves.shoreReflection.set(0.3); const entity = new Entity().add(transform).add(geometry).add(water).add(waves).build(ecd); // The wind that raises the waves is the scene's: a GlobalFluidEffector, 3 m/s towards +X+Z. // Needs FluidEffectorsSystem and GPUFluidSystem registered (EngineHarness's water setup adds the latter). const weather = new GlobalFluidEffector(); weather.wind = [3 * Math.SQRT1_2, 0, 3 * Math.SQRT1_2]; weather.drag = 1; const effectors = new FluidEffectorsComponent(); effectors.addEffector(weather); new Entity().add(effectors).build(ecd); ``` | Property | Type | Default | Description | |---|---|---|---| | `ior` | `Vector1` | `1.333` | Air-to-water index of refraction; the system clamps it to at least 1. | | `roughness` | `Vector1` | `0.02` | Perceptual surface roughness before unresolved wave slope variance is added; clamped to `[0, 1]`. | | `medium` | `ParticipatingMedium` | `open_ocean` | RGB absorption and scattering lobes, with coefficients in inverse metres. | | `simulateWhenHidden` | `ObservedBoolean` | `false` | Keep wave particles advancing while no view sees the body. Ambient waves follow time either way. | `Water.toJSON()` / `fromJSON()` carry `ior`, `roughness`, the optical medium and `simulateWhenHidden`. `WaterSerializationAdapter` uses binary version 5; the `4 → 5` upgrader preserves the optics and sets `simulateWhenHidden` to `false`. Save geometry and placement as the other components on the entity. `WaterWaves` has its own JSON and binary adapter (version 2), storing upwind fetch and shore reflection. Its `1 → 2` upgrader drops the wind speed and direction that version 1 stored; the wind is saved with the scene's `GlobalFluidEffector`s. **Legacy placement needs a scene migration.** JSON containing `level` or `size` throws, and the binary `3 → 4` upgrader deliberately throws because a component upgrader cannot create the required geometry and transform. Convert the old water entity to `Water` + `MeshletGeometry` + `Transform64` before loading it with this format. Old body and shore colours are not physical medium coefficients. ### Refraction, reflection and absorption For each visible water interface: 1. **Surface coverage** comes from the transformed mesh and GPU tessellation, with optional simulated wave displacement. 2. **Refraction** traces from the optical normal into the opaque scene using depth and the hierarchical depth buffer. The accepted receiver supplies a displaced colour lookup and an underwater path length. Refraction fades toward the original lookup near screen edges and uncertain coverage. 3. **Reflection** traces screen-space geometry and falls back to the environment map. `ior` controls Fresnel reflection; `roughness` and unresolved wave slopes control its roughness. 4. **The medium** supplies absorption, scattering and phase functions for transmission and in-scattered radiance. Choose a physical preset or author coefficients rather than tinting a deep-water or shore colour. 5. **Composition** publishes that transmission and radiance into the shared AVBOIT accumulators, so other transparent content participates in the same resolve. `waterSystem.settings.enabled` can disable the channel, and `settings.reflections` is an integer switch (`1` by default). `settings.max_distance` defaults to 300 world units and limits tracing distance. These are renderer settings, separate from the serializable `Water` component. ### Optical presets and waves `water_medium_preset({ preset })`, exported by `src/shade/renderer/medium/water/water_presets.js`, builds a `ParticipatingMedium` for `swimming_pool`, `clear_ocean`, `open_ocean`, `coastal`, `tropical_lagoon`, `green_lake` or `turbid_river`. Assign the result to `water.medium`; replacement notifies the system. Preset fitting is an authoring operation, so do it once rather than every frame. A lagoon's shallow sand bottom belongs to the scene, not its optical preset. `WaterWaves` is optional. Without it, the body has no wind-driven waves, but can still receive splashes. With it, the wind drives a fetch-limited JONSWAP spectrum: the same wind raises different waves on a small pool and an open sea. Its fields are `Vector1`s; edit them with `.set()` to notify the system. **The wind is the scene's, not the body's.** Every body reads the published wind field 10 m above its own origin, low-passed on the GPU, so direction changes blend over a few seconds. That field is the far field of the scene's `GlobalFluidEffector`s, folded by `FluidEffectorsSystem` and published by `GPUFluidSystem` (see [the scene's wind](https://meep.company-named.com/docs/physics/fluid/#the-scenes-wind)); a scene without them has still air and no wind waves. Two bodies in one scene feel the same wind and differ by their fetch. | Property | Default | Meaning | |---|---|---| | `upwindFetch` | `0` | Metres of open water upwind of the mesh, added to its own extent along the wind. Leave at zero for a bounded pool or lake. | | `shoreReflection` | `0.5` | Amplitude reflection coefficient at the mesh outline: 0 absorbs wave particles, 1 reflects them fully. Bodies without `WaterWaves` use 0.5. | `waterSystem.splash(entity, [x, y, z], radius, strength)` queues wave particles with a world-space radius (half their wavelength) and a vertical velocity kick in metres per second. The position is interpreted using the entity's CPU-owned pose; use it while that pose is CPU authoritative. The GPU consumes at most sixteen queued splashes per body per frame. By default, hidden bodies pause their wave particles. Set `water.simulateWhenHidden.set(true)` when those must continue off camera; this costs the body's simulation work even while hidden. ### Sampling the water surface (GPU readback) `WaterSystem` provides an asynchronous GPU readback API for buoyancy and gameplay code that needs the displaced surface height and world-space normal at batches of points on a water body: ```js import { GPUReadbackStatus } from "@woosh/meep-engine/src/shade/renderer/buffer/table/GPUReadbackStatus.js"; import { WATER_QUERY_SAMPLE_FLOATS } from "@woosh/meep-engine/src/shade/renderer/water/query/GPUWaterQueries.js"; const target = new Float32Array(2 * WATER_QUERY_SAMPLE_FLOATS); // Query 2 world-space points [x0, y0, z0, x1, y1, z1] with a 0.5 m spatial filter footprint: const handle = waterSystem.request_world(entity, [10, 0, 10, 12, 0, 10], 2, 0.5, target, 0); // On a subsequent tick (after WaterSystem.update()): if (waterSystem.status[handle] === GPUReadbackStatus.Delivered) { const worldY0 = target[0], nx0 = target[1], ny0 = target[2], nz0 = target[3]; } ``` - `waterSystem.request_local(entity, local_xz, count, footprint, target, target_offset)` - queries `count` points given as interleaved `[x0, z0, x1, z1, ...]` in the water body's local `(x, z)` plane. `footprint` is the spatial filter width in metres (`0` resolves all wavelengths). Each sample unpacks `WATER_QUERY_SAMPLE_FLOATS` (`4`) floats into `target` starting at `target_offset`: `[world_height, nx, ny, nz]`. Points outside the mesh outline or inside island holes are clamped continuously to the nearest point on the mesh's triangles so `NaN`s are never produced. - `waterSystem.request_world(entity, world_xyz, count, footprint, target, target_offset)` - transforms `count` world-space `[x, y, z]` points into the water body's local `(x, z)` plane using the inverse of its CPU-owned `Transform64` and delegates to `request_local`. - `waterSystem.status` - a `Uint8Array` indexed by the handle returned from `request_local` / `request_world`, holding a `GPUReadbackStatus` (`Pending` until answered at `WaterSystem.update()`, then `Delivered` or `Dropped` for one tick before reverting to `None` when the handle is recycled). Read `waterSystem.status` fresh each tick rather than caching the typed array reference, as it is reallocated when handle capacity grows. When running headless (no GPU scene context), requests are answered on the next `update()` from the water body's rest surface. ## Terrain overlays `TerrainOverlay` is a per-cell RGBA image the size of the terrain grid, blended over the splat layers by `TerrainShadeMaterial` during G-buffer shading. It is reached through `terrain.overlay` - there is no separate ECS component. It is two textures. The **cell map** is one RGBA texel per grid cell, read with `textureLoad` and clamped, so cells stay crisp. The **cell sprite** is a single image repeated inside every cell that has colour. A cell's colour tints the sprite; a cell the game left transparent draws nothing at all, and so does a sprite texel with alpha at or below 0.01. The tinted result is composited over the splat colour as a straight `over`, in linear light. That makes it a natural fit for turn-based movement ranges, threat maps and tile-selection UI: the game paints cells, and the sprite decides what a painted cell looks like. ```js import Vector4 from "@woosh/meep-engine/src/core/geom/Vector4.js"; const overlay = terrain.overlay; overlay.paintPoint(12, 8, new Vector4(1, 0, 0, 0.6)); // grid coordinates overlay.paintPointAlphaBlend(12, 8, new Vector4(0, 1, 0, 0.4)); overlay.clearPoint(12, 8); overlay.push(); // snapshot and clear - e.g. while showing a build preview // ... draw the preview ... overlay.pop(); // restore // The per-cell sprite. Loaded through the asset manager as GameAssetType.Image. overlay.baseTileImage = "./textures/grid-tile.png"; ``` | Method | Description | |---|---| | `paintPoint(x, y, vec4)` | Write RGBA (float 0-1) into grid cell `(x, y)`. | | `paintPointAlphaBlend(x, y, vec4)` | Alpha-blend over the cell's existing value. | | `clearPoint(x, y)` | Zero the cell. | | `readPoint(x, y, result)` | Read the cell's RGBA into a `Vector4`. | | `writeData(uint8Array)` | Replace the whole overlay with raw RGBA bytes. Length must match exactly. | | `clear()` | Zero everything. | | `push()` | Snapshot the cells, sprite URL and border width, then clear the overlay. | | `pop()` | Restore the top snapshot, resizing the overlay back if it changed. | | `update()` | Bump the sampler version after writing through `overlay.sampler` yourself. | The per-cell writes, `writeData` and `clear` all bump the sampler version themselves, which is what makes the terrain material re-upload the texture. `update()` is only for a caller that reached into `overlay.sampler.data` directly. `overlay.canvas` throws - use `overlay.sampler`. `paintSampler(src, dx, dy, dw, dh)` and `paintImage(canvas, ...)` are on the class but **write nothing**: both hand the blitter the `TerrainOverlay` rather than `overlay.sampler`, and the overlay has no `width`, `read` or `write`, so the copy loop's bounds come out `NaN` and it never runs. To blit a region, scale into `overlay.sampler` yourself and call `update()`. `baseTileImage` defaults to a white-pixel data URL, which the system holds as pixels rather than decoding, so an overlay with no authored sprite is just the cell colours. Changing it reloads through the asset manager, and a change that lands while a previous load is still in flight is discarded. **`overlay.borderWidth` is inert.** The WGSL grid overlay has no border uniform: the border is whatever the cell sprite's own alpha draws. The field round-trips, but writing to it changes nothing. ## Cloud shadows Every `Terrain` constructs a `Clouds` (`terrain.clouds`), enabled by default, and **nothing draws it**: nothing in the renderer reads its values. What it holds is settings: `enabled`, `variability`, `setSpeed(x, y)` and an accumulated `time`. The section exists because the class ships, every terrain owns one, and code that reads or writes `terrain.clouds` compiles - the honest answer to "why is nothing happening" is more useful than silence. Treat it as authored data with no consumer. One further detail: `clouds.time` is advanced by `Terrain.update(timeDelta)`, which the drawing `TerrainSystem` does not call, so the clock does not run. --- # Grass Section: World Source: https://meep.company-named.com/docs/world/grass/ Description: GPU grass grown on mesh entities - GrassSurface groups ground meshes, GroundCover says what grows on each, GrassSpecies describes the plant in SI units; blades bend in the scene's wind and are pressed by obstacles. Grass grows on ordinary mesh entities. Three components describe it, and the renderer does the rest on the GPU: it samples the ground on a lattice, bakes the tiles a view looks at, and draws individual blades that sway in the [scene's wind](https://meep.company-named.com/docs/physics/fluid/#the-scenes-wind) and are pressed flat by obstacles. | Component | On | Says | |---|---|---| | `GrassSurface` | any entity with a `Transform64` | this entity's frame is a surface: its ground is sampled as one lattice, along the frame's up axis | | `GroundCover` | a mesh entity (`ShadedGeometry` + `Transform64`) | which surface the mesh is ground of, what grows on it, and how densely | | `GrassSpecies` | shared by covers, not an entity | the plant: blade length and width, blades per m², colours, lean, curl, stiffness, turbulence, recovery time | ## Setup ```js import { GrassSpecies } from "@woosh/meep-engine/src/engine/graphics/ecs/grass/GrassSpecies.js"; import { GrassSurface } from "@woosh/meep-engine/src/engine/graphics/ecs/grass/GrassSurface.js"; import { GroundCover } from "@woosh/meep-engine/src/engine/graphics/ecs/grass/GroundCover.js"; import { GrassSurfaceSystem } from "@woosh/meep-engine/src/engine/graphics3/GrassSurfaceSystem.js"; import { GroundCoverSystem } from "@woosh/meep-engine/src/engine/graphics3/GroundCoverSystem.js"; em.addSystem(new ShadedGeometrySystem(engine.graphics, scene)); em.addSystem(new GrassSurfaceSystem(engine.graphics, scene)); em.addSystem(new GroundCoverSystem()); // needs the GrassSurfaceSystem on the same manager const meadow = GrassSpecies.from({ blade_length: 0.4, blade_width: 0.015, density: 300 }); const field = new Entity() .add(new Transform64()) .add(new GrassSurface()) .build(ecd); new Entity() .add(groundTransform) .add(groundShadedGeometry) .add(GroundCover.from({ surface: field, species: meadow })) .build(ecd); // a rock on the field: hides the ground under it, grows nothing new Entity() .add(rockTransform) .add(rockShadedGeometry) .add(GroundCover.from({ surface: field, species: null })) .build(ecd); ``` **Membership is its own relation.** `GroundCover.surface` says which surface a mesh is sampled with, and nothing about where the mesh is (`TransformAttachment`) or how long it lives (`ParentEntity`). A meadow of loose meshes is one surface without a transform parent. A mesh that carries both components and names itself is a surface of one. A surface that moves as one carries its grass with it, and nothing is re-baked. `surface` must not change while the component is attached: remove the component and add it back to move a mesh to another surface. **A member with no species only hides ground** - a boulder, a path, the floor of a building. Nothing grows on it or through it, and it hides the ground of other members under it. **Density is painted.** The red channel of the geometry's vertex colour scales how densely the species grows across the mesh (1 where there is no vertex colour), and `GroundCover.density` (0 to 1) scales that. After editing a `GroundCover` or a `GrassSpecies` in place, dispatch its `onChanged`. Nothing is rewritten per frame; links, unlinks, announced edits and announced moves queue the work. ## Wind and pressing Blades bend in the scene's wind field with the same drag law the foliage rig uses, so register `GPUFluidSystem` and a `GlobalFluidEffector` (see [Fluid](https://meep.company-named.com/docs/physics/fluid/#the-scenes-wind)) for grass that moves. `GrassSpecies.turbulence` adds sway the wind field does not resolve, and `elastic_modulus` with `blade_depth` set how stiff a blade is. Solid obstacles in the GPU fluid press grass down: an entity with a `FluidObstacle`, a `Collider` and a `RigidBody` flattens the blades under it, and they stand back up over `GrassSpecies.recovery_time` seconds. A porous obstacle (`FluidObstacle.drag` above 0) presses nothing: the air passes through it, and so does the grass. `grass_system.blades.press.enabled` switches pressing off, and `press.spacing` (0.125 m) sets how fine its edge is. ## Quality settings `grass_system.surfaces.settings` is a `GrassSurfaceSettings`. `surfaces` and `blades` are `null` until the scene has a GPU context. | Setting | Default | Meaning | |---|---|---| | `finest_spacing` | `0.125` | distance between the finest lattice's columns, world units: how exactly blade roots follow the ground | | `narrowest_blade` | `1.5` | least blade width drawn, in render-resolution pixels; picks each distance's lattice level | | `shortest_blade` | `2` | least blade length drawn, in pixels; no tile is asked for past that distance | | `bake_capacity` | `64` | most tile layers baked per view per frame: how fast newly seen ground gets grass | | `canopy_opacity` | `6` | blades a view ray may cross before the grass behind is left out; lower shows more ground at grazing angles | --- # Rendering overview Section: Rendering Source: https://meep.company-named.com/docs/rendering/overview/ Description: Meep's renderer is GPU-driven, visibility-buffer deferred and WebGPU only. This page maps what that means for game code, how the ECS binds to it, and what a frame contains. meep renders with its own renderer, in-tree under `src/shade/`. There is no WebGL path and no second backend. It is GPU-driven and visibility-buffer deferred, which changes what a game's code is responsible for: you describe content, and the renderer decides what is drawn, in what order, and whether it is culled. This page is the map of that; the linked pages cover each piece in depth. ## What the renderer is **A GPU-driven, visibility-buffer deferred renderer on WebGPU.** Geometry is clustered into meshlets ahead of time and lives GPU-resident in one large 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 (TAA, or the bundled NSS neural upscaler), tonemapped and presented. Three consequences shape everything else: - **A mesh is a small GPU-resident record, not a draw call you own.** You add a `Mesh` to a `Scene`, or a `ShadedGeometry` component to an entity, and that is the whole of your involvement in submission. There is no render layer to assign, no visibility list to maintain, no CPU frustum cull to configure, and no draw order to influence. - **Preparing geometry is a precompute.** `meshlet_geometry_build_from_geometry` runs once per shape, when content is created or loaded - never per frame. Content whose vertices are rewritten every frame (paths, debug lines) goes down a separate dynamic-mesh path instead. - **The frame is a closed sequence with declared injection points.** You do not insert a pass wherever you like; you register a `RenderExtension` against one of six `FramePhase`s. See [Render extensions](https://meep.company-named.com/docs/rendering/render-extensions/). ## WebGPU, and the device floor The renderer requires a WebGPU device that meets a fixed floor. There is no feature detection past it, no fallback, and no branch that produces a lesser frame - hardware below the floor is told clearly that it cannot run this. | Requirement | Value | |---|---| | Adapter feature | `indirect-first-instance` - indirect draw is used throughout | | Adapter feature | `float32-blendable` - the MBOIT transparency mode blends into 32-bit float targets | | Adapter feature | `texture-formats-tier1` - the hierarchical Z buffer is reduced in compute into `rg16float` storage textures | | Adapter limit | `maxStorageBuffersPerShaderStage` >= 10 | | Adapter limit | `maxColorAttachmentBytesPerSample` >= 32 - the G-buffer is wide | | Taken when offered | `timestamp-query`, `subgroups`, `texture-compression-bc`, `texture-compression-etc2`, `texture-compression-astc` - never required | The whole floor is checked against the adapter before a device is requested (`src/shade/device/SHADE_DEVICE_FLOOR.js` holds it), so a refusal names every gap at once. The adapter is requested with `powerPreference: "high-performance"`. A fallback (software) adapter logs a warning and proceeds. In practice there is one more requirement the floor cannot express: the engine's shaders use the WGSL `immediate_address_space` extension, which shipped in Chrome 149/150. An older Chromium acquires a device that passes every check above and then fails to dispatch shaders. ### How startup fails `Renderer.initialize()` rejects, and not everything it rejects with is a `ShadeDeviceFailure`: | Situation | Thrown | |---|---| | `navigator.gpu` is absent - WebGPU disabled or unsupported | `ShadeDeviceFailure`, `WebGPUUnavailable` | | No `context` passed, and the canvas `initialize()` creates returned `null` from `getContext("webgpu")` | a plain `Error` | | No adapter, or an adapter below the floor | `ShadeDeviceFailure`, `AdapterUnavailable` or `BelowFloor` | | `adapter.requestDevice()` rejected | `ShadeDeviceFailure`, `DeviceRequestFailed` | `ShadeDeviceFailure` (`src/shade/device/ShadeDeviceFailure.js`, named export) extends `Error`. Its `message` is written to be shown as it is, and names the specifics a person can act on - every feature and limit the hardware lacks, what the browser refused; `detail` holds those specifics alone, for a host that phrases its own message; `reason` is a `ShadeDeviceFailureReason`: | Reason | Meaning | |---|---| | `WebGPUUnavailable` | no `navigator.gpu` at all | | `AdapterUnavailable` | WebGPU is present but would not hand over an adapter | | `BelowFloor` | an adapter that misses the floor; the whole floor is checked before a device is requested, so `detail` lists every feature and limit it misses, with the adapter's numbers | | `DeviceRequestFailed` | the adapter was acceptable but the device request failed; `detail` is what the browser said | | `DeviceLost` | a working device went away while running | The engine path - `GraphicsEngine.start()` - always passes `initialize()` a context of its own canvas, so every startup failure of a browser or a GPU arrives there as a `ShadeDeviceFailure`, an old browser included. Anything else that breaks arrives as whatever was thrown, so test `isShadeDeviceFailure` before reading `reason`. Through the engine, this arrives as a signal. `GraphicsEngine.start()` raises `on.contextFailed` with the failure and then rethrows, so a caller that wants to handle it can and one that does not still fails loudly: ```js import { ShadeDeviceFailureReason } from "@woosh/meep-engine/src/shade/device/ShadeDeviceFailureReason.js"; engine.graphics.on.contextFailed.add(failure => { if (failure.isShadeDeviceFailure !== true) { // not a device failure; it carries no `reason` reportStartupFailure(failure); return; } if (failure.reason === ShadeDeviceFailureReason.WebGPUUnavailable) { suggestBrowserUpgrade(); } else if (failure.reason === ShadeDeviceFailureReason.BelowFloor) { reportUnsupportedHardware(failure.detail); // every unmet requirement, '; '-separated } }); ``` `Engine` subscribes to `contextFailed` itself: it pauses the simulation and adds `GraphicsContextFailureView` (`src/view/graphics/GraphicsContextFailureView.js`, named export) to the view stack, titled "Graphics unavailable" with the failure's `message` as its text, so an unhandled failure still puts the message on screen instead of burning cycles invisibly. Application state is left intact, which keeps a save-on-failure handler viable. ### A lost device is not recovered A device lost while running arrives on `engine.graphics.on.contextLost`, carrying a `ShadeDeviceFailure` with reason `DeviceLost`. **Nothing renders after this.** Every buffer, texture and pipeline lived on that device and went with it; the honest response is to say so and reload. `on.contextRestored` exists because the contract has it, but it **never fires** - a subscriber there is waiting for something that will not happen. `Engine` tolerates the outage for two seconds and then pauses the simulation, on the assumption that a player who cannot see anything should not have the world run on without them. It does not install a failure view on this path, so telling the player is yours to do. ## How the ECS binds to the renderer `engine.graphics` is a `GraphicsEngine` (`src/engine/graphics3/GraphicsEngine.js`, named export). `Engine` constructs it; you never do. It is deliberately a narrow facade rather than a renderer handle: the seam `Engine` needs in order to boot, plus a short list of things let through by name. | Member | What it is | |---|---| | `set_scene(scene)` | Draw this renderer `Scene` from now on. If the scene has no environment map, its atmosphere is turned on (`scene.atmosphere.enable_by_default()`), because the renderer lights with indirect by default and a scene with neither renders unlit. | | `set_environment_map(texture)` | Give the scene an environment map, which takes over the sky and the image-based light from the scene's atmosphere. The texture must be **octahedral**; there is no prefilter step, and the assignment is safe before startup as well as after. It writes into whichever scene the facade currently holds, so call it *after* `set_scene`. There is deliberately no `set_environment_texture` - the map is the background too. See [Sky & environment](https://meep.company-named.com/docs/rendering/sky/). | | `add_extension(ext)` / `remove_extension(ext)` / `extension_count(phase)` | Register work into the frame. Extensions are held on the facade and re-applied after a restart, so **registering does not require a device**. | | `scene_context(scene)` | The renderer's per-scene GPU state and the managers hanging off it (the animation manager above all). `null` while there is no device; a restart builds a **new** context, so ids issued by the old one are stale. | | `renderer` | The escape hatch. Hands out the `Renderer` itself, `null` before `start()` and after `stop()`. Everything the members above are shaped to avoid is reachable through it - frame features, post-process settings, `render_to_target`. | | `normalizeViewportPoint(input, result)` | Viewport pixels (origin top-left) to clip space, -1..1, +Y up. | | `viewportProjectionRay(x, y, source, direction)` | A world-space ray from the eye through a clip-space point. `x`/`y` are clip space, which is what `normalizeViewportPoint` produces. This is the renderer's whole contribution to gameplay picking. | | `render_to_sampler(scene, camera, w, h)` | Tooling-only GPU readback for thumbnails. Resizes the renderer for the call and puts it back. | | `dynamic_resolution` | The `DynamicResolutionScaling` instance, already wired to `renderer.internal_resolution_scale`. It targets 30 fps, so on hardware that clears the budget it never engages. | Five signals sit on `engine.graphics.on`: | Signal | Fires | |---|---| | `preRender` | camera matrices are final, the frame has not been submitted | | `postRender` | the frame has been submitted - submitted, not finished; the GPU is still working | | `contextLost` | the device was lost, carrying a `ShadeDeviceFailure` | | `contextRestored` | never | | `contextFailed` | there will be no rendering, carrying a `ShadeDeviceFailure` | **The lifecycle is symmetric.** `GraphicsEngine` starts from `Engine.start()` and stops from `Engine.stop()`, so `start -> stop -> start` returns a working renderer. ### The scene, and the black-frame trap There is one `Scene` per engine and `EngineHarness.shadeScene(engine)` hands it out - built on first ask and cached against the engine. Every system that needs a scene should ask for it here rather than constructing its own, or entities end up in scenes nobody draws. Only three systems call `set_scene` themselves: `LightSystem`, `MeshSystem` and `ParticipatingMediaSystem`. **An app that registers `ShadedGeometrySystem` alone and never calls `set_scene` gets a black frame** - the renderer is running, the meshes exist, and nothing has told the facade what to draw. There is no warning; the picture is simply empty. ```js import { EngineHarness } from "@woosh/meep-engine/src/engine/EngineHarness.js"; import { LightSystem } from "@woosh/meep-engine/src/engine/graphics3/LightSystem.js"; import { ShadedGeometrySystem } from "@woosh/meep-engine/src/engine/graphics3/ShadedGeometrySystem.js"; const engine = await EngineHarness.bootstrap({ configuration(config, engine) { const scene = EngineHarness.shadeScene(engine); // LightSystem calls set_scene, so this wiring is complete config.addSystem(new LightSystem(engine.graphics, scene)); config.addSystem(new ShadedGeometrySystem(engine.graphics, scene)); // without a LightSystem / MeshSystem, say it yourself: // engine.graphics.set_scene(scene); } }); ``` ## The frame Six phases, in the order they occur. Each names a moment where a specific set of frame records exists and is stable. ```pintora activityDiagram start :FrameStart - view only, no records; :rasterize visibility buffer and G-buffer; :AfterGBuffer - GBufferTextures, ViewTextures; :GTAO, froxel lighting, deferred resolve, volumetrics; :AfterLighting - SceneColor; :transparency; :AfterTransparency - whole scene, HDR, internal resolution; :TAA or NSS upscale, DoF, motion blur, sharpen, bloom; :BeforePresent - HDR, output resolution; :tonemap; :Overlay - PresentTarget, display space; end ``` | Phase | Records carried | What belongs here | |---|---|---| | `FrameStart` | none | per-frame GPU compute later phases depend on - a custom cull, a procedural buffer build | | `AfterGBuffer` | `GBufferTextures`, `ViewTextures` | surface work. The one phase where the G-buffer may be published into - projected decals | | `AfterLighting` | the above, plus `SceneColor` | custom work that transparent surfaces should blend over | | `AfterTransparency` | same | the default. Drawing into the scene: paths, outlines, gizmos | | `BeforePresent` | same | full-screen effects needing the finished image as input, still HDR, at output resolution | | `Overlay` | `PresentTarget` only | interface drawn onto the canvas in display space | **The upscale is a phase boundary and it is the one thing about the frame you cannot assume away.** `AfterGBuffer`, `AfterLighting` and `AfterTransparency` run at the internal render resolution; `BeforePresent` and `Overlay` are on the far side of TAA/NSS at output resolution. With `feature_taa_enabled === false` there is no upscale at all and the two sides match. Never state a resolution as a constant - ask `frame.resolution`, which is derived from the live handle. `SceneColor` is deliberately not carried at `Overlay`: the canvas is written there and a texture cannot be a render attachment and a sampled source in the same pass. [Render extensions](https://meep.company-named.com/docs/rendering/render-extensions/) covers the mechanism - the records, ordering, and the extensions that ship. ## The rendering systems Rendering systems live in `src/engine/graphics3/`, are **named** exports, and take explicit collaborators rather than the engine. Most register a render extension at startup and remove it at shutdown. Import as `@woosh/meep-engine/src/engine/graphics3/`. | System | Module | Constructor | Draws | |---|---|---|---| | [`MeshSystem`](https://meep.company-named.com/docs/rendering/meshes-materials/) | `MeshSystem.js` | `(graphics, scene, load)` | nothing itself - loads `SGMesh` models through `load(url)` and spawns them as entities that the systems below draw. Calls `set_scene` | | [`ShadedGeometrySystem`](https://meep.company-named.com/docs/rendering/meshes-materials/) | `ShadedGeometrySystem.js` | `(graphics, scene)` | one `meshes` row per `ShadedGeometry` entity | | [`MeshSkinSystem`](https://meep.company-named.com/docs/animation/skeletons/#who-registers-what) | `MeshSkinSystem.js` | `(graphics, scene)` | nothing itself - registers each `MeshSkin` and binds its mesh, so a skinned primitive deforms | | [`LightSystem`](https://meep.company-named.com/docs/rendering/lights-shadows/) | `LightSystem.js` | `(graphics, scene)` | the scene's lights and shadow fitting. Calls `set_scene` | | `CameraSystem` | `CameraSystem.js` | `(graphics)` | nothing - drives the render camera from `Camera` + `Transform64` | | [`TerrainSystem`](https://meep.company-named.com/docs/world/terrain/) | `TerrainSystem.js` | `(graphics, scene, assetManager)` | tile entities with a splat material; requires `ShadedGeometrySystem` | | [`WaterSystem`](https://meep.company-named.com/docs/world/water/) | `WaterSystem.js` | `(graphics, scene)` | meshlet water surfaces in the shared AVBOIT transparency resolve | | [`DecalSystem`](https://meep.company-named.com/docs/rendering/effects/) | `DecalSystem.js` | `(graphics, assets)` | projected decals into the G-buffer, at `AfterGBuffer`, after terrain | | [`OutlineSystem`](https://meep.company-named.com/docs/rendering/effects/#outlines) | `OutlineSystem.js` | `(graphics, scene, assets)` | draws the outlines, at `AfterTransparency`; fed by `SGMeshOutlineSystem` (`Outline` + `SGMesh`) and `ShadedGeometryOutlineSystem` (`Outline` + `ShadedGeometry`) | | [`GPUParticleEmitterSystem`](https://meep.company-named.com/docs/rendering/particles/#shades-gpu-particle-system) | `GPUParticleEmitterSystem.js` | `(graphics, scene, assets)` | loads and publishes the sprite atlas at `FrameStart` for the renderer's GPU particle nodes | | [`Trail3DSystem`](https://meep.company-named.com/docs/rendering/trails/) | `Trail3DSystem.js` | `(graphics, scene)` | trail tubes, simulated on the GPU and drawn inside the transparency pipeline | | `PathDisplaySystem` | `PathDisplaySystem.js` | `(graphics)` | tubes along `PathDisplay` + `Path` entities, at `AfterTransparency` | | `DebugDrawSystem` | `DebugDrawSystem.js` | `(graphics)` | whatever `Gizmo` recorded this frame, at `AfterTransparency`, last | | [`ParticipatingMediaSystem`](https://meep.company-named.com/docs/rendering/sky/) | `ParticipatingMediaSystem.js` | `(graphics, scene)` | volumetric media. Calls `set_scene` | | [`VolumetricLightMapSystem`](https://meep.company-named.com/docs/rendering/global-illumination/) | `VolumetricLightMapSystem.js` | `(graphics, scene)` | nothing - uploads a baked Brick4 lightmap into the scene's context | | [`AnimationSystem`](https://meep.company-named.com/docs/animation/skeletons/) | `AnimationSystem.js` | `(graphics, scene)` | nothing - plays clips on `Animation` + `AnimationClips` entities | | [`AnimationGraphSystem`](https://meep.company-named.com/docs/animation/graphs/) | `AnimationGraphSystem.js` | `(graphics, scene)` | nothing - evaluates `AnimationGraphController` + `AnimationClips` entities | | [`PickingSystem`](https://meep.company-named.com/docs/rendering/picking/) | `PickingSystem.js` | `(graphics)` | nothing - async, batched visibility-buffer reads for `Pickable` entities | | `TooltipComponentSystem` | `TooltipComponentSystem.js` | `({ graphics, tooltips, pointer, localization, picking })` | nothing - DOM tooltips over picked entities | `Engine` registers none of these; it only constructs `GraphicsEngine`. `EngineHarness.buildBasics` registers `CameraSystem` and `LightSystem`, plus `TerrainSystem` and `WaterSystem` when terrain is enabled - but never a mesh system, which is why a harness app that wants to draw models registers `MeshSystem` and `ShadedGeometrySystem` itself - and `MeshSkinSystem` when a model is skinned. ## What is deliberately absent | | | |---|---| | **No `getRenderer()`** | The facade's `renderer` getter is an escape hatch, not a pattern. | | **No `pixelRatio`** | Render scale is the renderer's `internal_resolution_scale`: the frame is rendered smaller and upscaled by TAA, not stretched by the browser from a smaller canvas. | | **No layers** | CPU visibility died with GPU culling. There is nothing to assign a mesh to and nothing to toggle per camera. | | **No `graphics.scene`** | Entities reach the scene through the mesh system, not through the facade. | | **No material manager** | There is exactly one shipping PBR material class, `StandardShadeMaterial`. Nothing registers, compiles or caches materials on your behalf. Streaming its textures is opt-in per material - see [Virtual texturing](https://meep.company-named.com/docs/rendering/virtual-texturing/). | | **No WebGL, no second backend** | One target, WebGPU. There is no seam where another would go. | | **No degradation tiers** | One pipeline. Individual features switch off (`feature_shadows_enabled`, `feature_taa_enabled`, the resolution scale) but there is no low-quality build of the frame. | | **No Draco** | `KHR_texture_basisu` (KTX2, ETC1S or UASTC) is read and transcoded and meshopt-compressed bufferViews are decoded; `KHR_draco_mesh_compression` is not - see [Meshes & materials](https://meep.company-named.com/docs/rendering/meshes-materials/). | | **No LOD and no impostors** | Meshlet culling is what stands in their place. | ## Where to go next The rest of this section, in reading order: - [Meshes & materials](https://meep.company-named.com/docs/rendering/meshes-materials/) - `ShadedGeometry`, geometry vs meshlet geometry, `StandardShadeMaterial`, textures. - [Lights & shadows](https://meep.company-named.com/docs/rendering/lights-shadows/) - the `Light` component, photometric units, froxel binning, cascades. - [Sky & environment](https://meep.company-named.com/docs/rendering/sky/) - the scene's atmosphere, the octahedral environment map that replaces it as both the IBL source and the background, and volumetric fog. - [Global illumination](https://meep.company-named.com/docs/rendering/global-illumination/) - `indirect_lighting_mode`, the real-time probe modes, the Brick4 bake, and the `VolumetricLightMap` component. - [Effects](https://meep.company-named.com/docs/rendering/effects/) - decals, outlines, camera shake, and the dynamic-mesh path. - [Particles & VFX](https://meep.company-named.com/docs/rendering/particles/) - ParticleEffect components, GPU simulation graphs and shared texture atlases. - [Trails](https://meep.company-named.com/docs/rendering/trails/) - `Trail3D`, and why `Trail2D` renders nothing. - [Virtual texturing](https://meep.company-named.com/docs/rendering/virtual-texturing/) - `material.vt_stack`, streamed pages, and the residency loop. - [Picking](https://meep.company-named.com/docs/rendering/picking/) - `PickingSystem`, the async batched ray query. - [Render extensions](https://meep.company-named.com/docs/rendering/render-extensions/) - the frame records, phase ordering, and putting your own pass in the frame. - [Frame settings & post-processing](https://meep.company-named.com/docs/rendering/frame-features/) - the `renderer.feature_*` switches, upscaling, and the post-process sub-objects. Terrain and water are rendering systems too, but they are documented with the rest of the world content: [Terrain](https://meep.company-named.com/docs/world/terrain/) and [Water & overlays](https://meep.company-named.com/docs/world/water/). --- # Meshes & materials Section: Rendering Source: https://meep.company-named.com/docs/rendering/meshes-materials/ Description: The renderer's geometry, material and texture types, the meshlet build that turns one into the other, and the ShadedGeometry component that gives a single primitive a row in the scene. A drawable is three things: a **`MeshletGeometry`** (what to draw), a **`ShadeMaterial`** (how to shade it) and a **`Transform64`** (where it is). `ShadedGeometry` is the ECS component that pairs the first two, and `ShadedGeometrySystem` gives every entity carrying it one row in the renderer's `Scene`. There is no CPU-side machinery around them: no BVH to keep fed, no frustum-culling pass you can query, no `raycast` on the system, and no draw-method optimiser promoting repeated geometry to hardware instancing. Culling, occlusion and instancing all happen on the GPU from meshlet clusters, so the only thing for you to do is hand the renderer a shape and a material. ## Geometry: two types, one of them a precompute ```pintora activityDiagram start :make_box_geometry, or a glTF primitive; :Geometry - named attributes over typed arrays; :meshlet_geometry_build_from_geometry - once, per shape; :MeshletGeometry - clusters, encoded attributes, BVH; :ShadedGeometry.from, plus a Transform64; :ShadedGeometrySystem gives it a row in the Scene; end ``` ### `Geometry` - the authoring form ```js import { Geometry } from "@woosh/meep-engine/src/shade/renderer/geometry/Geometry.js"; import { Attribute } from "@woosh/meep-engine/src/shade/renderer/geometry/Attribute.js"; import { StandardAttributes } from "@woosh/meep-engine/src/shade/renderer/geometry/StandardAttributes.js"; const geometry = new Geometry(); geometry.setAttribute(Attribute.from(positions, 3, StandardAttributes.Position)); geometry.index = Attribute.from(indices, 1, StandardAttributes.Index); geometry.ensureNormals(); // computes them only if absent geometry.ensureBounds(); // fills bounding_box / bounding_sphere ``` Attributes are held in a flat `attributes: Attribute[]` and addressed **by name**. The names are strings, and the ones the renderer knows come from `StandardAttributes`: | Constant | String | Encoding / use | |---|---|---| | `Index` | `"index"` | the index buffer, on `geometry.index` | | `Position` | `"position"` | vertex positions | | `Normal` | `"normal"` | vertex normals | | `Tangent` | `"tangent"` | tangent basis, required by normal mapping | | `TextureCoordinates0` | `"uv0"` | the main UV layout | | `TextureCoordinates1` | `"uv1"` | the lightmap UV layout | | `Color` | `"color"` | vertex colour, `vec3` | | `SkinningJoints` | `"joints"` | `vec4` | | `SkinningWeights` | `"weights"` | `vec4` | An `Attribute` is `Attribute.from(array, itemSize, name)`; read one back with `geometry.getAttribute(StandardAttributes.Position).data`, which is the typed array itself. The methods worth knowing: | Method | What it does | |---|---| | `ensureBounds()` | computes `bounding_box` and `bounding_sphere` if the `GeometryFlags.BoundsNeedUpdate` flag is set. `computeBoundingBox()` / `computeBoundingSphere()` / `computeBoundingSphereFromBox()` force it | | `ensureNormals()` / `computeNormals()` | vertex normals. `ensure*` is a no-op when the attribute is already there | | `ensureTangents()` / `computeTangents()` | the tangent basis, by Lengyel's per-triangle accumulation followed by Gram-Schmidt orthogonalisation. The `graphics/geometry/MikkT/` tree ships but has no importer outside itself. Throws if index, position, normal or `uv0` is missing | | `ensureIndex()` / `buildIndex()` | builds an index if the geometry has none | | `getVertexCount()` / `getIndexCount()` / `getPrimitiveCount()` | counts; `getIndexCount()` is three times the triangle count | | `clone()` / `copy(other)` / `equals(other)` / `hash()` | value semantics | `geometry.version` is bumped by `geometry.needsUpdate = true`. **Nothing watches the arrays** - writing into an attribute's `data` is invisible until you say so. That only matters on the dynamic-mesh path below; static geometry is encoded into meshlets once and never consulted again. ### `MeshletGeometry` - the GPU form ```js import { meshlet_geometry_build_from_geometry } from "@woosh/meep-engine/src/shade/renderer/geometry/meshlet_geometry_build_from_geometry.js"; const meshlets = meshlet_geometry_build_from_geometry(geometry); ``` `MeshletGeometry` is the shape as the renderer holds it: triangles clustered into meshlets (`meshlets: MeshletBatch`), attributes encoded and compressed, and a bottom-level tree over the triangles (`bvh: ArrayBuffer`, BVH8 nodes, root first) that the renderer's ray and distance queries walk. It also carries `primitive_count`, `bounding_box`, `bounding_sphere` and `getIndexCount()`. **The build is a precompute.** `meshlet_geometry_build_from_geometry` computes bounds, builds and compresses the meshlet batch and constructs the tree (`blas_from_meshlets`). Do it once when the shape is created or loaded, never per frame. Passing the same `Geometry` through it twice gives you two independent GPU residencies of the same triangles. **A tree and its meshlets belong together.** Every meshlet is one subtree, and building the tree re-orders the triangles inside each meshlet into the order its nodes visit them, so a leaf names its triangles as `(meshlet << 8) | triangle` with no index table in between. A `(meshlet, triangle)` id taken before the tree was built is stale after it, and a `bvh` is valid for the `meshlets` it was built with and no others. The optional second argument fills an existing instance in place: `meshlet_geometry_build_from_geometry(geometry, out)`. That is how the ready-to-render primitives are built: `MeshletGeometry` subclasses whose constructor runs a generator below and then the build, one class per file in `src/shade/renderer/geometry/` - `BoxGeometry`, `PlaneGeometry`, `CapsuleGeometry`, `ConeGeometry`, `CylinderGeometry`, `TorusGeometry` and `UVSphereGeometry`, each taking its generator's arguments. `BoxGeometry.js` also re-exports `PlaneGeometry` as a deprecated alias; import it from `PlaneGeometry.js`. The reverse direction exists too, and you need it for CPU-side triangle queries: ```js import { geometry_build_from_meshlet_geometry } from "@woosh/meep-engine/src/shade/renderer/geometry/geometry_build_from_meshlet_geometry.js"; const decoded = geometry_build_from_meshlet_geometry(meshlets); // a Geometry again ``` ### Primitive generators Ten, all in `src/shade/renderer/geometry/primitives/`, all named exports, all returning a `Geometry` that still needs a meshlet build. The sphere, capsule, cylinder and cone run their axis along Y; the plane lies in XY facing +Z, and the torus lies in XY with its hole along Z. | Function | Signature | |---|---| | `make_box_geometry` | `(width = 1, height = 1, depth = 1, widthSegments = 1, heightSegments = 1, depthSegments = 1)` | | `make_plane_geometry` | `(width = 1, height = 1, widthSegments = 1, heightSegments = 1)` | | `make_uv_sphere_geometry` | `(radius = 1, widthSegments = 32, heightSegments = 16, phiStart = 0, phiLength = Math.PI * 2, thetaStart = 0, thetaLength = Math.PI)` | | `make_capsule_geometry` | `(radius = 1, height = 1, capSegments = 4, radialSegments = 8, heightSegments = 1)` | | `make_cylinder_geometry` | `(radiusTop = 1, radiusBottom = 1, height = 1, radialSegments = 8, heightSegments = 1, openEnded = false, thetaStart = 0, thetaLength = Math.PI * 2)` | | `make_cone_geometry` | `(radius = 1, height = 1, radialSegments = 8, heightSegments = 1, openEnded = false, thetaStart = 0, thetaLength = Math.PI * 2)` | | `make_torus_geometry` | `(radius = 1, tube = 0.4, radialSegments = 8, tubularSegments = 6, arc = Math.PI * 2)` | | `make_torus_knot_geometry` | `(radius = 1, tube = 0.4, tubularSegments = 64, radialSegments = 8, p = 2, q = 3)` | | `make_polyhedron_geometry` | `(vertices, indices, radius = 1, detail = 0)` | | `make_octahedron_geometry` | `(radius = 1, detail = 0)` | - **`make_uv_sphere_geometry`** is rings of latitude and meridians of longitude with equirectangular texture coordinates. The two angular ranges cut a partial sphere: `phi` turns about the axis and `theta` runs down from the north pole, so a `thetaLength` of `Math.PI / 2` is a dome. - **`make_capsule_geometry`** describes the same shape as a `CapsuleShape3D` with the same two numbers: `height` is the straight section, and the whole body spans `height + 2 * radius`. A collider and its mesh therefore agree. - **`make_cone_geometry`** is `make_cylinder_geometry` with a top radius of zero, apex up. Each segment gets its own apex vertex, so the apex normals do not lean toward one edge. - **`make_octahedron_geometry`** is the other sphere: a subdivided octahedron, which spreads its triangles over the surface without the crowding a UV sphere has at its poles. `make_polyhedron_geometry` is the general form it is built on: give it a vertex list, an index list, a radius and a subdivision count, and it projects every subdivided vertex onto the sphere of that radius. ```js import { make_uv_sphere_geometry } from "@woosh/meep-engine/src/shade/renderer/geometry/primitives/make_uv_sphere_geometry.js"; import { make_octahedron_geometry } from "@woosh/meep-engine/src/shade/renderer/geometry/primitives/make_octahedron_geometry.js"; const globe = make_uv_sphere_geometry(1, 48, 24); // radius 1, 48 meridians, 24 rings const ball = make_octahedron_geometry(1, 3); // radius 1, three subdivisions ``` ## ShadedGeometry The component. Named export, at `engine/graphics/ecs/mesh-v2/ShadedGeometry.js`. ```js import { EngineHarness } from "@woosh/meep-engine/src/engine/EngineHarness.js"; import Entity from "@woosh/meep-engine/src/engine/ecs/Entity.js"; import { Transform64 } from "@woosh/meep-engine/src/engine/ecs/transform/Transform64.js"; import { ShadedGeometry } from "@woosh/meep-engine/src/engine/graphics/ecs/mesh-v2/ShadedGeometry.js"; import { ShadedGeometrySystem } from "@woosh/meep-engine/src/engine/graphics3/ShadedGeometrySystem.js"; import { make_box_geometry } from "@woosh/meep-engine/src/shade/renderer/geometry/primitives/make_box_geometry.js"; import { meshlet_geometry_build_from_geometry } from "@woosh/meep-engine/src/shade/renderer/geometry/meshlet_geometry_build_from_geometry.js"; import { StandardShadeMaterial } from "@woosh/meep-engine/src/shade/renderer/material/StandardShadeMaterial.js"; import { Color } from "@woosh/meep-engine/src/core/color/Color.js"; const engine = await EngineHarness.bootstrap({ configuration: (config, engine) => { config.addSystem( new ShadedGeometrySystem(engine.graphics, EngineHarness.shadeScene(engine)) ); }, }); await EngineHarness.buildBasics({ engine, enableTerrain: false, enableWater: false }); const ecd = engine.entityManager.dataset; // once per shape, not per entity const geometry = meshlet_geometry_build_from_geometry(make_box_geometry(1, 1, 1)); const material = new StandardShadeMaterial(); material.diffuse_color.copy(Color.from_sRGB_to_linear(Color.parse("#4ef0a8"))); const t = new Transform64(); t.setTranslation(0, 0, 0); new Entity() .add(t) .add(ShadedGeometry.from(geometry, material)) .build(ecd); ``` `ShadedGeometry.from(geometry, material, draw_mode?)` is the whole construction path. It does **not** compute a bounding box - the box a mesh is culled against comes off the `MeshletGeometry`, which has one built into it. ### Fields | Field | Type | Notes | |---|---|---| | `geometry` | `MeshletGeometry` | what to draw. The JSDoc types it `MeshletGeometry\|Geometry` for the sake of the component's older CPU bounds path, but the renderer's `GPUGeometryManager` asserts `isMeshletGeometry` when the mesh reaches the GPU - build meshlets | | `material` | `ShadeMaterial` | usually `StandardShadeMaterial`; terrain tiles use `TerrainShadeMaterial` with its own material template | | `depth_material` | `ShadeMaterial\|null` | carried and compared, read by nothing in 3.71.0 | | `mode` | `DrawMode` | carried, read by nothing in 3.71.0. The only writer in the engine passes `DrawMode.Triangles` | | `flags` | `number` | see below | `ShadedGeometry.serializable` is `false` - the component does not round-trip through the save system. Models that do are placed with `SGMesh` instead. Two methods are still live: - `getBoundingBox(destination)` writes the world-space AABB into an `AABB3`, by projecting the meshlet geometry's own box through the entity's world transform on the CPU. It deliberately does **not** read back the box the GPU derives: it answers where the primitive is under what the simulation knows, which is what a pick or a framing wants, and the GPU's answer is a frame or two behind. - `query_raycast_nearest(contact, ray, transform_matrix4)` raycasts this primitive's own triangles on the CPU, writing a `SurfacePoint3`. It **requires a decoded `Geometry`** - meshlet pages hold quantised triangles - so run `geometry_build_from_meshlet_geometry` first and keep the result. For picking a whole scene, use [`PickingSystem`](https://meep.company-named.com/docs/rendering/picking/) instead. ### Flags `ShadedGeometry.flags` is a bitmask with the helpers `setFlag(f)`, `clearFlag(f)`, `writeFlag(f, bool)` and `getFlag(f)`. **Two of its eight flags are live and the rest are not** (3.71.0). `Skinned` and `SDFWorld` are the live ones: both are read by `ShadedGeometrySystem` and `prefab_place` and passed to `rows.attach_mesh`. `Skinned` is set by `prefab_instantiate` and asserted by `MeshSkinSystem` on every primitive carrying a `MeshSkin`; `SDFWorld` is on by default (`DEFAULT_FLAGS`) and controls whether the primitive is in the scene's SDF world, which the rays of `ProbeClipmap` global illumination trace. The only other flag any code branches on is `DeferredBoundsUpdate`, and the path it opens is broken rather than useful - see below. Of the remaining five, four reach `ShadedGeometry.js` only as part of `DEFAULT_FLAGS` (`CastShadow`, `ReceiveShadow`, `Visible`, alongside `SDFWorld`) and `FLAG_SET_EQUALITY` (those plus `DrawMethodLocked`), and nothing branches on them; `InView` appears nowhere but its own definition. | Flag | Value | What it names | |---|---|---| | `InView` | 1 | a CPU frustum-cull result | | `CastShadow` | 2 | shadow-map participation | | `ReceiveShadow` | 4 | shadow-map participation | | `DrawMethodLocked` | 8 | a pinned draw method | | `Visible` | 16 | submission | | `DeferredBoundsUpdate` | 32 | collapse repeated bounds updates between reads | | `Skinned` | 64 | **live.** Set by `prefab_instantiate` on a primitive a skin deforms; read by `ShadedGeometrySystem`, which gives such a primitive its own per-instance vertex clone for its `MeshSkin` to deform. Set it yourself on a skinned mesh built in code | | `SDFWorld` | 128 | **live, on by default.** Read by `ShadedGeometrySystem` and `prefab_place` (`in_sdf_world`). Clear it (`clearFlag(ShadedGeometryFlags.SDFWorld)`) to exclude a mesh from the scene's SDF world and surface caches in [`ProbeClipmap` global illumination](https://meep.company-named.com/docs/rendering/global-illumination/) | What that means in practice: - **Shadow participation is not per-mesh.** Everything in the scene casts and receives; the switch is `renderer.feature_shadows_enabled`. See [Lights & shadows](https://meep.company-named.com/docs/rendering/lights-shadows/). - **To hide one, remove the component or the entity.** `unlink` takes the primitive's row out of the scene. A `meshes` row has no `visible` field at all - `DynamicMesh`, which is no part of the scene database, is the only drawable that does. - **Do not set `DeferredBoundsUpdate`.** It documents a trade against the component's CPU bounds queue, but that queue is not wired up: there is no `DeferredBoundsQueue` in the package and nothing calls `bindBoundsQueue`, so `#bounds_queue` is always `null`. `updateTransform` takes the deferred branch on the flag and dereferences that null, so the first transform change after setting it throws `TypeError: Cannot read properties of null (reading 'add')` instead of updating bounds. ## ShadedGeometrySystem ```js import { ShadedGeometrySystem } from "@woosh/meep-engine/src/engine/graphics3/ShadedGeometrySystem.js"; em.addSystem(new ShadedGeometrySystem(graphics, scene)); // (GraphicsEngine, Scene) ``` The constructor is `(graphics, scene)`. (There is no `ShadedGeometrySystem3`; use the unsuffixed name.) Its `dependencies` are `[ShadedGeometry, Transform64]`. On `link` it attaches the entity a `meshes` row naming the component's `geometry` and `material` (over a per-instance vertex clone where the component carries the `Skinned` flag), and subscribes to three announcements on that entity: | Announcement | What it does | |---|---| | `TRANSFORM64_EVENT_CHANGE` | marks the entity's world row, so the GPU re-reads where it is | | `TRANSFORM_ATTACHMENT_EVENT_CHANGE` | marks its local offset, which is what its row holds when its parent has one | | `SHADED_GEOMETRY_EVENT_CHANGE` | rewrites the row from the component - a material swapped, most often. Announce it with `shaded_geometry_announce_change(dataset, entity)`; a `ShadedGeometry` carries no signals of its own | Nothing is polled. An entity that does not move costs nothing - and one that moves without announcing it does not move on screen. **It does not call `graphics.set_scene()`.** Only `LightSystem`, `MeshSystem` and `ParticipatingMediaSystem` do. An application that registers `ShadedGeometrySystem` on its own has to tell the facade what to draw: ```js graphics.set_scene(scene); ``` Pass `EngineHarness.shadeScene(engine)` as the scene, as the sample above does, and the harness's lights and terrain land in the same one - a second `Scene` is a second, unlit, undrawn world. ## Materials There is exactly one shipping PBR material class. `ShadeMaterial` is the base and carries what the rasterizer buckets on: ```js import { ShadeMaterial } from "@woosh/meep-engine/src/shade/renderer/material/ShadeMaterial.js"; import { TransparencyMode } from "@woosh/meep-engine/src/shade/renderer/material/TransparencyMode.js"; import { ShadeDrawMode } from "@woosh/meep-engine/src/shade/renderer/material/ShadeDrawMode.js"; import { ShadeDrawSide } from "@woosh/meep-engine/src/shade/renderer/material/ShadeDrawSide.js"; ``` | Field | Default | Meaning | |---|---|---| | `name` | `""` | debugging label | | `transparency_mode` | `TransparencyMode.Opaque` | which rasterization path the surface takes | | `draw_mode` | `ShadeDrawMode.Triangles` | primitive topology | | `draw_side` | `ShadeDrawSide.Front` | which faces are drawn | plus a read-only `id`, a `textures` getter, and `copy` / `clone` / `equals` / `hash`. `copy` deliberately does not copy `id`. ### `StandardShadeMaterial` ```js import { StandardShadeMaterial } from "@woosh/meep-engine/src/shade/renderer/material/StandardShadeMaterial.js"; const material = new StandardShadeMaterial(); material.texture_albedo = albedo; // a ShadeTexture material.roughness_factor = 0.4; material.metallic_factor = 1; ``` | Field | Type | Default | Meaning | |---|---|---|---| | `texture_albedo` | `ShadeTexture` | `undefined` | base colour; alpha carries transparency | | `diffuse_color` | `Color` | `1, 1, 1, 1` | multiplied with the albedo. **Linear**, see below | | `texture_normal` | `ShadeTexture` | `undefined` | tangent-space normals | | `texture_orm` | `ShadeTexture` | `undefined` | glTF packing: R occlusion, G roughness, B metalness | | `texture_emissive` | `ShadeTexture` | `undefined` | emission | | `emissive_factor` | `Color` | `0, 0, 0` | multiplied with the emissive texture | | `roughness_factor` | `number` | `1` | multiplied with the ORM green channel | | `metallic_factor` | `number` | `0` | multiplied with the ORM blue channel | | `transmission_factor` | `number` | `0` | how much of the dielectric base becomes transmissive rather than diffuse. `1` is clear glass | | `ior_factor` | `number` | `1.5` | index of refraction for the dielectric Fresnel layer. `1.5` gives F0 = 0.04; 1.33 water, 2.4 diamond. Ignored for metals | | `ambient_factors` | `LinearModifier` | `1, 1` | multiplier and offset over the indirect contribution | | `vt_stack` | `VirtualTextureStack \| undefined` | `undefined` | opt-in virtual texturing. When set, albedo, normal and ORM come from streamed pages and the three regular textures are ignored; emissive stays regular. **Opaque materials only** - see [Virtual texturing](https://meep.company-named.com/docs/rendering/virtual-texturing/) | `textures` returns the four regular textures that are actually set, which is what the renderer de-duplicates uploads from. ### Transparency, topology, sides ```js TransparencyMode = { Opaque: 0, AlphaTested: 1, Transparent: 2 } ShadeDrawMode = { Points: 0, Lines: 1, Triangles: 2 } ShadeDrawSide = { Front: 0, Double: 1, Back: 2 } ``` Materials are bucketed by transparency mode, draw mode and sidedness. `Front` and `Back` share a one-sided pipeline; `Double` uses a separate bucket. The transparency mode picks the pass: `Opaque` goes through the opaque rasterization passes, `AlphaTested` through a pass of its own that can discard, `Transparent` through the order-independent one at `AfterTransparency`. `Front` draws the surface's front, `Back` draws its back, and `Double` draws both. The vertex shader reverses triangle winding for `Back`, so both one-sided modes use back-face culling; `Double` disables culling. A mirrored world transform also reverses winding, and the two reversals cancel when combined. This lets instances with negative scale share geometry and materials without changing which side is visible. Normals account for the material's requested side and the transform's handedness. glTF's `doubleSided` sets `ShadeDrawSide.Double` on load. Shadow casters reverse the cull policy, drawing the opposite side of a one-sided surface to reduce self-shadow acne. `Double` remains unculled in the shadow pass. `ShadeDrawMode` is the one to be careful with: the mesh rasterizer's topology table has an entry for `Triangles` only, and an unmapped value falls back to `triangle-list`. Setting `Points` or `Lines` on a mesh material does not give you a point or line pipeline. Lines and points come from the [dynamic-mesh path](https://meep.company-named.com/docs/rendering/effects/). ## Textures Two objects, and the split is load-bearing: **`ShadeImage` is the pixels, `ShadeTexture` is how to sample them.** Two materials sampling one image differently are two textures over one image, and the image is uploaded once. Both answer `equals` and `hash`, which is what the de-duplication keys on. ```js import { ShadeImage } from "@woosh/meep-engine/src/shade/renderer/texture/source/ShadeImage.js"; import { ShadeTexture } from "@woosh/meep-engine/src/shade/renderer/texture/ShadeTexture.js"; import { TextureWrapType } from "@woosh/meep-engine/src/shade/renderer/texture/TextureWrapType.js"; import { TextureFilterType } from "@woosh/meep-engine/src/shade/renderer/texture/TextureFilterType.js"; import { ColorSpace } from "@woosh/meep-engine/src/shade/renderer/texture/ColorSpace.js"; const image = ShadeImage.fromImageBitmap(bitmap); image.color_space = ColorSpace.SRGB; // an albedo or emissive source; see below const texture = ShadeTexture.from(image); texture.wrapS = TextureWrapType.Repeat; texture.wrapT = TextureWrapType.Repeat; texture.magFilter = TextureFilterType.Linear; ``` `ShadeImage` is built with `fromImageBitmap(bitmap)`, `fromSampler2D(sampler)` or `fromArrayBuffer(buffer, channel_count, data_type, width, height, depth)`, and exposes `id`, `source`, `width`, `height`, `depth`, `channel_count`, `data_type`, `normalized` and `color_space`. `ShadeTexture.from(image)` wraps one. Its fields are `label`, `minFilter`, `magFilter`, `mipmapFilter`, `mipmapGenerationFilter`, `wrapS` / `wrapT` / `wrapR`, `dimensions` and `flags`. The only flag is `ShadeTextureFlags.GenerateMipMaps`, and it is **on by default**. | Enum | Values | |---|---| | `TextureWrapType` | `ClampToEdge: 0`, `Repeat: 1`, `MirroredRepeat: 2` | | `TextureFilterType` | `Nearest: 0`, `Linear: 1`, `Mitchell: 2`, `LinearNormal: 3`, `MagicKernelSharp: 4`, `CatmullRom: 5`, `Wronski2021: 6` | | `ColorSpace` | `None: 0`, `SRGB: 1`, `LinearSRGB: 2` | `LinearNormal` is `Linear` with the result renormalised, which is what the glTF loader picks as the mip generation filter for normal maps; `MagicKernelSharp` is what it picks for colour maps. **`ShadeImage.color_space` defaults to `LinearSRGB`.** The image's colour space is what picks the GPU texture format, so an sRGB-encoded PNG used as albedo or emissive must say so - otherwise it uploads as `rgba8unorm` and is sampled without the decode, and the surface reads far too bright. `load_gltf` sets `ColorSpace.SRGB` on base-colour and emissive images for you; an image you build by hand it does not. **Compressed textures: KTX2 only.** A glTF `KHR_texture_basisu` image - a KTX2 container carrying ETC1S (BasisLZ) or UASTC - is read by `ktx2_read` and transcoded on the CPU into a block format the device samples: BC7, BC1, ASTC or ETC2 when the adapter offers that family, RGBA8 otherwise. Pass `texture_support: gpu_texture_compression_support(device)` (`src/shade/renderer/texture/format/gpu_texture_compression_support.js`) to `load_gltf` so the target is what the device can hold; omitted, the loader targets the best format the transcoder writes, which assumes desktop-class hardware. `GLTFSceneBundleAssetLoader` and `load_model_scene_bundle` pass nothing, so a model placed through `SGMesh` gets that assumption. A block-compressed texture brings its own mip chain and gets no generated one. A texture's image is chosen in the order `KHR_texture_basisu`, `EXT_texture_webp`, `source`, and only the chosen image is fetched - an image named through an extension the loader does not read is never requested. **Compressed geometry: meshopt.** A bufferView compressed with `EXT_meshopt_compression`, or its draft-era name `KHR_meshopt_compression`, is decoded on load by the engine's own decoder (`src/core/binary/meshopt/`, pure JavaScript): all three modes - attributes, triangles, indices - and the five filters - none, octahedral, quaternion, exponential, color - with the `fallback` placeholder buffer left unfetched. Nothing is registered for it; `GLTF_BUFFER_VIEW_EXTENSIONS` (`src/format/scene/gltf/ext/`) is the set every load honours, and `TinyGltf#bufferViewExtensions` is where a caller substitutes a different one. `KHR_draco_mesh_compression` is the one geometry extension the loader cannot decode: it re-encodes a primitive rather than a bufferView. ## The sRGB trap `Color` is deliberately space-agnostic: four floats, no space tag. The two halves of the package disagree by default, and this is where it bites. - `Color.parse("#4ef0a8")`, `Color#toHex` and `Color#toCssRGBAString` speak **encoded sRGB**, because that is what a hex literal and a CSS colour are. - The renderer wants **linear**. `diffuse_color` and `emissive_factor` are written straight into the material's GPU struct with no transfer function applied. So this is wrong, quietly, and gives you a washed-out surface: ```js material.diffuse_color.copy(Color.parse("#4ef0a8")); // wrong ``` and this is right: ```js import { Color } from "@woosh/meep-engine/src/core/color/Color.js"; material.diffuse_color.copy(Color.from_sRGB_to_linear(Color.parse("#4ef0a8"))); ``` `Color.from_linear_to_sRGB(input, output?)` is the other direction, for putting an engine colour back into a CSS string. Both carry alpha across untouched. glTF's own `baseColorFactor` is linear by specification and is copied in as-is, so a loaded model needs no conversion. ## Loading a model ### The renderer path ```js import { load_gltf } from "@woosh/meep-engine/src/shade/renderer/loader/gltf/load_gltf.js"; import { prefab_compile } from "@woosh/meep-engine/src/engine/graphics3/prefab/prefab_compile.js"; import { prefab_place } from "@woosh/meep-engine/src/engine/graphics3/prefab/prefab_place.js"; import { Transform64 } from "@woosh/meep-engine/src/engine/ecs/transform/Transform64.js"; const bundle = await load_gltf("data/models/crate.glb", { assetManager }); prefab_place( renderer.scenes.obtain(scene), // the scene's GPU context - its rows are where the model goes scene.dataset, // everything in a scene stands at an entity of this prefab_compile(bundle), // the model, compiled once new Transform64(), // where the root goes ); ``` `load_gltf(url, { assetManager, scope, fileMap, texture_support })` reads `.gltf` and `.glb` and resolves to a **`SceneBundle`** - the one file's contents as flat arrays: | Field | Type | For | |---|---|---| | `nodes` | `SceneNode[]` | the file's nodes in pre-order - name, parent index, local TRS, and a geometry + material where the node draws | | `skins` | `Skin[]` | joints and meshes as indices into `nodes` | | `clips` | `ShadeAnimationClip[]` | each channel's `target` an index into `nodes` | | `lights` | `{light, node}[]` | punctual lights, anchored by node index | `assetManager` is required, not optional: every sub-request the parse makes - the `.bin` buffers, the images - goes back through the manager, so they are cached, counted and cancellable like everything else the application loads. Pass a `scope` to tie a whole load to one cancellable unit, and a `fileMap` (`Map`) when the files came from a drop rather than the network. A `SceneBundle` is **the model as loaded, not a placement of it** - records, with no transform state anyone could pose. `prefab_compile(bundle)` turns it into a `Prefab` once, and every placement is spawned from that with its own entities, which is what makes two of one model - animated or not - possible. USD is the other model format. `load_usd(buffer, { fileName })` (`src/shade/renderer/loader/usd/load_usd.js`) parses `.usda` and `.usdz` - `.usdc` is detected and not read - and resolves to a `SceneBundle` with empty `skins` and `clips`, because UsdSkel is not read; `USDSceneBundleAssetLoader` registers it under `GameAssetType.ModelUSD`. `load_model_scene_bundle` accepts either format, so with the loader registered an `SGMesh` may name a `.usdz` as readily as a `.glb`. ### The ECS path: `SGMesh` and `MeshSystem` Inside the engine, a model is placed with the `SGMesh` component and drawn by `MeshSystem`. ```js import { EngineHarness } from "@woosh/meep-engine/src/engine/EngineHarness.js"; import Entity from "@woosh/meep-engine/src/engine/ecs/Entity.js"; import { Transform64 } from "@woosh/meep-engine/src/engine/ecs/transform/Transform64.js"; import { SGMesh } from "@woosh/meep-engine/src/engine/graphics/ecs/mesh-v2/aggregate/SGMesh.js"; import { MeshSystem } from "@woosh/meep-engine/src/engine/graphics3/MeshSystem.js"; import { ShadedGeometrySystem } from "@woosh/meep-engine/src/engine/graphics3/ShadedGeometrySystem.js"; import { MeshSkinSystem } from "@woosh/meep-engine/src/engine/graphics3/MeshSkinSystem.js"; import { GLTFSceneBundleAssetLoader } from "@woosh/meep-engine/src/engine/asset/loaders/GLTFSceneBundleAssetLoader.js"; import { ArrayBufferLoader } from "@woosh/meep-engine/src/engine/asset/loaders/ArrayBufferLoader.js"; import { ImageBitmapAssetLoader } from "@woosh/meep-engine/src/engine/asset/loaders/image/ImageBitmapAssetLoader.js"; import { GameAssetType } from "@woosh/meep-engine/src/engine/asset/GameAssetType.js"; import { load_model_scene_bundle } from "@woosh/meep-engine/src/engine/asset/load_model_scene_bundle.js"; const engine = await EngineHarness.bootstrap({ configuration: (config, engine) => { const gltf = new GLTFSceneBundleAssetLoader(); config.addLoader(GameAssetType.ModelGLTF, gltf); // .glb config.addLoader(GameAssetType.ModelGLTF_JSON, gltf); // .gltf config.addLoader(GameAssetType.ArrayBuffer, new ArrayBufferLoader()); config.addLoader(GameAssetType.ImageBitmap, new ImageBitmapAssetLoader()); const scene = EngineHarness.shadeScene(engine); config.addSystem(new MeshSystem( engine.graphics, scene, url => load_model_scene_bundle(engine.assetManager, url) )); // models expand into entities carrying ShadedGeometry, so this is required too config.addSystem(new ShadedGeometrySystem(engine.graphics, scene)); // and a skinned primitive carries a MeshSkin, which this deforms config.addSystem(new MeshSkinSystem(engine.graphics, scene)); }, }); new Entity() .add(new Transform64()) .add(SGMesh.fromURL("data/models/crate.glb")) .build(engine.entityManager.dataset); ``` Three things about that: - **`MeshSystem(graphics, scene, load)`** takes the loader as a function so it can be driven in a spec without a network or a device. `load_model_scene_bundle(assetManager, url)` is the stock implementation; it guesses the asset type from the extension so a preload and a placement hit the same cache entry. `ImageBitmapAssetLoader` is easy to forget - without it a model loads with no textures. - **`MeshSystem` calls `graphics.set_scene(scene)` in `startup`.** `ShadedGeometrySystem` does not, so when both are registered the scene wiring is already done. - **A model becomes entities.** `MeshSystem` compiles each url into a `Prefab` once and spawns one instance per placement: every node of the file becomes an entity under the one carrying `SGMesh`, named, parented by `ParentEntity` and posed by `TransformAttachment`, carrying a `ShadedGeometry` where it draws. Geometry, materials, inverse-bind matrices and animation curves are shared by every placement, not copied. That is why `ShadedGeometrySystem` has to be registered as well - it is what gives each of those primitives its `meshes` row. There is one path here rather than two: a skinned primitive also carries a `MeshSkin`, which `MeshSkinSystem` registers and binds, and the model's clips are an `AnimationClips` on the entity carrying `SGMesh`, which the animation systems play. `MeshSystem` itself puts nothing on the GPU - every one of those components is read by its own system exactly as if code had built it. See [Skeletons & skinning](https://meep.company-named.com/docs/animation/skeletons/). `SGMesh` also exposes `url`, `getBoundingBox(aabb3)` and `getUntransformedBoundingBox(aabb3)`, and the `castShadow` / `receiveShadow` flags. `MeshSystem` adds `scene`, `instance_of(entity)`, `mesh_entities_of(entity)` and `compute_world_bounds(target, entity)`. ### A second placement of the same model ```js import { prefab_compile } from "@woosh/meep-engine/src/engine/graphics3/prefab/prefab_compile.js"; import { prefab_instantiate } from "@woosh/meep-engine/src/engine/graphics3/prefab/prefab_instantiate.js"; const prefab = prefab_compile(bundle); // once per model const instance = prefab_instantiate(prefab, dataset, root); // once per placement ``` `prefab_compile(bundle)` reads the bundle and never writes it, producing a `Prefab`: a node count, a parent index per node, names, rest poses, composed rest worlds, primitives, and the skins and clips re-addressed to node indices. Geometry, materials, inverse-bind matrices and curves are referenced, not copied, which is what makes a prefab cheap to spawn. `prefab_instantiate(prefab, dataset, root)` spawns one under an entity you already have, and answers a `PrefabInstance`: | Member | Meaning | |---|---| | `entities` | `Int32Array` - the entity of each node, by node index. `entities[0]` is `root` | | `mesh_entities` | `Int32Array` - the entities that draw, one per primitive | | `entity_of(name)` | the entity of the node the asset calls `name`, or `-1` - this is where a socket, an effect anchor or a projectile spawn is looked up | A skinned primitive's entity carries a `MeshSkin` with its joints as entities of this instance, and the root carries an `AnimationClips` with every channel targeting an entity of this instance - see [Skeletons & skinning](https://meep.company-named.com/docs/animation/skeletons/#per-entity-instancing). `prefab_place` is the same thing for a scene with no systems: it makes the root entity, spawns the prefab under it, acquires a row for every entity, attaches a `meshes` row per primitive and registers each skinned primitive's skin - what `MeshSystem`, `ShadedGeometrySystem` and `MeshSkinSystem` do between them in a game. It returns `{ root, instance, skins, drawn }`, where `skins` is one `{ entity, skin_id }` per registered primitive, or `null` when nothing was registered (`register_animation: false`). It registers no clips; whatever plays them does. **The GPU is authoritative for a driven joint's local offset.** An entity whose `TransformAttachment` a clip writes carries a `GPUStateAuthority` with the `TransformAttachment` bit granted (`gpu_authority_declare` / `gpu_authority_grant`, `engine/ecs/gpu/`), because the pose accumulator resolves that offset on the GPU and a CPU that also wrote it would race the animation. The bit stays granted whether or not a clip is currently playing, so a CPU edit to such an offset is not uploaded. Move the instance through its root entity, and drive its joints through the animation systems. ## Geometry that changes every frame A ribbon, a tube along a path, a debug line - content whose vertices are rewritten every frame cannot pay for a meshlet build, and rebuilding meshlets per frame to force it down this page's path is explicitly not the answer. It goes down a separate one: a `DynamicMesh` holds a plain `Geometry`, lives in a `DynamicMeshBatch` of yours rather than in the `Scene`, gets no scene-database row, and is drawn by a `GPUDynamicMeshRenderer` inside a render extension. One fixed vertex layout, one pipeline, `geometry.needsUpdate = true` when you have rewritten the arrays. It is documented in full under [Effects](https://meep.company-named.com/docs/rendering/effects/). ## Where to go next - [Rendering overview](https://meep.company-named.com/docs/rendering/overview/) - the render pipeline, the `GraphicsEngine` facade and the six frame phases. - [Lights & shadows](https://meep.company-named.com/docs/rendering/lights-shadows/) - the `Light` component, `LightSystem`, and the shadow settings (there are no per-mesh shadow flags). - [Picking](https://meep.company-named.com/docs/rendering/picking/) - `PickingSystem`, the async batched ray query. - [Virtual texturing](https://meep.company-named.com/docs/rendering/virtual-texturing/) - `StandardShadeMaterial.vt_stack` and streamed material pages. - [Effects](https://meep.company-named.com/docs/rendering/effects/) - decals, highlights and the dynamic-mesh path. --- # Lights & shadows Section: Rendering Source: https://meep.company-named.com/docs/rendering/lights-shadows/ Description: The Light component, LightSystem, and the renderer's photometric light model - candela and lux intensity, GPU froxel clustering, cascaded and atlased shadow maps, and ReSTIR DI. Light data lives on the `Light` ECS component. `LightSystem` mirrors every `Light + Transform64` entity into the renderer's `Scene`, where each one becomes a `Light` held in `scene.lights`, standing at that entity's row. From there the renderer takes over: point and spot lights are culled and binned into froxels on the GPU each frame and applied in the deferred pass; directional lights are never clustered and instead drive cascaded shadow maps over the whole view. This page covers the component, the four light types, the renderer's own light objects, and how shadows are generated and filtered. ```pintora activityDiagram start :Light + Transform64 entity; :LightSystem mirrors it into scene.lights; :GPU light table rebuilt on version change; :cull and froxel binning, point and spot only; :shadow atlas refresh - CSM cascades, local tiles; :deferred lighting resolve; end ``` ## The Light component ```js import { Light } from "@woosh/meep-engine/src/engine/graphics/ecs/light/Light.js"; import { LightType } from "@woosh/meep-engine/src/engine/graphics/ecs/light/LightType.js"; import { Transform64 } from "@woosh/meep-engine/src/engine/ecs/transform/Transform64.js"; import Entity from "@woosh/meep-engine/src/engine/ecs/Entity.js"; const light = new Light(); light.type.set(LightType.POINT); light.color.setRGB(1, 0.9, 0.7); // chromaticity only, see below light.intensity.set(40); // candelas light.distance.set(8); // cutoff radius, metres light.radius.set(0.15); // the source is 30 cm across; 0 is a point light.castShadow.set(true); const transform = new Transform64(); transform.setTranslation(0, 4, 0); new Entity() .add(light) .add(transform) .build(ecd); ``` Set `type` before the entity is built. `LightSystem` reads it once, when the entity links, to decide which renderer object to create; it is the one field the system does not observe, so changing it later leaves the old light in the scene. ### Properties | Property | Type | Default | Description | |---|---|---|---| | `type` | `ObservedEnum` | `LightType.DIRECTION` | One of the four constants below. Read once at link time | | `color` | `Color` | white | Chromaticity in linear Rec.709. Its luminance is normalized away at upload - brightness comes from `intensity` alone. Pure black means the light is off | | `intensity` | `Vector1` | `1` | Candelas for `POINT` and `SPOT`, lux for `DIRECTION` | | `angle` | `Vector1` | `Math.PI / 4` | `SPOT` only: the **half-angle** of the cone, in radians. The renderer's limit is `π/2` | | `penumbra` | `Vector1` | `0.4` | `SPOT` only: soft-edge share of the cone (0 = all umbra, 1 = all penumbra) | | `distance` | `Vector1` | `1` | `POINT` and `SPOT`: the cutoff radius of the light's influence - how far it reaches, not how big it is | | `radius` | `Vector1` | `0` | The size of the source. `POINT` and `SPOT`: a world-space radius in metres - a 20 cm ceiling panel is `0.2`. `DIRECTION`: an angular radius in radians - the sun's is `0.006475`. It caps the inverse-square falloff inside the source, sizes the specular highlight, softens the terminator and widens the shadow penumbra. `0` is a delta source - every highlight mirror-sharp, every shadow hard-edged - and is what an unset light gets. Serialized only when non-zero | | `castShadow` | `ObservedBoolean` | `false` | Whether the renderer allocates a shadow-map slot for this light | | `maxShadowDistance` | `Vector1` | `Infinity` | `DIRECTION` only, and **it has no effect**: the renderer fits its own cascades. The field round-trips so scene JSON that carries it still loads | `Light.Type` is a static alias for `LightType`, so `light.type.set(Light.Type.POINT)` also works. ## Light types ```js import { LightType } from "@woosh/meep-engine/src/engine/graphics/ecs/light/LightType.js"; ``` | Constant | Value | What `LightSystem` creates | Behaviour | |---|---|---|---| | `LightType.DIRECTION` | 0 | renderer `DirectionalLight` | Parallel rays along the entity transform's forward. Affects the whole scene, is never froxel-clustered, and is the only type that gets cascades | | `LightType.SPOT` | 1 | `SpotLight` | Cone from the entity's position along its forward. `angle`, `penumbra` and `distance` shape it | | `LightType.POINT` | 2 | `PointLight` | Sphere of influence at the entity's position; `distance` is the radius | | `LightType.AMBIENT` | 3 | **nothing** | Silently dropped - see below | ### Ambient lights are dropped; the environment is the ambient term `LightSystem` has no renderer object for `LightType.AMBIENT` and returns `null` for it. The entity keeps its component, but nothing is added to the scene and nothing renders. This is deliberate: the renderer lights indirect from the environment by default, so a flat ambient light on top would double-count it. There is an environment to be the ambient term unless you turn it off. A scene that arrives at `GraphicsEngine.set_scene(scene)` without an environment map gets its procedural sky (`scene.atmosphere`) enabled, unless code has assigned `scene.atmosphere.enabled` itself; a scene that has a map keeps it. The sky is lit by the scene's first directional light - its colour times its intensity - and by a fallback sun when the scene has none. Replace the sky with a map through `graphics.set_environment_map(texture)` - the texture must be octahedral-encoded. See [Sky & environment](https://meep.company-named.com/docs/rendering/sky/). `EngineHarness.buildLights` still builds an ambient entity (tagged `["Light", "Ambient"]`). It costs one entity and renders nothing. ## Registering LightSystem `LightSystem` is a **named** export at `engine/graphics3/LightSystem.js` and takes `(graphics, scene)`. There is nothing to pre-allocate or size up front: the GPU light table is rebuilt from the collection. ```js import { LightSystem } from "@woosh/meep-engine/src/engine/graphics3/LightSystem.js"; import { EngineHarness } from "@woosh/meep-engine/src/engine/EngineHarness.js"; await engine.entityManager.addSystem( new LightSystem(engine.graphics, EngineHarness.shadeScene(engine)) ); ``` `EngineHarness.shadeScene(engine)` hands out the one `Scene` per engine. `LightSystem.startup()` calls `graphics.set_scene(scene)`, so registering it is also what tells the renderer which scene to draw - it is one of only three systems that do (the others are `MeshSystem` and `ParticipatingMediaSystem`). There is no `LightSystem3`; use the unsuffixed `LightSystem`. ## A sun and a fill from EngineHarness `EngineHarness.buildLights({ engine })` registers `LightSystem` if it is missing and builds two entities: a directional key light tagged `["Light", "Key"]` and the ambient fill above. | Option | Default | Notes | |---|---|---| | `sun` | `Color(1, 0.93, 0.87)` | Key-light chromaticity | | `sunIntensity` | `0.9` | Lux | | `sunDirection` | `Vector3(0.17, -1, 0.17)` | Fed to `t64_look_rotation`; the transform sits at `(30, 70, 30)` | | `castShadow` | `true` | Set on the key light | | `ambient` | `Color.white` | Fill chromaticity | | `ambientIntensity` | `0.07` | Fill intensity | | `sunShadowDistance` | `1000` | Written to `maxShadowDistance`, which has no effect | `EngineHarness.buildBasics({ engine })` calls it for you unless you pass `enableLights: false`, and forwards `enableShadows` as `castShadow`. Note that it forwards nothing else - a scene that wants a different sun calls `buildLights` itself, or reaches the light afterwards. The key light's `radius` is left at `0`, so its shadows have no penumbra; set it to the sun's `0.006475` on the light afterwards for soft ones. A radius above `0` is also what makes the default sky draw the sun's disc. ### A directional light is authored above the air A directional light stands at infinity, so while `scene.atmosphere.enabled` what reaches a surface is the light through the whole atmosphere toward it: `color` and `intensity` times the atmosphere's transmittance for the light's direction, read at `atmosphere.reference_altitude`. A sun near the horizon dims and reddens, and one below it is black, from its direction alone. So `color` and `intensity` say what the light is before the air, the same at every hour: a day cycle turns the light and leaves both where they are, and the sky, lit by the [same light](https://meep.company-named.com/docs/rendering/sky/#the-sun), follows. It is one value a light for the whole scene, written on the GPU every frame, and it is what every surface shades with. Fog takes the atmosphere toward the light at each froxel instead, starting from the light as authored. With the atmosphere disabled - `enabled` assigned `false`, or a scene handed to `set_scene` with an environment map and nothing said - the light is used as authored. **The default sun is dim, and automatic exposure is what hides it.** `0.9` lux is a heavily overcast sky, and a scene lit by it looks correct only because auto-exposure opens up to meet it. Two consequences: the frame's brightness follows whatever is on screen, so it shifts when something bright enters the view, and turning auto-exposure off leaves the scene at dusk. Every example on this site sets the sun to **6 lux** and turns adaptation off: ```js await EngineHarness.buildLights({ engine, sunIntensity: 6 }); // or, after buildBasics has already made one: engine.entityManager.dataset.traverseEntities([Light], (light) => { if (light.type.getValue() === LightType.DIRECTION) { light.intensity.set(6); } }); engine.graphics.renderer.feature_automatic_exposure_enabled = false; ``` 6 is not a physical daylight figure. Under the default sky the key light is also the sky's sun, so the indirect light brightens and dims with it. A scene under a real sky HDR wants a sun that matches that sky instead, and a scene whose ground is near-white wants the same sun and a stop of negative [exposure compensation](https://meep.company-named.com/docs/rendering/frame-features/) rather than a dimmer light. ## The stale-light trap `LightCollection` bumps its `version` when a light is added or removed. **Mutating a light in place does not.** The GPU light table is only rebuilt when the version moves, so a light that has been recoloured, re-aimed or dimmed keeps rendering with the values it was uploaded with. Nothing about this is visible from the CPU: the light object holds the new value, every read-back is correct, and only the picture is stale. `scene.lights.needsUpdate = true` is what says otherwise. `LightSystem` does this for you. It listens for `TRANSFORM64_EVENT_CHANGE` on the entity and binds the component's `color`, `intensity`, `castShadow`, `angle`, `penumbra`, `distance` and `radius`, flipping `needsUpdate` on any of them changing. Moving a light is therefore the one part you still have to say out loud: write the transform, then `t64_announce_change(ecd, entity)`. If you hold a renderer `Light` directly, `needsUpdate` is yours to remember: ```js const scene = EngineHarness.shadeScene(engine); const sun = scene.lights.elements[0]; sun.intensity = 4.0; scene.lights.needsUpdate = true; // without this the GPU keeps the old value ``` ## The renderer's light objects Working below the ECS - a standalone scene, or an entity whose light you want to reach through - these are the types. All named exports. | Export | Module | |---|---| | `LightCollection` | `shade/renderer/light/LightCollection.js` | | `make_sunlight` | `shade/renderer/light/make_sunlight.js` | | `Light` | `shade/renderer/light/model/Light.js` | | `DirectionalLight` | `shade/renderer/light/model/DirectionalLight.js` | | `PointLight` | `shade/renderer/light/model/PointLight.js` | | `SpotLight` | `shade/renderer/light/model/SpotLight.js` | A renderer `Light` **stands at an entity**, and where it is, is that entity's `transforms` row - read on the GPU every frame, so a light parented under something moves with it. It is aimed by writing its `Transform64` and calling `updateMatrix()`, and the engine's convention is that a light shines along its forward. `scene.lights.add(light, entity)` is what puts one in a scene; `place_light(scene, light)` (`shade/renderer/light/place_light.js`) makes the entity first, for a caller that has none of its own, giving it the light's own `transform` as its `Transform64` so that what the light was aimed with is what the row is written from. | Field | Default | Meaning | |---|---|---| | `color` | white | Chromaticity, linear Rec.709 | | `intensity` | `1` | Candelas (point, spot) or lux (directional) | | `radius` | `0` | Physical size of the emitter. Feeds the area-light shading term for every type, and the penumbra width of point-light shadows | | `near_clip_distance` | `0` | Pushes the shadow near plane out, so a light inside a lamp or lantern mesh is not shadowed by its own housing | | `casts_shadow` | `true` | Note this defaults the opposite way to the ECS component's `castShadow` | Per subclass: - `DirectionalLight` adds nothing. Its direction is entirely the transform's forward. - `PointLight` adds `distance = 1` and an `intensity_lumens` accessor (`cd = lm / 4π`). - `SpotLight` adds `distance = FLOAT32_MAX`, `angle = Math.PI / 3` (a **half-angle**, limit `π/2`), `penumbra = 0`, and an `intensity_lumens` accessor using `cd = lm / (2π(1 − cos θ))`. Because θ is the current `angle`, reads and writes track it: narrowing the cone at a fixed lumens value raises on-axis intensity. There are no light cookies - no projected texture on a spot light, in any form. ### make_sunlight ```js import { make_sunlight } from "@woosh/meep-engine/src/shade/renderer/light/make_sunlight.js"; scene.lights.add(make_sunlight({ intensity: 2.5 })); ``` Defaults: `intensity = 2.5`, `direction = Vector3(-0.2, -1, 0.2)`, `temperature = 7100` K - the light as it is [above the air](#a-directional-light-is-authored-above-the-air), which the default atmosphere, from that direction, turns into about a 5500 K light of intensity 2.2 on the ground. It sets `casts_shadow = true` and `radius = 0.006475`, the sun's angular radius seen from Earth, so the area-light term gives specular highlights the right size. ### Why color carries no brightness At upload, `light_pack_color` divides the colour by its own Rec.709 luminance and multiplies by `intensity`, so the triplet the GPU sees always has luminance exactly `intensity` whichever RGB was picked. Without that, a saturated blue would deliver roughly a tenth the luminance of a saturated green at the same nominal intensity, because the RGB-to-luminance weights are lopsided - and "intensity in candelas" would not mean anything. A colour whose luminance is below `1e-6` is treated as off rather than scaled to infinity. ## Froxel clustering Local lights are binned on the GPU each frame: a frustum and Hi-Z cull pass (`graph_cull_lights`) narrows the set, then `graph_build_light_clusters` sorts the survivors by type and id, marks each against a coarse 4×4×4-cell grid, and `shader_cluster_assign_lights` writes every cell's light list that the deferred pass loops over. All of it lives in `shade/renderer/light/cluster/` and none of it is configurable from outside; there is nothing to register or size. A cell has no fixed light limit. The lists of every cell share one buffer, sized from the frame's own count and grown when a frame needs more: a frame that overflows it keeps what fits, and the frames after it are sized up. The shape of the grid is fixed by two exported constants: | Constant | Value | Module | |---|---|---| | `LIGHT_CLUSTER_TILE_RESOLUTION` | `32` px | `light/cluster/LIGHT_CLUSTER_RESOLUTION.js` | | `LIGHT_CLUSTER_RESOLUTION_Z` | `24` slices | `light/cluster/LIGHT_CLUSTER_RESOLUTION.js` | Only point and spot lights are clustered - `CLUSTER_LIGHT_TYPE` has exactly the two members, and directional lights are deliberately absent because they touch every cluster anyway. ## Shadows `renderer.feature_shadows_enabled` (default `true`) is the master switch. Turning it off evicts every shadow map and clears the cast-shadow bit on every light record, so lights keep lighting and stop occluding. It is one of the plain booleans on the renderer catalogued under [frame settings](https://meep.company-named.com/docs/rendering/frame-features/). ### Directional: cascaded shadow maps Directional lights use CSM with `SHADOWMAP_CSM_CASCADE_COUNT = 3` cascades. Default per-cascade resolutions are `[1740, 1440]`, with the last entry repeating - so cascade 0 is 1740², cascades 1 and 2 are 1440². The cascade blend fraction (`SHADOWMAP_CSM_CASCADE_BLEND_FRACTION`) is deliberately `0`: expanding a cascade's extents to guarantee overlap would cost texel density on every cascade all the time, to smooth a transition that is rarely visible. The shader still blends opportunistically over its border band wherever the next cascade happens to reach; where it does not, a hard cut is accepted. ### Local lights: one shared atlas Every shadow map - the three directional cascades included - is packed into a single 8192² depth atlas (`4096 * 2`) by a max-rectangles packer. A spot light takes one perspective view and one rect. A point light renders six cube faces and remaps them into a single octahedrally-encoded rect, with a `SHADOWMAP_ATLAS_BORDER = 4` texel wrap skirt on each side so the filter kernel can cross an octahedral seam without bleeding into a neighbour; the usable inner surface is the slot side minus 8. Local slots start at 128² and are then resized every frame by `ShadowmapResolutionPolicy`, which derives a desired power-of-two side from the light's projected on-screen area: - Sides are clamped to `[32, 1024]`. Below 32 a shadow is too blocky to be worth drawing; above 1024 one light could monopolise the atlas. - Single-step resizes have a 3-frame cooldown and 0.2 log2 of hysteresis, so a light sitting on a power-of-two boundary does not flip-flop between sizes. Jumps of two steps or more (a camera cut, a sudden zoom) bypass the cooldown. - A global drop scale shrinks every light's request by 10% per frame once atlas occupancy passes 0.85, and grows back once it falls below 0.50. The gap between the two is a deadband. ### The refresh budget Not every map is redrawn every frame. The per-frame budget is 8 **views**, where a spot light costs 1 view, a directional 3 (one per cascade), and a point light 6 (one per cube face) - so the cost of the refresh step tracks the rasterization work being asked for rather than the light count. Directional lights always refresh and charge against the pool, which reduces what is left for local lights that frame. Unused budget carries over between frames, so a point light that cannot fit in one frame's remainder eventually gets its turn instead of starving. ### Filtering There are no variance shadow maps. What runs: | Light type | Filter | |---|---| | Directional | Per-cascade 5-tap PCF over hardware comparison-gather taps (`shadowmap_sample_5` on `textureGatherCompare`), with CSM cascade blending on top | | Spot | The same 5-tap PCF, against a single perspective view | | Point | 8 cone-distributed taps around the receiver-to-light vector, each re-encoded to the light's octahedral map, resolved through a contact-hardening DPCF kernel. Tap directions come from the calling shader's per-invocation random state, so neighbouring pixels decorrelate without a rotation table | Bias is applied as a world-space offset toward the light - a normal-offset term plus a slope-scaled depth term, both scaled by the world size of one shadow texel - rather than as a post-projection constant, so it stays stable as a cascade's depth range grows. PCSS and EVSM code is present in the tree (`shadow/map/shader/pcss/`, `shadow/evsm/`) but nothing imports it. Neither is part of the shipping frame; do not plan around them. ### Tetrahedral point shadows `renderer.feature_tetrahedron_point_shadows` (default `false`) swaps the six-face cube generator for a four-face tetrahedral one. Both remap into the same octahedral atlas encoding, so the sampler is identical and the flag is safe to flip at runtime - existing point maps are evicted and rebuilt on the next light pass. It exists for A/B comparison of the two generators, not as a quality setting. ### No per-mesh shadow toggle `ShadedGeometryFlags.CastShadow` and `ReceiveShadow` exist on the `ShadedGeometry` component and are part of its default flag set, but nothing in the render path reads them. Every instance in the scene is a potential caster and a receiver. See [Meshes & materials](https://meep.company-named.com/docs/rendering/meshes-materials/). ## ReSTIR DI `renderer.feature_restir_di_enabled` (default `false`) turns on stochastic screen-bounded direct shadowing for local point and spot lights - an Unreal MegaLights-style path. When it is on, the deferred pass skips its froxel cluster loop entirely and consumes the ReSTIR-resolved radiance instead. Each pixel draws RIS candidate lights from its froxel cluster, reuses a reprojected reservoir from the previous frame, and resolves visibility with an optional screen-space contact trace before falling back to a traced ray. ```js const renderer = engine.graphics.renderer; // null until the engine has started renderer.feature_restir_di_enabled = true; renderer.restir_di.m_initial = 16; ``` | Field on `renderer.restir_di` | Default | Meaning | |---|---|---| | `m_initial` | `8` | Initial RIS candidate lights drawn per pixel | | `use_screen_space_shadow` | `true` | Try a short screen-space contact trace before the ray-traced fallback; `false` is pure ray-traced visibility | | `denoise_enabled` | `true` | Run the edge-aware à-trous denoiser on the resolved radiance | | `denoise_iterations` | `3` | À-trous iteration count (step sizes 1, 2, 4, …); wider and smoother, and more expensive | The tuning object is `ReSTIRDI`, `shade/renderer/restir/di/ReSTIRDI.js`. It is created during renderer initialization, so read it after the engine has started. ## Where to go next - [Rendering overview](https://meep.company-named.com/docs/rendering/overview/) - the visibility-buffer deferred pipeline, frame phases, and render extensions. - [Meshes & materials](https://meep.company-named.com/docs/rendering/meshes-materials/) - `ShadedGeometry`, meshlet geometry, and materials. - [Sky & environment](https://meep.company-named.com/docs/rendering/sky/) - the procedural sky or octahedral environment map that supplies the ambient term. - [Global illumination](https://meep.company-named.com/docs/rendering/global-illumination/) - indirect lighting modes beyond the environment map. --- # Sky & environment Section: Rendering Source: https://meep.company-named.com/docs/rendering/sky/ Description: Every scene has a physical atmosphere that draws the sky and bakes the image-based light from the scene's sun; an octahedral environment map replaces both. Covers the atmosphere's settings, the ways to supply a map, the CPU recipe for an authored one, volumetric fog, and the two path tracers. There is no skybox object in the renderer, and no sky component. The sky behind the geometry and the image-based light every surface reads its indirect light from come from one source, and always the same one for both: the scene's physical atmosphere, `scene.atmosphere`, or an octahedral environment map, `scene.lights.environment`. A map, when one is set, wins. | `scene.lights.environment` | `scene.atmosphere.enabled` | Background | Image-based light | |---|---|---|---| | a `ShadeTexture` | either | the map, drawn by `shader_background` | the map | | `undefined` | `true` | the atmosphere as seen from the camera, drawn by `shader_background_sky` | a 256² octahedral map baked from the atmosphere | | `undefined` | `false` | black | black | `GraphicsEngine.set_scene(scene)` settles the default: when `scene.lights.environment === undefined` it calls `scene.atmosphere.enable_by_default()`, so a scene handed over without a map gets a sky, and sky lighting, from its sun. An `enabled` you assigned yourself is respected either way, and a scene that arrives with a map keeps it. The bottom row is what is left - the renderer lights with indirect on by default, so a scene with neither source has a black background and no ambient light at all. ## The atmosphere Every `Scene` carries a `SceneAtmosphere` (`src/shade/renderer/atmosphere/SceneAtmosphere.js`) as `scene.atmosphere`: the parameters of a Hillaire (2020) sky, authored in metres and inverse metres. The planet's centre sits at `(0, -planet_radius, 0)`, so world `y = 0` is sea level and +Y is up. ```js import { EngineHarness } from "@woosh/meep-engine/src/engine/EngineHarness.js"; const atmosphere = EngineHarness.shadeScene(engine).atmosphere; // a hazier day: five times the aerosol atmosphere.mie_scattering = [2e-5, 2e-5, 2e-5]; atmosphere.mie_extinction = [2.2e-5, 2.2e-5, 2.2e-5]; atmosphere.invalidate(); ``` | Field | Default | Meaning | |---|---|---| | `enabled` | `false` | Whether the atmosphere draws the sky and bakes the image-based light while the scene has no environment map. `set_scene` turns it on through `enable_by_default()` unless it was assigned; `enabled_explicitly` says whether it was. | | `planet_radius` | `6_378_000` | Centre to sea level, metres. | | `atmosphere_height` | `100_000` | Thickness of the shell above sea level, metres. | | `rayleigh_scale_height` | `8_000` | Exponential scale height of the molecular density, metres. | | `rayleigh_scattering` | `[5.802e-6, 13.558e-6, 33.1e-6]` | Sea-level Rayleigh scattering, RGB, per metre. | | `mie_scale_height` | `1_200` | Exponential scale height of the aerosol density, metres. | | `mie_scattering` | `[3.996e-6, 3.996e-6, 3.996e-6]` | Sea-level Mie scattering, RGB, per metre. | | `mie_extinction` | `[4.44e-6, 4.44e-6, 4.44e-6]` | Sea-level Mie extinction, RGB, per metre. Absorption is derived: `max(mie_extinction - mie_scattering, 0)`. | | `mie_phase_g` | `0.8` | Cornette-Shanks asymmetry of the aerosol phase function, held inside ±0.999 on upload. | | `ozone_center_height` | `25_000` | Altitude of peak ozone density, metres. | | `ozone_half_width` | `15_000` | Half-width of the ozone layer's tent profile, metres. | | `ozone_absorption` | `[0.65e-6, 1.881e-6, 0.085e-6]` | Peak ozone absorption, RGB, per metre. | | `ground_albedo` | `[0.3, 0.3, 0.3]` | Diffuse reflectance of the planet's surface, for multiple scattering and the bounce that fills the lower hemisphere. | | `reference_altitude` | `1` | Altitude above sea level, metres, the image-based light is baked from. Held at least 10 m up (`ATMOSPHERE_ALTITUDE_CUTOFF`). | | `sun_irradiance_scale` | `1` | Multiplies the sun's irradiance as the atmosphere sees it: brightens or dims the sky without touching the light. | | `fallback_sun_enabled` | `true` | Light the sky from the fallback sun when the scene has no directional light. | | `fallback_sun_direction` | `(0.2, 1, -0.2)`, normalised | Unit vector **toward** the fallback sun. | | `fallback_sun_irradiance` | `[6, 6, 6]` | The fallback sun's RGB irradiance. | The fields are plain properties and nothing watches them. After changing the medium - the radii, heights, coefficients, phase or `ground_albedo` - call `atmosphere.invalidate()` (or set `atmosphere.needsUpdate = true`); either bumps `atmosphere.version`, which is what the GPU side compares. Assigning `enabled` bumps it for you. `reference_altitude`, `sun_irradiance_scale` and the fallback sun are read every frame and need no call. ### The sun The atmosphere has no sun of its own. `resolve_atmosphere_sun(scene)` (`src/shade/renderer/atmosphere/resolve_atmosphere_sun.js`) finds one each frame, taking the first of: 1. **The first `DirectionalLight` in `scene.lights.elements`** - under the ECS, a `Light` of `LightType.DIRECTION`. The sun stands opposite the way the light shines. Its irradiance is the light's colour scaled to its `intensity` (`light_pack_color`) times `sun_irradiance_scale`: the light as authored, above the air. 2. **The fallback sun**, when `fallback_sun_enabled` is true: `fallback_sun_direction` and `fallback_sun_irradiance`, again times `sun_irradiance_scale`. 3. **Nothing.** The sky and its image-based light are black. So the sky follows the light. Rotate the sun and the sky turns with it; raise its `intensity` and the sky brightens in proportion; a scene with no directional light at all still gets daylight from the fallback. The same light reaches a surface through this atmosphere, dimmed and reddened toward the horizon and black below it - see [a directional light is authored above the air](https://meep.company-named.com/docs/rendering/lights-shadows/#a-directional-light-is-authored-above-the-air) - so turning the light is all a day cycle does. **A sun disc is drawn only for a directional light with a `radius` above zero** - its angular radius in radians. `make_sunlight` sets the sun's `0.006475`; `EngineHarness.buildLights` leaves its key light at `0`, which draws a sky with no disc in it. The fallback sun never draws one. The disc is limb-darkened, dimmed by the atmosphere along the view ray, drawn no smaller than `0.0045` radians, and hidden where the view ray meets the planet. ### What is drawn, and what is baked **The background** is rebuilt every frame. `shader_sky_view_lut` (`src/shade/renderer/atmosphere/shader_sky_view_lut.js`) renders a 192 × 108 sky-view LUT for the camera's position, and `shader_background_sky` (`src/shade/renderer/deferred/shader_background_sky.js`) samples it for every pixel no geometry covered, adding the disc. The camera's altitude is its world `y`, held at least 10 m above sea level. **The image-based light** is baked. `GPULightCollection` renders `shader_sky_irradiance_lut` into mip 0 of the scene's environment texture - a 256² octahedral map (`SKY_IRRADIANCE_LUT_RESOLUTION`), skirt included, of the sky as seen from `reference_altitude` - and then convolves it into irradiance and roughness mips exactly as it does an authored map. Everything that samples the environment reads this map: indirect lighting, probe rays that leave the scene, the GPU path tracer's misses. It holds the scattered sky and the ground's bounce, not the disc; the sun's direct light is the directional light's. The bake repeats when `atmosphere.version`, `reference_altitude`, or the resolved sun's direction or irradiance differ from the last one baked, so a moving sun re-bakes and re-convolves the map every frame it moves. Both read the same two tables. Each `GPUSceneContext` owns one `GPUSky` (`src/shade/renderer/atmosphere/GPUSky.js`), exposed as `scene_context.sky` and constructed over the scene's `SceneAtmosphere`: a uniform buffer of the parameters, a 256 × 64 transmittance LUT and a 32 × 32 multiple-scattering LUT. `GPUSky.update()` uploads the parameters and rebuilds both LUTs when `atmosphere.version` has moved, and does nothing otherwise. Its readers are the background, the bake, and [volumetric fog](#volumetric-fog-and-participating-media). ## The environment map Assign `scene.lights.environment` and the atmosphere steps aside for both jobs. The map is a single octahedral `ShadeTexture`: the image-based-lighting source, and what the background pass draws behind the geometry. Replace it and both change together. There is deliberately no `set_environment_texture` counterpart to `set_environment_map` - the map already *is* the visible sky. Once the G-buffer and ambient occlusion exist and before indirect lighting is added, `Renderer` records `shader_background` (`src/shade/renderer/deferred/shader_background.js`). The pass is depth-tested `equal` against background depth, so it only touches pixels no geometry covered; for each of those it unprojects through the camera's inverse view-projection matrix and calls `sample_environment_color(tEnvironment, sEnvironment, view_direction)`, which reads mip 0 of the environment texture with bilinear octahedral filtering. The same texture is separately convolved on the GPU into an irradiance map and a set of roughness mips for the lighting path. Two consequences worth internalising: - **Whatever you want in the sky has to be in the map.** Sun disc, horizon haze, cloud shapes, time of day - nothing of the atmosphere is drawn over a map. - **The background is drawn at the map's base resolution.** `load_cube_environment` builds a 128² octahedral map, which is plenty for an ambient source but visibly soft as a backdrop. If the sky is meant to be looked at, build the map larger. Three constraints apply to the texture: | Constraint | Enforcement | |---|---| | Must be a `ShadeTexture` | Asserted in the `LightCollection.environment` setter and again in `GraphicsEngine.set_environment_map` (`texture.isShadeTexture === true`) | | Must be square, at least 48² | Asserted in `GPULightCollection` (`width === height` and `width >> 4 >= 3`, so the last of the five filtered levels still has an interior inside its skirt) | | Must be **octahedral**-encoded with a **one-texel skirt** | `GPULightCollection` asserts `octahedral_skirt_matches` when CPU texels are on hand (`Sampler2D` or uncompressed `ShadeTexelData`). With assertions stripped, an unskirted map renders with seams along the octahedron's edges; a cube or equirectangular texture samples as garbage | ### Getting a texture in | Call | Import | What you get | |---|---|---| | `load_cube_environment(folder_path, file_extension)` | `src/engine/graphics3/load_cube_environment.js` | `Promise`. Six sRGB face images, decoded to linear and reprojected to a 128² octahedral f16 map on the CPU at load. | | `load_environment_map(url, projection)` | `src/shade/renderer/light/environment/rgbe/load_environment_map.js` | `Promise`. An RGBE `.hdr` file. See the download gotcha below. | | your own `Sampler2D` | - | Any radiance you can evaluate per direction. See [the recipe](#recipe-an-authored-environment-on-the-cpu). | ```js import { load_cube_environment } from "@woosh/meep-engine/src/engine/graphics3/load_cube_environment.js"; // fetches posx.png, negx.png, posy.png, negy.png, posz.png, negz.png const texture = await load_cube_environment("/textures/sky/", ".png"); engine.graphics.set_environment_map(texture); ``` The face names and the extension are concatenated straight onto the folder path, so include the trailing slash and the leading dot. ### The `load_environment_map` download gotcha `ProjectionMappingType` is exported from the same file as `{ Equirectangular: 0, Octahedral: 1 }`, and `projection` **defaults to `Equirectangular`**. On that branch the function resamples the panorama to octahedral on the main thread and then calls `download_env_map(...)`, which hands the converted buffer to `downloadAsFile(..., '.hdr', 'binary')`. In other words, loading an equirectangular `.hdr` triggers a file download in the player's browser, every time, as a side effect. Pass a pre-converted octahedral map instead: ```js import { load_environment_map, ProjectionMappingType } from "@woosh/meep-engine/src/shade/renderer/light/environment/rgbe/load_environment_map.js"; engine.graphics.set_environment_map( await load_environment_map("/textures/sky_octahedral.hdr", ProjectionMappingType.Octahedral) ); ``` The `Octahedral` branch parses the RGBE payload straight to `Float16` and skips the resample entirely, which is both correct and much cheaper. The file that one accidental `Equirectangular` run downloads *is* the converted map - run the conversion once during authoring, ship the result, and never take the equirectangular path at runtime. ### There is no prefilter step `set_environment_map` does no prefiltering. The renderer convolves the map into its irradiance and roughness mips on the GPU, notices when the texture has been swapped, and redoes that work itself. Assignment is the entire API, and it is safe before startup as well as after: ```js engine.graphics.set_environment_map(texture); // also raises graphics.needDraw scene.lights.environment = texture; // equivalent, minus the redraw flag ``` To hand both jobs back to the atmosphere, clear the map on the scene - `set_environment_map` asserts a texture: ```js scene.lights.environment = undefined; scene.atmosphere.enabled = true; // a scene that reached set_scene with a map never had it turned on ``` ### Recipe: an authored environment on the CPU Any sky you can evaluate per direction becomes an environment map through the chain `load_cube_environment` follows: ```pintora activityDiagram start :sample the sky into the interior of a float Sampler2D; :sampler2d_octahedral_skirt_fill; :sampler2d_to_f16; :ShadeImage.fromSampler2D; :set image.color_space to LinearSRGB; :ShadeTexture.from; :graphics.set_environment_map; end ``` Sampling straight into the octahedral grid avoids an intermediate panorama and the orientation problem below: ```js import { Sampler2D } from "@woosh/meep-engine/src/engine/graphics/texture/sampler/Sampler2D.js"; import { sampler2d_to_f16 } from "@woosh/meep-engine/src/engine/graphics/texture/sampler/sampler2d_to_f16.js"; import { octahedral_z_pole_uv_to_direction } from "@woosh/meep-engine/src/shade/renderer/light/environment/octahedral_z_pole_uv_to_direction.js"; import { sampler2d_octahedral_skirt_fill } from "@woosh/meep-engine/src/shade/renderer/light/environment/sampler2d_octahedral_skirt_fill.js"; import { ColorSpace } from "@woosh/meep-engine/src/shade/renderer/texture/ColorSpace.js"; import { ShadeTexture } from "@woosh/meep-engine/src/shade/renderer/texture/ShadeTexture.js"; import { ShadeImage } from "@woosh/meep-engine/src/shade/renderer/texture/source/ShadeImage.js"; const RESOLUTION = 512; const interior = RESOLUTION - 2; // linear radiance arriving from a unit direction, +Y up: a dusk gradient over dark ground function sky_radiance(out, offset, direction) { const up = direction[1]; if (up >= 0) { const horizon = (1 - up) ** 4; out[offset] = 0.02 + 0.9 * horizon; out[offset + 1] = 0.04 + 0.35 * horizon; out[offset + 2] = 0.12 + 0.1 * horizon; } else { out[offset] = 0.02; out[offset + 1] = 0.018; out[offset + 2] = 0.015; } } const sampler = Sampler2D.float32(4, RESOLUTION, RESOLUTION); const direction = [0, 0, 0]; for (let v = 1; v <= interior; v++) { for (let u = 1; u <= interior; u++) { // texel centres in the (RESOLUTION - 2)² interior, so the mapping stays symmetric across the folds octahedral_z_pole_uv_to_direction(direction, (u - 0.5) / interior, (v - 0.5) / interior); const offset = (v * RESOLUTION + u) * 4; sky_radiance(sampler.data, offset, direction); sampler.data[offset + 3] = 1; } } sampler2d_octahedral_skirt_fill(sampler); const image = ShadeImage.fromSampler2D(sampler2d_to_f16(sampler)); // radiance, not colour: these values never had a transfer curve on them. // LinearSRGB is already ShadeImage's default; the shipped loaders set it explicitly anyway. image.color_space = ColorSpace.LinearSRGB; engine.graphics.set_environment_map(ShadeTexture.from(image)); ``` `octahedral_z_pole_uv_to_direction` is the CPU port of the exact WGSL decode the GPU samples with, and the source is emphatic that every CPU-side producer of octahedral texels must go through it so the two can never drift apart. The outer one-texel ring is the octahedral skirt that hardware bilinear filtering reads across the octahedron's edges: sample the `(RESOLUTION - 2)²` interior and call `sampler2d_octahedral_skirt_fill(sampler)` rather than filling `0 .. RESOLUTION - 1` directly. ### If you go through a panorama, watch the orientation `resample_equirectangular_to_octahedral(sampler, output_resolution)` takes a float `Sampler2D` and writes the skirt itself, so the panorama route works - but the engine holds two equirectangular conventions, and the resampler reads only one of them: | | Longitude | Latitude | |---|---|---| | `resample_equirectangular_to_octahedral` reads (`equirectangular_zenith_first_direction_to_uv`) | `u = (atan2(x, z) + pi) / 2pi` | `v = acos(y) / pi`, so `v = 0` is the zenith | | `equirectangular_direction_to_uv` in `src/core/geom/3d/equirectangular/` writes | `u = atan2(z, x) / 2pi + 0.5` | `v = asin(y) / pi + 0.5`, so `v = 0` is `-Y` | A panorama laid out the second way and fed to the resampler comes out flipped vertically and turned a quarter turn about Y. The result still looks like a sky, which is what makes it easy to miss - check where the sun lands. Either render the panorama in the first convention, or sample into the octahedral grid directly as above. ## Volumetric fog and participating media A `ParticipatingMedia` component paired with a `Transform64` is a box of fog, smoke, dust or cloud that the renderer marches through. ```js import { EngineHarness } from "@woosh/meep-engine/src/engine/EngineHarness.js"; import { ParticipatingMedia } from "@woosh/meep-engine/src/engine/graphics3/ParticipatingMedia.js"; import { ParticipatingMediaSystem } from "@woosh/meep-engine/src/engine/graphics3/ParticipatingMediaSystem.js"; import { Transform64 } from "@woosh/meep-engine/src/engine/ecs/transform/Transform64.js"; import { VolumetricsParticleSpec } from "@woosh/meep-engine/src/shade/renderer/volumetrics/ParticipatingMediaVolume.js"; import { MIE_PARTICLES_STANDARD_PRECOMPUTED } from "@woosh/meep-engine/src/core/math/physics/mie/MIE_PARTICLES_STANDARD_PRECOMPUTED.js"; const engine = await EngineHarness.bootstrap({ configuration(config, engine) { config.addSystem( new ParticipatingMediaSystem(engine.graphics, EngineHarness.shadeScene(engine)) ); } }); const medium = new ParticipatingMedia(); medium.particle_spec = VolumetricsParticleSpec.fromMeep( MIE_PARTICLES_STANDARD_PRECOMPUTED.FOG_DROPLET_SMALL ); medium.target_extinction = 0.4; // per metre, set after the spec medium.fade_distance = 1; const transform = new Transform64(); transform.setTranslation(0, 4, 0); transform.setScale(7, 5, 7); // the volume is a unit cube, so this is its size in metres transform.updateMatrix(); // scale reaches the matrix only when it is composed const ecd = engine.entityManager.dataset; const entity = ecd.createEntity(); ecd.addComponentToEntity(entity, medium); ecd.addComponentToEntity(entity, transform); ``` Set `particle_spec` before `target_extinction`: the setter divides by the spec's extinction to get a density, so assigning the spec afterwards silently changes the strength you asked for. `ParticipatingMediaSystem` takes `(graphics, scene)`, declares `dependencies = [ParticipatingMedia, Transform64]`, and calls `graphics.set_scene(scene)` during startup - it is one of only three systems that do. **The component is the medium; the `Transform64` beside it is the box.** The renderer's `ParticipatingMediaVolume` is a unit cube centred on the origin, posed by that transform, so position, size and orientation are already ECS concepts and the component does not restate them. The transform is taken as world space with **no hierarchy applied**, exactly as lights are: parenting a fog volume to a moving entity leaves the fog where the child's own transform puts it. | Field | Default | Meaning | |---|---|---| | `density` | `3e7` | Particles per cubic metre. Physically a count, so the numbers are large; the default is dense fog. What the useful range is depends entirely on `particle_spec`. | | `particle_spec` | `VOLUMETRIC_PARTICLE_SPEC_FOG` | What one particle does to light - a Mie solution (`extinction`, `scattering`, `radius`, `g`). `VolumetricsParticleSpec.fromMeep(entry)` converts an entry of the generated `MIE_PARTICLES_STANDARD_PRECOMPUTED` library (`src/core/math/physics/mie/`), which has named entries for hazes, fogs, clouds and dusts. | | `fade_distance` | `0.1` | Metres of soft edge inside the box faces. **World space, deliberately not scaled by the transform.** Zero gives hard edges, visible as a straight line across the screen wherever the box crosses the view. | | `target_extinction` | derived | Extinction per metre - `density` expressed in what it does rather than how many particles it took, and comparable across particle specs. **Writing it sets `density`; it is not stored**, so changing `particle_spec` afterwards changes what reading it back gives. Asserts if the spec extinguishes nothing. | | `noise_strength` | `0` | Noise on the density, in [0, 1]: how far the medium goes from uniform toward the noise tile's value. `0` is a uniform medium and costs nothing; `1` is the tile as it is. | | `noise_scale` | `32` | World size of one repeat of the tile, in metres. The engine's tile holds four base features an edge, so `32` puts them 8 m apart. | | `noise_warp` | `0.1` | How far a warp tap may displace the lookup, in tile units. `0` is one tap and a field that only slides. | | `noise_velocity` | `[0, 0, 0]` | The medium's own motion for the noise, metres a second along the world axes, added to the scene's wind - a draught in a corridor the wind does not reach. | | `noise_wind_factor` | `1` | How much of the scene's wind this medium feels, `1` all of it. The wind is the scene's far field (`GPUFluidSystem.far_field_at`, the mean wind and its turbulence from its `GlobalFluidEffector`s - see [the scene's wind](https://meep.company-named.com/docs/physics/fluid/#the-scenes-wind)), plus wherever a GPU fluid domain departs from it. A scene without a `GPUFluidSystem` is still air. | | `noise_texture` | `0` | Which slot of the scene's noise atlas the tile comes from. `0` is the one the engine bakes. | The component serialises (`ParticipatingMediaSerializationAdapter`, `typeName = "ParticipatingMedia"`), noise settings included, and `density` is what survives a save, not `target_extinction`. Two behaviours to plan around: - **Changes are polled once a frame, not subscribed to.** Neither the transform nor a density slider nor a swapped particle spec or noise setting announces itself to this system, so it compares them each frame and uploads only when something differs. A medium with noise also scrolls every frame, by the wind it feels plus its own `noise_velocity`. A change becomes visible within a frame rather than instantly, and a fog volume needs no `t64_announce_change` to follow its transform. - **Mutating a `ParticipatingMediaVolume` directly is invisible.** `scene.volumetrics` is a `SceneVolumetrics`; `add` and `remove` bump its `version` themselves, but an in-place edit needs `scene.volumetrics.invalidate()`. Going through the component avoids the question. There is no feature flag. The renderer builds the volumetrics LUTs whenever the scene holds at least one volume, and composites them over the finished opaque, background and indirect colour in a dedicated pass - before transparency, so transparent surfaces blend over the fog, and before TAA, which then smooths the fog's per-pixel sampling noise. The fog is already in `SceneColor` by the time `FramePhase.AfterLighting` runs, so a [render extension](https://meep.company-named.com/docs/rendering/render-extensions/) at that phase sees it. The froxels take their sunlight through [the atmosphere](#the-atmosphere): each directional light is attenuated by the `GPUSky` transmittance LUT on its way in, and the multiple-scattering LUT fills in what a single bounce misses. Fog reads those LUTs whatever `atmosphere.enabled` says, so a scene whose sky is an environment map still fogs through the scene's atmosphere parameters. `renderer.volumetrics` (`GPUViewVolumetrics`) tunes the main view's froxel grid: `tile_size` (default `16`, screen pixels per froxel in XY; changing it preserves and resamples temporal history by UVW), `resolution_z` (default `64`, depth slices between camera near and `froxel_far`; changing it drops temporal history), `froxel_far` (default `Infinity`, clamped to `camera.far`), `taa_enabled` (default `true`, 3D temporal reprojection over the scattering volume), and `reset_history()` (also called by `renderer.indicate_view_change()`). ## Path tracing Two unrelated path tracers ship, and they are not alternatives to each other. ### The GPU path tracer `renderer.feature_path_tracing_enabled` (default `false`) - one of the [frame settings](https://meep.company-named.com/docs/rendering/frame-features/) - makes `renderer.path_tracer` replace the rasterized and shaded colour for the frame. The traced result still goes through TAA and tone mapping like any other colour, which is the problem: the tracer accumulates across frames itself, one tile per call, and resets whenever the camera moves, so **turn `feature_taa_enabled` off while this is on** or two temporal filters fight over the same image. ```js const renderer = engine.graphics.renderer; // the escape hatch renderer.feature_taa_enabled = false; renderer.feature_path_tracing_enabled = true; renderer.path_tracer.render_tile_size = 256; // square pixels per call renderer.path_tracer.min_accumulation_alpha = 0.01; // blend floor ``` `renderer.path_tracer` is an `AccumulatingPathTracer`, constructed lazily on first access. Each `render()` traces one tile and blends it into the history with weight `max(1 / sample_count, min_accumulation_alpha)`. A path that leaves the scene samples the scene's environment texture - the authored map, or the one baked from the atmosphere. The source is direct about what this is for: it binds the GPU TLAS buffer directly, which made it the check that the TLAS builds and traces correctly and the first place a regression in that tree would show. It calls itself prototype-grade rather than a shipping render mode. Do not build a product on it. ### The pure-JS CPU path tracer `src/engine/graphics/sh3/path_tracer/` is a complete Monte-Carlo renderer in plain JavaScript, single-threaded, on the CPU. `BufferedGeometryBVH` builds from a `Geometry` carrying a `position` attribute. | Class | File | Role | |---|---|---| | `PathTracer` | `PathTracer.js` | `path_trace(out, ray, min_bounce, max_bounce, random, scene)` - one path, one output RGB | | `PathTracedRenderer` | `PathTracedRenderer.js` | Drives a tracer over a camera and scene. `render(target, camera, scene, progress)` is a **generator** that yields once per pixel, so a scheduler can spread it over frames. Writes tone-mapped, sRGB-encoded bytes into a `Sampler2D`. | | `PathTracedScene` | `PathTracedScene.js` | Two-level BVH (top-level over mesh AABBs, per-mesh for triangles), lights, background sampler. `createMesh(geometry, material, transform)`, `addLight(light)`, `optimize()` to rebuild the top level. | | `PathTracedMesh` | `PathTracedMesh.js` | One mesh instance: geometry, material, transform, per-mesh BVH | | `BufferedGeometryBVH` | `BufferedGeometryBVH.js` | Per-geometry BVH | Russian roulette terminates a path with probability 0.5 after `min_bounce` bounces, scaling survivors by the reciprocal to keep the estimator unbiased. The background is a closure on `scene.__background_sampler` with the signature `(out, out_offset, direction, direction_offset)`: it writes linear RGB for a unit direction. The default is black. This tracer shares nothing with the renderer's scene, the atmosphere included, so a sky is a function you assign: ```js // the Ray Tracing in One Weekend gradient scene.__background_sampler = (out, out_offset, direction, direction_offset) => { const t = 0.5 * (direction[direction_offset + 1] + 1); out[out_offset] = 1 - 0.5 * t; out[out_offset + 1] = 1 - 0.3 * t; out[out_offset + 2] = 1; }; ``` `populate_path_traced_scene_from_ecd(ecd, scene)` exists and walks `[ShadedGeometry, Transform64]` and `[Light, Transform64]` (directional and point lights only). **It does not work on a scene authored for the renderer as it stands**, and its own JSDoc says why: a `ShadedGeometry` spawned from a loaded model holds a `MeshletGeometry`, whose triangles are quantized inside meshlet pages, and a `ShadeMaterial` - while `createMesh` wants a `Geometry` and the tracer's own `StandardMaterial`. `geometry_build_from_meshlet_geometry` decodes the first; there is no converter yet for the second. Entities built directly with a `Geometry` and a `StandardMaterial` go through unchanged. Nothing in the engine calls the CPU tracer - there is no SH3 probe baking; see [global illumination](https://meep.company-named.com/docs/rendering/global-illumination/) for the indirect-lighting modes. It is a reference renderer for offline tooling. Being single-threaded JavaScript it is orders of magnitude slower than the GPU path, which is why `PathTracedRenderer.render` is a generator: drive it from a scheduler and spread it over frames rather than blocking on it. ## Related - [Rendering overview](https://meep.company-named.com/docs/rendering/overview/) - the frame, its phases, and the render-extension surface - [Global illumination](https://meep.company-named.com/docs/rendering/global-illumination/) - `indirect_lighting_mode`, and why IBL from the sky is the default - [Lights & shadows](https://meep.company-named.com/docs/rendering/lights-shadows/) - the directional light the atmosphere takes for its sun, and why `LightType.AMBIENT` is silently dropped (the environment is the ambient term) - [Real-time Global Illumination example](https://meep.company-named.com/examples/#probe-clipmap) - a day cycle with no environment map: the atmosphere draws the sky from one sun light --- # Global illumination Section: Rendering Source: https://meep.company-named.com/docs/rendering/global-illumination/ Description: The renderer's indirect lighting - the IBL default, the real-time ProbeClipmap cascaded probe clipmap, the ScreenProbes screen probe gather over it, the Brick4 sparse volumetric lightmap and its bake, and the VolumetricLightMap component that carries one. The renderer always applies an indirect term. There is no "GI off" switch: the deferred resolve and the forward transparency pass both ask for indirect lighting every frame, and the only question is where the answer comes from. That is one setting on the renderer. ```js import { ShadeIndirectLightingMode } from "@woosh/meep-engine/src/shade/renderer/ShadeIndirectLightingMode.js"; engine.graphics.renderer.indirect_lighting_mode = ShadeIndirectLightingMode.Brick4; ``` `engine.graphics` is the `GraphicsEngine` facade; `.renderer` is the escape hatch to the `Renderer` itself, and it is `null` before `Engine.start()` and again after `stop()`. Set the mode once the engine is running. | Mode | Value | What produces the indirect light | What you author | |---|---|---|---| | `IBL` | `0` | the environment - the scene's atmosphere, or an environment map in its place - convolved into irradiance and roughness mips. The default. | nothing, or an environment map - see [Sky & environment](https://meep.company-named.com/docs/rendering/sky/) | | `Brick4` | `1` | a baked sparse volumetric lightmap, sampled in world space | run the bake, ship the bytes, carry them on a `VolumetricLightMap` | | `ProbeClipmap` | `3` | a real-time cascaded octahedral probe clipmap traced on the GPU against the scene's SDF brick clipmap and its surface material, gathered from per-mesh Model Surface Caches | nothing offline - configure via `renderer.probe_clipmap` ([see below](#probeclipmap---real-time-cascaded-probe-clipmap)) | | `ScreenProbes` | `4` | a screen probe gather over the `ProbeClipmap` world: probes placed on the G-buffer every few pixels, traced through the screen and then the SDF bricks, with the world-space probes answering past their reach. It lights the opaque surfaces' diffuse; everything else reads the world-space probes | nothing offline - configure via `renderer.screen_probes`, and `renderer.probe_clipmap` for the world ([see below](#screenprobes---screen-probe-gather)) | The enum is a named export and the values above are the literal ones, so `indirect_lighting_mode` is safe to serialize as a number. `2` names no mode. The selected mode also supplies the indirect light in the froxel irradiance volume. Participating media and particles with `lighting: true` use that volume, which combines this indirect contribution with shadowed direct lights. Under `ScreenProbes` that contribution is the world-space probes'. --- ## A scene with no environment renders unlit This catches people before any of the modes matter. `GraphicsEngine.set_scene` gives the scene an environment when it arrives without an environment map: ```js if (scene.lights.environment === undefined) { scene.atmosphere.enable_by_default(); } ``` The comment beside it states the reason plainly: the renderer lights with indirect by default, and a scene with neither an authored environment nor an active atmosphere renders unlit. `enable_by_default()` turns on `scene.atmosphere`, the scene's physical sky, which draws the background and bakes the image-based light from the scene's sun. It leaves an `enabled` you assigned yourself alone, so `scene.atmosphere.enabled = false` on a scene with no map is how you ask for a black environment - turning the sky off is the thing that takes a decision, not turning it on. A scene that arrives with an environment map keeps it, and the map does both jobs in the atmosphere's place. And the environment is not only the IBL source: the background is drawn from it in **every** mode, so a Brick4, ProbeClipmap or ScreenProbes scene still needs one for the sky behind the geometry. [Sky & environment](https://meep.company-named.com/docs/rendering/sky/) covers both sources. --- ## Brick4 - the sparse volumetric lightmap Brick4 is the technique meep 3 actually ships for baked indirect light. It is a tree of nodes over the scene's bounds, each node carrying a 4x4x4 grid of probes (`BRICK4_PROBE_RESOLUTION`), branching 3 per axis (`BRICK4_BRANCH_FACTOR`, so 27 children per node). Probes hold second-order spherical harmonic colour packed into 28 bytes each, and adjacent nodes share the probes on their shared faces. What makes it sparse is the expansion rule: a child cell only becomes a candidate for subdivision if it overlaps scene geometry, tested against a BVH over the scene. Empty air is never refined. Expansion runs shallowest-first and stops on whichever comes first - probe spacing that would fall below the requested `cell_size`, or an estimated GPU footprint that would exceed the memory budget. Density therefore follows surfaces, and the budget is a real ceiling rather than a hint. ```pintora activityDiagram start :brick4_bake_for_scene; :lightmap.svlm downloaded; :ship the bytes with the level; :VolumetricLightMap.data = bytes; :VolumetricLightMapSystem uploads it; if (indirect_lighting_mode) then (Brick4) :indirect lighting reads the map; else (any other mode) :the map is never read; endif end ``` ### Baking ```js import { brick4_bake_for_scene } from "@woosh/meep-engine/src/shade/renderer/global_illumination/brick4/cpu/brick4_bake_for_scene.js"; import { MEGABYTE } from "@woosh/meep-engine/src/core/science/units/memory/MEGABYTE.js"; import { EngineHarness } from "@woosh/meep-engine/src/engine/EngineHarness.js"; const { tree, binary } = await brick4_bake_for_scene({ scene: EngineHarness.shadeScene(engine), renderer: engine.graphics.renderer, cell_size: 0.5, max_memory_usage_bytes: 16 * MEGABYTE }); ``` | Parameter | Default | Meaning | |---|---|---| | `scene` | required | the renderer's `Scene`, not the ECS dataset. `EngineHarness.shadeScene(engine)` is the one the harness's systems draw into. | | `renderer` | required | the `Renderer` - `engine.graphics.renderer` | | `cell_size` | `0.5` | smallest cell in world units. **Capped, never coarsened:** the value used is `min(cell_size, largest_scene_dimension / 32)`, so a small scene silently gets a finer grid than asked for. | | `max_memory_usage_bytes` | `16 * MEGABYTE` | ceiling on the estimated GPU footprint of the whole structure, probe data included | It resolves to `{ tree, binary }` - the intermediate CPU tree, and the `ArrayBuffer` in brick4's GPU format. Four things about the call are worth knowing before you wire it into anything: - **It is asynchronous and needs a live device.** The tree is built on the CPU; the probes are baked on the GPU. Bake after `Engine.start()`, never before. - **It downloads a file, unconditionally.** The last thing it does before uploading is `downloadAsFile(binary, "lightmap.svlm")`. There is no flag to suppress it. This is an authoring tool and belongs in a tools build or a dev-only route, not anywhere a player can reach. - **Nothing loads `.svlm` for you.** That extension appears exactly once in the engine - in the download call above. There is no asset loader for it and no `GameAssetType`. Reading the bytes back is the application's job; an `ArrayBufferLoader` fetch (`GameAssetType.ArrayBuffer`) or a plain `fetch(...).arrayBuffer()` is all it takes. - **It uploads the result itself.** Before returning, it pushes `binary` straight into the scene's lightmap buffer, so the picture changes the moment the bake finishes, with no component involved. `VolumetricLightMapSystem` will not undo that upload until a claim on the scene actually changes. The JSDoc is candid about cost: *"Requires a fairly beefy GPU to run, confirmed to work on RTX 4090."* Treat it as an offline step run on a workstation, not something a game does at load time. ### Carrying a lightmap at runtime A scene has exactly one lightmap, and the `VolumetricLightMap` component is a claim on it. That is what gives a lightmap the lifetime an entity already has: it arrives when the level's entity is built, it is saved with it, and it goes away when the entity does. ```js import { VolumetricLightMap } from "@woosh/meep-engine/src/engine/graphics3/VolumetricLightMap.js"; import { VolumetricLightMapSystem } from "@woosh/meep-engine/src/engine/graphics3/VolumetricLightMapSystem.js"; import { EngineHarness } from "@woosh/meep-engine/src/engine/EngineHarness.js"; await em.addSystem(new VolumetricLightMapSystem( engine.graphics, EngineHarness.shadeScene(engine) )); const map = new VolumetricLightMap(); map.data = await (await fetch("/levels/keep/lightmap.svlm")).arrayBuffer(); const entity = ecd.createEntity(); ecd.addComponentToEntity(entity, map); ``` Both the component and the system are **named** exports. The system takes `(graphics, scene)` - the `GraphicsEngine` and the renderer's `Scene` - and declares `dependencies = [VolumetricLightMap]`. | Member | Notes | |---|---| | `data` | `ArrayBuffer \| null`. Asserted to be an `ArrayBuffer` - a `Uint8Array` will not do. `null` is a normal state, not a broken one: it means the bytes are still loading, and lights the scene with nothing. | | `version` | bumped on **every** assignment to `data` | | `toJSON()` / `fromJSON()` | base64. Correct but expensive; the binary `VolumetricLightMapSerializationAdapter` (registered by `populateEngineSerializationRegistry`) is the cheap path. | | `hash()` | the byte length, deliberately not the bytes | | `equals(other)` | a real byte comparison | | `typeName` | `"VolumetricLightMap"` | The contract around it has several edges that will otherwise cost you an afternoon: - **First claim wins; a second waits.** `system.active` is the *first* component to link and stays so until it unlinks, at which point the next in line takes over. Last-writer-wins would make a level's lighting depend on entity construction order. Swapping one map for another is therefore: remove the old component, then add the new one. - **The payload is opaque.** It is brick4's own GPU structure - the format `brick4_to_gpu_structure` writes and the indirect-lighting shaders read. The component neither validates it nor knows how to make one. - **The entity's transform is ignored.** A brick4 structure begins with the world-space bounds it was baked against, so the map already knows where it is. Moving the entity that carries it moves nothing, and the component does not need a `Transform64` at all. - **Mutating the buffer in place is invisible.** The system watches `version`, and only assignment moves it. Publish an in-place edit by assigning `data` again, even to the same buffer. - **Unlinking uploads an empty map** rather than leaving the last one in place. So do a `null` payload and a zero-length buffer. There is no way to un-upload - in Brick4 mode the shader reads the buffer unconditionally - so a component that removed itself and left the scene lit exactly as before would make the lifetime a fiction. - **The upload happens in `update()`, not `link()`.** A lightmap can arrive before the renderer has a device, and a restart hands out a fresh context whose buffer is empty again. Both are the same question asked once a frame, so a link is eventually consistent by at most one frame. - **Uploading a lightmap does not turn Brick4 on.** Which technique the frame uses is `renderer.indirect_lighting_mode`; a scene in any other mode never reads this buffer no matter what is in it. The upload is necessary and not sufficient. ### The fused indirect pass, and screen-space reflections In `Brick4` mode the renderer collapses the diffuse pass, the specular pass and the indirect resolve into a single shader. It reads the G-buffer once, drops the intermediate `rgba16float` diffuse and specular targets, and shares one brick4 probe pair between the diffuse and specular evaluations - less bandwidth for slightly more cache pressure inside the pass. **There is no switch for it.** Fusing is a policy of the frame graph, decided where the passes are built, and it applies whenever the mode is `Brick4` and `feature_ssr_enabled` is false. The only control you have over it is `feature_ssr_enabled`, because SSR needs the standalone specular target. **Screen-space reflections work in Brick4 mode.** Enabling `feature_ssr_enabled` selects the split path, and SSR uses the baked Brick4 volume for fallback specular lighting where screen-space information is insufficient. This costs the separate reflection and filtering passes; keep SSR off when the fused pass alone gives the result you need. [Frame settings](https://meep.company-named.com/docs/rendering/frame-features/#screen-space-reflections) covers reprojection and filtering controls. One neighbouring setting matters here: `renderer.feature_ssao_enabled` is `true` by default, and GTAO's bent normals are what the indirect diffuse is evaluated against in every mode. Switch it off and the indirect passes fall back to the plain G-buffer shading normal. [Frame settings](https://meep.company-named.com/docs/rendering/frame-features/) catalogues that switch and the rest of them. --- ## ProbeClipmap - real-time cascaded probe clipmap `ShadeIndirectLightingMode.ProbeClipmap` (`3`) computes real-time diffuse and glossy indirect lighting on the GPU without an offline bake. While the mode is active, the renderer maintains these structures on the GPU under per-frame budgets: 1. **Per-mesh caches** - sparse signed-distance-field bricks (`GPUGeometrySDFManager`) and Model Surface Caches (`GPUMeshSurfaceCaches`), baked incrementally on the GPU for geometries in the scene's SDF world. Bricks with identical bytes share one atlas slot. A surface cache is kept per (geometry, material) pair, in block-coded 4³ blocks where the field can hold surface, and only for the planes (diffuse albedo, metalness and roughness, emissive) the material makes vary; a constant plane is one value in the cache's record, and a pair that varies in no plane is never baked. Every `ShadedGeometry` opts in by default through `ShadedGeometryFlags.SDFWorld`; call `geom.clearFlag(ShadedGeometryFlags.SDFWorld)` before linking (or announce a change) to exclude a mesh. 2. **Brick clipmap** - cascades of 7³-voxel SDF bricks centred on the camera, scrolled and rebuilt from the per-mesh caches up to `brick_build_budget` cells per frame. Each built brick also gathers a texel of surface material per texel (`GPUBrickMaterial`) from the surface caches of the surfaces it holds; that is what a probe ray's hit reads. 3. **Probe clipmap** - cascades of octahedral radiance and Chebyshev depth-moment probes centred on the camera, the probes the frame's pixels want and shading samples. They trace `frustum_ray_budget` rays per frame at most (`floor(frustum_ray_budget / rays_per_probe)` probes), three quarters of `ray_budget`. 4. **World cache** - a second, denser probe set in the same windows: its spacing is `probe_spacing / 2^world_cache_spacing_shift` and its lattice `2^world_cache_spacing_shift` times `probe_cascade_resolution` per axis, so every frustum probe's point is one of its points. A probe ray that hits where the frustum has no probe wants the world cache's probes there, and only those hits sample it, never the shaded pixels. It traces the rest of `ray_budget` (`world_ray_budget`) with small `4×4` probes and never re-samples its neighbours. The renderer exposes it as `world_cache` beside the frustum's `probe_clipmap` on `GPUProbeClipmapGI`. Like `Brick4`, `ProbeClipmap` uses a fused indirect resolve pass when `renderer.feature_ssr_enabled` is `false`, and switches to the split path when SSR is enabled so SSR can use the probe clipmap for fallback specular lighting. Pixels outside the clipmap or with zero probe weight fall back to `IBL`. Configure the mode through `renderer.probe_clipmap` (`ProbeClipmapSettings` in `src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSettings.js`): | Field | Default | Meaning | |---|---|---| | `brick_cascade_count` | `6` | Brick clipmap cascades, a positive integer; each cascade doubles the voxel size of the one inside it. Checked when the GI is built against the probe rays' 5-bit cascade field (at most `32`) and the device's storage binding size. Structural (rebuilds GI on change). | | `brick_cascade_resolution` | `32` | Cells per axis of a brick cascade, a power of two (cells wrap by masking); the brick clipmap checks the rest against its layout and the device when built. Structural. | | `brick_voxel_size` | `0.125` | Finest brick cascade voxel size in metres. Structural. | | `brick_build_budget` | `4096` | Maximum brick cells built per frame, a positive integer. | | `mesh_sdf_voxel_size` | `0.125` | Per-geometry cached SDF voxel size in mesh units. Changing re-bakes cached geometries. | | `mesh_sdf_max_bricks` | `18` | Even integer from `2` capping bricks per axis of a geometry's SDF before its voxel coarsens to fit; the SDF manager checks the bake's ring against the device when it sizes it. Changing re-bakes cached geometries. | | `mesh_sdf_bake_budget` | `23` | Maximum mesh SDF bricks evaluated per frame while caches fill. | | `surface_bake_budget` | `512` | Maximum Model Surface Cache bricks surveyed and baked per frame, a positive integer: field surveys first, then new (geometry, material) pairs, then re-bakes of materials that changed. A frame with nothing to bake spends nothing. | | `probe_cascade_count` | `5` | Probe clipmap cascades, a positive integer checked against the layout and device when built; each cascade doubles probe spacing. Structural. | | `probe_cascade_resolution` | `32` | Probes per axis of a probe cascade, a power of two. Structural. | | `probe_spacing` | `1` | Metres between probes in the finest cascade. Structural. | | `radiance_resolution` | `16` | Octahedral radiance texels per side of a probe (power of two, at least `2`; the atlas checks a tile against the device). Structural. | | `depth_resolution` | `8` | Octahedral depth-moment texels per side of a probe (power of two). Structural. | | `rays_per_probe` | `256` | Rays a frustum probe traces per update: a power of two, at most `64 · radiance_resolution²` and `64 · depth_resolution²`. Below `radiance_resolution²` an update covers a spread subset of the texels; above it, each texel averages several rays. | | `ray_budget` | `131072` | Maximum rays both probe sets trace per frame. The read-only `frustum_ray_budget` is `floor(0.75 · ray_budget)` and must be at least `rays_per_probe`; `world_ray_budget` is the rest and must be at least `world_cache_rays_per_probe`. | | `world_cache_spacing_shift` | `2` | `k` in the world cache's spacing `probe_spacing / 2^k` and lattice `2^k · probe_cascade_resolution`; a positive integer. Structural. | | `world_cache_radiance_resolution` | `4` | Octahedral radiance texels per side of a world cache probe (power of two, at least `2`). It is only projected to SH, never sampled directly. Structural. | | `world_cache_depth_resolution` | `4` | Octahedral depth-moment texels per side of a world cache probe (power of two); a hit's pick weighs the probe by it. Structural. | | `world_cache_rays_per_probe` | `16` | Rays a world cache probe traces per update (power of two, at most `64 ·` each world cache resolution squared). | | `response_frames` | `30` | Frames over which a neighbour's history goes stale for `history_resampling`: a neighbour last updated Δt frames ago weighs `e^(−Δt / response_frames)`. A probe's own history blends each new sample the same way however long ago its last update was. | | `history_resampling` | `false` | Each frustum probe update also re-samples the histories of four of the probe's 26 neighbours in its cascade, where their depth says they see the same point. Traces no extra rays; trades some spatial blur for stability. Takes effect the next frame. | | `ray_resampling` | `false` | Each frustum probe update also takes one neighbour's rays from the same frame, a neighbour updated this frame chosen by its radiance and how well the probe sees it, keeping every ray whose hit (or sky) the probe's depth confirms. Traces no extra rays; brings in light the neighbour found this frame. Takes effect the next frame. | | `debug_view` | `ProbeClipmapDebugView.None` | Debug view before TAA (`None: 0`, `MeshSDF: 1`, `MeshSurfaces: 2`, `BrickClipmap: 3`, `IndirectDiffuse: 4`, `IndirectSpecular: 5`, `BrickMaterial: 6`, `BrickMetalRough: 7`), imported from `shade/renderer/global_illumination/probe_clipmap/debug/ProbeClipmapDebugView.js`. | --- ## ScreenProbes - screen probe gather `ShadeIndirectLightingMode.ScreenProbes` (`4`) is a Lumen-style screen probe gather run over the `ProbeClipmap` world (`GPUScreenProbeGI` in `src/shade/renderer/global_illumination/screen_probe/GPUScreenProbeGI.js`). It changes one thing about that mode: the diffuse light of the opaque surfaces comes from probes placed on the G-buffer every frame, a few pixels apart, instead of from the world-space probes. Everything `ProbeClipmap` maintains still runs underneath - the per-mesh caches, the brick clipmap, the world light clusters and both sets of world-space probes - and `renderer.probe_clipmap` still configures it. ```js import { ShadeIndirectLightingMode } from "@woosh/meep-engine/src/shade/renderer/ShadeIndirectLightingMode.js"; const renderer = engine.graphics.renderer; renderer.indirect_lighting_mode = ShadeIndirectLightingMode.ScreenProbes; renderer.screen_probes.downsample_factor = 8; // four times the probes, and the rays ``` A frame of the mode, after the world's own update: 1. **Place.** One uniform probe stands in every tile of `downsample_factor` pixels, at a point in the tile that cycles over 8 frames. Adaptive probes follow at half that spacing, then a quarter, down to `adaptive_min_downsample_factor`, wherever the probes placed so far would not interpolate to a point of the finer grid - depth edges and thin geometry. There are as many adaptive slots as uniform probes, so a frame never holds more than twice the uniform count. 2. **Trace.** Each probe casts `octahedron_resolution²` rays. With `importance_sampling`, rays are taken from directions the pixels around the probe cannot see and spent where the probe's light was brightest last frame. With `screen_traces`, a ray is marched through the depth buffer's hierarchy first, and a hit there is lit by the last frame's colour of the opaque surfaces - a bounce more each frame. What the screen cannot answer goes on through the SDF bricks, where a front-face hit is shaded as a `ProbeClipmap` probe ray's is: emissive, the directional lights shadowed by rays through the bricks, one local light of the hit's cluster cell, and a bounce from the world-space probes. A ray that passes the probe's reach unoccluded reads the world-space probes along its direction; where there are none, the environment. 3. **Filter.** The rays are composited into each probe's radiance, `spatial_filter_passes` passes blend it with the neighbouring probes', and each probe is projected to spherical harmonics. 4. **Resolve.** Each pixel interpolates the probes around it at its bent normal, and a temporal filter accumulates the result over up to `temporal_frames` frames - fewer where the rays saw something move. A pixel no probe covers takes its covered neighbours' mean, or its history. 5. **Capture.** The lit colour of the opaque surfaces, before fog and transparency, is kept for the next frame's screen hits. Only the deferred opaque diffuse is the screen probes'. The rest of the frame reads the world-space probes exactly as under `ProbeClipmap`: | Reader | Indirect light under `ScreenProbes` | |---|---| | Opaque surfaces, diffuse | the screen probes | | Opaque surfaces, specular | the world-space probes, the environment where no probe weighs anything; SSR when `feature_ssr_enabled` is `true`, falling back to the same probes | | Transparent surfaces and water | the world-space probes | | The froxel irradiance volume | the world-space probes | As with `ProbeClipmap` and `Brick4`, the two lobes resolve in one fused pass while `renderer.feature_ssr_enabled` is `false`, and on the split path when it is `true`. Configure the gather through `renderer.screen_probes` (`ScreenProbeSettings` in `src/shade/renderer/global_illumination/screen_probe/ScreenProbeSettings.js`): | Field | Default | Meaning | |---|---|---| | `downsample_factor` | `16` | Pixels between the uniform probes along each axis, a power of two. Every ray and every pixel's interpolation scales with the probe count, so the cost goes as the inverse square of this. Structural (rebuilds the screen probes on change). | | `octahedron_resolution` | `8` | Texels per side of a probe's radiance, `4`, `8` or `16`; a probe casts this squared rays a frame. Structural. | | `adaptive_min_downsample_factor` | `4` | The finest spacing adaptive probes are placed at, in pixels, a power of two. At or above `downsample_factor` no adaptive probe is placed. Structural. | | `importance_sampling` | `true` | Rays follow where a probe's light comes from: each texel is weighed by the cosine lobes of the pixels around the probe and by the light its history saw there. Off, every texel takes one ray. Takes effect the next frame. | | `screen_traces` | `true` | Rays are traced through the screen first and lit by the last frame's colour where they hit. Off, every ray is traced through the bricks alone. Takes effect the next frame. | | `spatial_filter_passes` | `3` | Passes of the filter between neighbouring probes, a non-negative integer; `0` runs none. Takes effect the next frame. | | `temporal_frames` | `10` | The most frames the temporal filter averages a pixel's diffuse over, at least `1`: a pixel whose history holds blends its new light by `1 / (1 + frames)`. Takes effect the next frame. | | `debug_view` | `ScreenProbeDebugView.None` | Debug view before TAA (`None: 0`, `IndirectDiffuse: 1`, `ProbePlacement: 2`, `TraceKinds: 3`), imported from `shade/renderer/global_illumination/screen_probe/ScreenProbeDebugView.js`. While it is `None`, `renderer.probe_clipmap.debug_view` applies in this mode too. | Three things to plan around: - **Its history is tied to its structure and its view.** The screen probes' resources are made for the view's internal resolution and the three structural settings; a change to any of them - a step of the render resolution included - makes them again, and the gather starts from nothing. `renderer.indicate_view_change()` drops the history too, for a camera cut. - **The probe count is bounded by the device.** The probes' atlas is `ceil(width / downsample_factor) · octahedron_resolution` texels wide and must fit `maxTextureDimension2D`, and each per-probe buffer must fit `maxStorageBufferBindingSize`; both are asserted when the resources are made. A larger `downsample_factor` or a smaller `octahedron_resolution` is the way under. - **It costs the whole of `ProbeClipmap` and then its own passes.** The world it traces is not optional, so nothing in `renderer.probe_clipmap` gets cheaper for running the gather on top. --- ## Related - [Real-time Global Illumination example](https://meep.company-named.com/examples/#probe-clipmap) - live scene demonstrating `ShadeIndirectLightingMode.ProbeClipmap` and local point light bounce on the Flying World island - [Sky & environment](https://meep.company-named.com/docs/rendering/sky/) - the atmosphere that lights a scene by default, and the octahedral environment map that replaces it - [Lights & shadows](https://meep.company-named.com/docs/rendering/lights-shadows/) - the direct half of the lighting - [Rendering overview](https://meep.company-named.com/docs/rendering/overview/) - the frame the renderer builds, and the `GraphicsEngine` facade --- # Effects Section: Rendering Source: https://meep.company-named.com/docs/rendering/effects/ Description: Decals, outlines, camera shake, and the dynamic-mesh path for content whose vertices change every frame. meep's rendering effects are ECS systems. You register the system, attach a component, and the system registers a [render extension](https://meep.company-named.com/docs/rendering/render-extensions/) that draws at a declared phase of the renderer's frame. The phase decides what an effect can see and what can cover it: decals run before anything is lit, so lighting, ambient occlusion and reflections all see them; outlines run after transparency, over the finished scene and before the upscale that anti-aliases them. Trails are the exception: they are drawn inside the transparency pipeline itself, as a transparency channel. | Effect | System | Components | Draws at | |--------|--------|-----------|----------| | Decals | `DecalSystem(graphics, assets)` | `Decal`, `Transform64` | `AfterGBuffer`, after the terrain | | Outlines | `OutlineSystem(graphics, scene, assets)` + a pairing system per kind | `Outline` + `SGMesh`, `Outline` + `ShadedGeometry` | `AfterTransparency` | | Trails | `Trail3DSystem(graphics, scene)` | `Trail3D`, `Transform64` | inside the transparency pipeline | | Camera shake | `CameraShakeBehavior`, `CameraShakeTraumaBehavior` | - | not a render pass at all | | Your own geometry | `GPUDynamicMeshRenderer` inside your own extension | - | wherever you register it | Every one of these systems takes `engine.graphics` (the `GraphicsEngine` facade) as its first argument, not the engine. --- ## Decals **A decal is a surface override, not a tint.** It carries albedo, a tangent-space normal, roughness, metalness and emission, and it writes them into the G-buffer *before anything is lit* - so ambient occlusion, screen-space reflection and shading all see a decal exactly as they see the surface it is painted on. A scorch mark dulls the specular response of the floor it is on; a glowing rune actually emits. **Decals reach opaque surfaces only, by construction.** The G-buffer is all they touch and transparency composites later, so a decal will never appear on water. ```js import { DecalSystem } from "@woosh/meep-engine/src/engine/graphics3/DecalSystem.js"; import { Decal } from "@woosh/meep-engine/src/engine/graphics/ecs/decal/v2/Decal.js"; await em.addSystem(new DecalSystem(engine.graphics, engine.assetManager)); // Attach a decal to an entity that also has a Transform64 entity.add(Decal.fromJSON({ uri_albedo: "data/textures/decals/scorch_albedo.png", uri_normal: "data/textures/decals/scorch_normal.png", uri_orm: "data/textures/decals/scorch_orm.png", priority: 0, color: "#ffffff" })); ``` `DecalSystem` declares `dependencies = [Decal, Transform64]`, and its `startup()` registers a `DecalExtension` (`name = "decals"`, `phase = FramePhase.AfterGBuffer`). Terrain has already shaded its splat layers through its material by this phase, so the decal composite sees textured ground without an extension ordering constraint. ### The component `Decal` is a named export from `src/engine/graphics/ecs/decal/v2/Decal.js`. Its fields: | Field | Type | Notes | |-------|------|-------| | `uri_albedo` | `string` | Base colour; **its alpha is the decal's mask**, the coverage every channel blends by. Optional: with none, the mask is one across the whole projection volume and the colour is `color` | | `uri_normal` | `string` | Tangent-space normal, applied in the decal's own frame | | `uri_orm` | `string` | glTF packing: **G is roughness, B is metalness**. R (occlusion) is deliberately ignored, so an authored glTF ORM texture drops in unmodified | | `uri_emissive` | `string` | Greyscale mask, multiplied by `emissive_color` and `emissive_intensity` | | `uri` | `string` | **Deprecated.** It **shadows `uri_albedo` while both are set**, so content authored with it keeps working | | `roughness` | `number` | Multiplies whatever `uri_orm` gives; default `1`, so a decal with no ORM map is simply this value | | `metalness` | `number` | Same, default `0` | | `emissive_color` | `Color` | Default white | | `emissive_intensity` | `number` | **Zero by default**, so a decal that does not set it is non-emissive. Values above one are the point of it being a float | | `priority` | `number` | Draw order when decals overlap | | `color` | `Color` | Premultiplied into the decal | | `albedo_weight`, `normal_weight`, `roughness_weight`, `metalness_weight`, `emissive_weight` | `number` | How much of each channel is written, in [0, 1], default `1`. Each scales the mask's coverage for that one channel: `0` leaves the surface's value exactly as it was. A decal that writes only normals keeps `uri_albedo` for its shape and sets `albedo_weight: 0`. A decal's emission replaces what is beneath it, so `emissive_weight: 0` is also what keeps an emitting surface emitting under a decal | The entity's `Transform64` is the projector: a unit box, scaled to the volume you want, whose world matrix and inverse are what the GPU record carries. **It projects along its local +Z, into the surface.** The coverage fade is `smoothstep(0.35, 0.6, dot(face_normal, -axis_z))`, so a projector built by pointing +Z along the surface normal scores -1 and every pixel is rejected - silently: the entity links, the texture resolves, the record is well-formed, and nothing is drawn. Aim +Z at the surface. ### What to expect at runtime - **A decal is not packed until its albedo image has loaded.** The image's alpha is the decal's shape, and drawing it with a placeholder would put a white square on the ground until the image landed, so it simply does not appear yet. Only a decal that names no albedo map at all draws with the full-volume mask. - **Textures are reference counted across decals.** Combat spawns a footprint decal per step and every one of them names the same file; packing a patch per footprint would repack three atlases and regenerate their mip chains several times a second. There are three atlases - albedo (sRGB), normal and ORM - because their contents want different mip filters and different alpha storage: the albedo atlas holds premultiplied colour, the others straight. Each atlas builds its mip chain patch by patch, so a patch's border repeats its own edge at every level rather than blending in its neighbour. - **Records are rebuilt every frame, on purpose.** The froxel binning depends on the camera and has to run every frame regardless, and rebuilding the records alongside it means nothing has to watch a decal for changes - which matters, because a `Color`'s change signal does not fire for alpha-only edits. - **Capacity grows with the record buffer.** There is no fixed budget on the number of decals you may link; the system grows its record array to fit. What is bounded is the GPU side: `DECAL_CULL_LIMIT = 4095` decals survive culling in a frame, and `DECAL_CLUSTER_LOCAL_LIMIT = 32` fit in one froxel - deliberately smaller than the light limit, because a froxel crowded with decals is a pile of surface overrides where all but the last few are invisible. - The decal froxel grid has the lighting grid's shape by construction: 32-pixel tiles, 24 Z slices. - When nothing is packed, the pass does not run at all and the frame keeps the G-buffer it already had. --- ## Outlines `Outline` marks an entity with up to two looks: one where it is the front surface, and one where other geometry hides it. Each look is an `OutlineSpec`: a solid line around the silhouette, a soft fade beyond it, a fill over the object, and a black-and-white mask for the line and one for the fill. ```js import { OutlineSystem } from "@woosh/meep-engine/src/engine/graphics3/OutlineSystem.js"; import { SGMeshOutlineSystem } from "@woosh/meep-engine/src/engine/graphics/ecs/outline/SGMeshOutlineSystem.js"; import { ShadedGeometryOutlineSystem } from "@woosh/meep-engine/src/engine/graphics/ecs/outline/ShadedGeometryOutlineSystem.js"; import { Outline } from "@woosh/meep-engine/src/engine/graphics/ecs/outline/Outline.js"; import { OutlineSpec } from "@woosh/meep-engine/src/engine/graphics/ecs/outline/OutlineSpec.js"; import { MeshSystem } from "@woosh/meep-engine/src/engine/graphics3/MeshSystem.js"; import { EngineHarness } from "@woosh/meep-engine/src/engine/EngineHarness.js"; import { load_model_scene_bundle } from "@woosh/meep-engine/src/engine/asset/load_model_scene_bundle.js"; const scene = EngineHarness.shadeScene(engine); // models draw through MeshSystem plus ShadedGeometrySystem, ParentEntitySystem and // TransformAttachmentSystem, registered as for any model (see Meshes & materials) const meshes = new MeshSystem(engine.graphics, scene, url => load_model_scene_bundle(engine.assetManager, url)); await em.addSystem(meshes); // the pass. It observes no entities: the pairing systems tell it what to outline. // The asset manager loads mask textures; pass null when no spec names one. const outlines = new OutlineSystem(engine.graphics, scene, engine.assetManager); await em.addSystem(outlines); // one pairing system per kind of outlined thing. Register the ones you need. await em.addSystem(new SGMeshOutlineSystem(outlines, meshes)); // loaded models await em.addSystem(new ShadedGeometryOutlineSystem(outlines)); // primitives // a 3 px orange line where the unit can be seen... const selected = new OutlineSpec(); selected.solid_color.set(1.0, 0.6, 0.2, 1); selected.solid_width = 3; // ...and a thin line with a faint fill, drawn over whatever hides it const behind = new OutlineSpec(); behind.solid_color.set(0.6, 0.5, 1.0, 1); behind.solid_width = 1.5; behind.fill_color.set(0.6, 0.5, 1.0, 0.3); const outline = new Outline(); outline.visible = selected; outline.hidden = behind; entity.add(outline); ``` All five are named exports. `OutlineSystem` registers an `OutlineExtension` (`name = "outline"`) at `FramePhase.AfterTransparency`, before the upscale: the outline is drawn into the scene from the jittered visibility buffer, so the temporal resolve anti-aliases its edges along with every other silhouette's. ### The two specs | Field | Draws | |---|---| | `visible` | where the entity is the front surface | | `hidden` | where other geometry stands in front of the entity, over that geometry | Either may be `OutlineSpec.NONE`, the frozen spec that draws nothing, and that side is not drawn. **A fresh `Outline` holds two fresh `OutlineSpec`s, and a fresh spec is a 2 px white line**, so an `Outline` added as it comes outlines the entity in white through walls too. Set the side you do not want to `OutlineSpec.NONE`. A spec that paints no pixel is skipped entirely, so it claims no space from other outlines: a band paints only with both a width and some alpha, the fill only with some alpha. `outline_spec_is_drawing(spec)` (`.../ecs/outline/outline_spec_is_drawing.js`) is that test. Fading `solid_color.a` to zero is therefore a clean way to switch a line off. ### The spec | Field | Default | Notes | |---|---|---| | `solid_color` | white, alpha 1 | the line | | `solid_width` | `2` | output pixels out from the silhouette's edge | | `soft_color` | white, alpha 0 | the fade beyond the line; its alpha is the fade's opacity where it begins, at the line's outer edge, and it fades to nothing | | `soft_width` | `0` | output pixels beyond the line | | `fill_color` | white, alpha 0 | over the object's own pixels | | `outline_mask`, `fill_mask` | `null` | URL of a mask texture for the line (solid and soft) or the fill | | `outline_mask_scale`, `fill_mask_scale` | `1` | | | `outline_mask_offset`, `fill_mask_offset` | `0` | | Colours are **linear RGB with straight alpha**: the outline is drawn into the scene before tone mapping, so a colour picked as sRGB hex needs `Color.from_sRGB_to_linear` first. Widths are output pixels, so a line is the same width at every distance and at every internal resolution. `spec.reach` is `solid_width + soft_width`, how far past the silhouette it paints; the pass runs as many flood rounds as the widest spec in use needs. **A mask is tiled across the screen**, at one texel per output pixel, and does not follow the object. Its red channel `m` multiplies the part it masks by `saturate(m * scale + offset)`, so stripes give a dashed line or a hatched fill, and a non-zero offset keeps the dark texels partly drawn. A null mask reads as white, so `scale` and `offset` alone then make a constant factor. Masks load through the asset manager as `GameAssetType.Image`, so the engine needs a loader for that type (`ImageRGBADataLoader`), and a data URL drawn into a canvas is as good a URL as a file. The [Outlines example](https://meep.company-named.com/examples/highlight/) builds both of its masks that way. `OutlineSpec` has `copy`, `clone`, `equals`, `hash` and JSON round-tripping, and `Outline` serializes through `OutlineSerializationAdapter`, which the engine's serialization registry includes. ### Specs are shared by reference Specs are held by reference and read every frame. That gives two behaviours for free: 1. **Edit a spec in place and every entity holding it changes on the next frame.** A pulsing selection is a per-frame write to `spec.soft_width` or `spec.solid_color.a`; there is nothing to announce. 2. **Entities holding the same spec object are outlined as one shape.** Their outlines merge where they meet, which is what a group selection wants. Give each entity its own spec (`spec.clone()`) when they should stay apart. Two different specs sharing space are drawn as two outlines, each pixel belonging to one of them. ### How it is drawn **Each pixel belongs to one spec**, so outlines never paint over each other. A pixel's owner is the front surface's visible spec; failing that, the hidden spec of the nearest outlined row behind it. The nearer silhouette's outline is on top, a pixel two outlined entities both cover shows the front one's fill, and where outlined entities overlap, the one behind loses its hidden part to the one in front. The pass works from the visibility buffer the frame already wrote. Only the rows with a hidden spec are rasterized a second time, to find where they are hidden. A full-screen classify labels every pixel with its spec, and a jump flood that keeps each pixel's two nearest specs runs only on the 8×8 screen tiles within reach of a silhouette, so its cost follows the silhouettes' length rather than the area they enclose. The inside of a large object is drawn as its fill alone, and not at all when the fill is transparent. With nothing outlined the pass does not run. ### Pairing systems `OutlineSystem` owns everything about drawing and declares no component tuple, because which mesh rows an entity has depends on what kind of thing it is. A pairing system per kind contributes entries through `outlines.add_entry(entity, outline, rows)` and hands them back on unlink: | Pairing system | Tuple | Constructor | Outlines | |---|---|---|---| | `SGMeshOutlineSystem` | `[Outline, SGMesh]` | `(outlines, meshes)` | every primitive the model spawned, asked of `MeshSystem` every frame | | `ShadedGeometryOutlineSystem` | `[Outline, ShadedGeometry]` | `(outlines)` | the primitive's own row | Two consequences: 1. **The `Outline` goes on the model's entity**, the one carrying `SGMesh`, not on the primitives `MeshSystem` builds under it. A model still loading has no primitives yet and starts being outlined when they arrive. 2. **A primitive needs its own pairing system.** An `Outline` on a bare `ShadedGeometry` draws nothing unless `ShadedGeometryOutlineSystem` is registered. Where an outlined primitive sits inside an outlined model, the primitive's own outline wins. ### Highlight (deprecated) `Highlight` is a selection component holding a list of `HighlightDefinition` colours that composite `over` in list order. It is deprecated in favour of `Outline`, which does everything it does and more. Its systems still exist and draw through the same pass: `SGMeshHighlightSystem(outlines, meshes)` and `ShadedGeometryHighlightSystem(outlines)` take an `OutlineSystem` and draw each `Highlight` as a 3 px solid line (`HIGHLIGHT_LINE_WIDTH`) in its composited colour, visible side only, with a spec of its own per entity. To migrate, replace `Highlight.fromOne(r, g, b, a)` with an `Outline` whose `visible.solid_color` is that colour, `visible.solid_width = 3` and `hidden = OutlineSpec.NONE`, and register the `Outline` pairing systems. Give each entity a spec of its own (`spec.clone()`), as `Highlight` did: entities sharing one spec merge into one outline. --- ## Ribbons and trails `Trail3D` is the one trail component the engine draws, and it has its own page: see [Trails](https://meep.company-named.com/docs/rendering/trails/) for the component surface, the sizing rules and `make_gradient_stroke`, which authors a beam or a streak. A trail's knots are simulated in compute and its tube is extruded in the vertex stage, so the CPU builds no geometry for it. There is no screen-facing ribbon: `Trail2D` deserializes but nothing renders it. If what you actually want is arbitrary geometry you rewrite yourself each frame, that is the [dynamic-mesh path](#dynamic-meshes) below. --- ## Camera shake Camera shake is a pair of `Behavior` subclasses in `src/engine/graphics/camera/`. It touches no render pass; it moves a `TopDownCameraController`. `CameraShake` (`CameraShake.js`) owns six independent 2D simplex noise streams - yaw, pitch, roll and X/Y/Z offset - seeded from a fixed value so a replay shakes identically. `shake.read(value, time, offset, rotation)` writes into the `offset` and `rotation` `Vector3`s you hand it, scaled by `value` (0-1) and clamped by `limitsOffset` / `limitsRotation`. `CameraShakeBehavior` wraps a `CameraShake` and updates the controller's `target`, `pitch`, `yaw` and `roll` every tick. It takes a single options object; the limits are set at construction: ```js import { CameraShakeBehavior } from "@woosh/meep-engine/src/engine/graphics/camera/CameraShakeBehavior.js"; const shakeBehavior = new CameraShakeBehavior({ controller, maxPitch: 0.05, maxYaw: 0.05, maxRoll: 0.02, maxOffsetX: 0.1, maxOffsetY: 0.1, strength: 0, }); ``` `CameraShakeTraumaBehavior` adds a trauma accumulator on top. `trauma` is clamped to 0-1, decays at `decay` units per second, and is mapped through a cubic curve before being written to the underlying behaviour's `strength`. Add trauma in response to impacts: ```js import { CameraShakeTraumaBehavior } from "@woosh/meep-engine/src/engine/graphics/camera/CameraShakeTraumaBehavior.js"; const traumaBehavior = new CameraShakeTraumaBehavior({ shakeBehavior, decay: 1.5 // full trauma decays in ~0.67 s }); // On explosion: traumaBehavior.trauma = Math.min(1, traumaBehavior.trauma + 0.6); ``` Both behaviours are based on Squirrel Eiserloh's 2016 GDC talk "Math for Game Programmers: Juicing Your Cameras With Math". --- ## Dynamic meshes A tube along a path, a gizmo, a debug line: content whose vertices are rewritten every frame cannot pay for a meshlet build, and rebuilding meshlets per frame to force it down the standard path is explicitly not the answer. The renderer gives it a path of its own. **This is a separate path, not a variant of the standard one.** A `DynamicMesh` holds a plain `Geometry` rather than a `MeshletGeometry` and its own `transform`, is no entity of the scene, gets no row in the scene database, and is drawn by a pipeline of its own after the standard geometry path has finished with the frame. It is what `PathDisplaySystem` and `DebugDrawSystem` are built on - the two shipping systems whose content is rebuilt on the CPU. (Particles and trails do not use it; each is simulated on the GPU and has a pipeline of its own.) ### The pieces ```js import { DynamicMesh } from "@woosh/meep-engine/src/shade/renderer/scene/DynamicMesh.js"; import { DynamicMeshBatch } from "@woosh/meep-engine/src/shade/renderer/scene/DynamicMeshBatch.js"; const batch = new DynamicMeshBatch(); // yours, not the Scene's const mesh = DynamicMesh.from(geometry, [1, 0.5, 0, 1]); // Geometry + flat RGBA batch.add(mesh); mesh.visible = false; // hide without losing GPU residency geometry.needsUpdate = true; // you say when the vertices changed; nothing watches the arrays ``` `DynamicMesh` is a node of nothing: it carries its own `transform`, a `Transform64` posed directly and refreshed with `updateMatrix()`, with no parent above it and no row in the scene database. Its `color` is a `Float32Array` RGBA multiplied into whatever per-vertex colour the geometry carries - the alpha is what fades a mesh out as a whole. `DynamicMeshBatch` exposes `add`, `remove`, `clear`, and the getters `meshes` (insertion order, which is draw order, because these are blended), `count` and `version`. ### The vertex layout is fixed `src/shade/renderer/dynamic/DYNAMIC_MESH_VERTEX.js` exports `DYNAMIC_MESH_VERTEX_STRIDE = 8`, `DYNAMIC_MESH_VERTEX_POSITION_OFFSET = 0` and `DYNAMIC_MESH_VERTEX_COLOR_OFFSET = 4`: | Floats | Meaning | |--------|---------| | `[0..2]` | position `x, y, z`, object space | | `[3]` | reserved - keeps the stride a power of two and leaves room for a UV later | | `[4..7]` | colour `r, g, b, a` | One layout rather than a described one, because a dynamic mesh is drawn by a single pipeline: letting each geometry declare its own attribute set would buy nothing and cost either a pipeline per layout or a shader that branches per vertex. **Your geometry needs a position attribute and an index.** A colour attribute is optional; without one, every vertex is uploaded white and the mesh's flat `color` is the whole colour. Whatever colour components you do supply (3 or 4) are copied; the rest stay at 1. ```js import { Geometry } from "@woosh/meep-engine/src/shade/renderer/geometry/Geometry.js"; import { Attribute } from "@woosh/meep-engine/src/shade/renderer/geometry/Attribute.js"; import { StandardAttributes } from "@woosh/meep-engine/src/shade/renderer/geometry/StandardAttributes.js"; const geometry = new Geometry(); geometry.setAttribute(Attribute.from(positions, 3, StandardAttributes.Position)); geometry.setAttribute(Attribute.from(colors, 4, StandardAttributes.Color)); geometry.index = Attribute.from(indices, 1, StandardAttributes.Index); ``` There is no material and no lighting on this path - one pipeline, position and colour, straight alpha over the finished scene. That is why path display and debug draw carry no per-object texture, material or lit shading. ### Drawing it `GPUDynamicMeshRenderer` (`src/shade/renderer/dynamic/GPUDynamicMeshRenderer.js`) owns the GPU buffers and records the draws. You put one inside a [render extension](https://meep.company-named.com/docs/rendering/render-extensions/) of your own: ```js import { GPUDynamicMeshRenderer } from "@woosh/meep-engine/src/shade/renderer/dynamic/GPUDynamicMeshRenderer.js"; import { RenderExtension } from "@woosh/meep-engine/src/shade/renderer/extension/RenderExtension.js"; import { FramePhase } from "@woosh/meep-engine/src/shade/renderer/extension/FramePhase.js"; import { SceneColor } from "@woosh/meep-engine/src/shade/renderer/extension/SceneColor.js"; import { ViewTextures } from "@woosh/meep-engine/src/shade/renderer/extension/ViewTextures.js"; class SparkExtension extends RenderExtension { name = "sparks"; phase = FramePhase.AfterTransparency; #mesh_renderer = new GPUDynamicMeshRenderer(); #batch; constructor(batch) { super(); this.#batch = batch; } record(frame) { if (this.#batch.count === 0) { // nothing to draw, and the frame's colour is left exactly as it was return; } const scene = frame.get(SceneColor); const view = frame.get(ViewTextures); const drawn = this.#mesh_renderer.graph_draw({ graph: frame.graph, batch: this.#batch, color: scene.color, depth: view.depth, camera: frame.view.camera.buffer }); scene.color = drawn.color; view.depth = drawn.depth; } } const extension = engine.graphics.add_extension(new SparkExtension(batch)); ``` `graph_draw({graph, batch, color, depth, camera})` returns `{ color, depth }`. Publish the colour into `SceneColor.color` and the depth into `ViewTextures.depth`, as above. An opaque draw produces a new depth handle; later extensions, depth of field, motion blur and the NSS upscaler must consume it. A blended draw returns the input depth unchanged. A development build rejects a frame that reads a superseded depth handle. ### Opaque or blended `GPUDynamicMeshRenderer.opaque` chooses between the two modes, and **it is a property of the pass, not of a mesh** - the whole batch moves together: | `opaque` | Behaviour | |----------|-----------| | `false` (default) | Blended, depth-tested, depth never written. What effects want | | `true` | No blending; the pass writes the depth it is given | Set it before the first draw. Changing it later rebuilds the pipeline, which is cheap but not free. The `true` case exists for a solid surface with no meshlet build behind it - geometry generated on the fly, or decoded out of some other container - which has no depth ordering of its own otherwise, and no CPU sort can give it one: a painter's order over triangles is wrong wherever two of them interpenetrate. For solid content that transparent surfaces should cover, record at `AfterLighting`: transparency then tests against the depth you published. At `AfterTransparency`, transparent surfaces have already been composited into the colour and the dynamic batch draws over them. ### Residency **Residency is keyed on the geometry**, not on batch membership. A mesh that blinks off for a frame, or is removed and re-added, keeps its buffers - which is also why a system should write into the geometry it already holds rather than building a fresh one each frame, or it strands a vertex buffer per frame. A geometry that is gone for good should say so: ```js mesh_renderer.release(geometry); // -> boolean, whether anything was held // on shutdown engine.graphics.remove_extension(extension); mesh_renderer.destroy(); // frees every geometry still held ``` Upload happens inside the pass: every visible mesh's geometry whose `version` has moved is re-interleaved into the fixed layout and written before the draws are executed. --- ## Occlusion is not an API Occlusion culling is GPU-driven inside the rasterizer, and the Hi-Z pyramid is internal to the renderer. There is no occlusion query to issue, no readback to drive from a post-render hook, and nothing to size or register. ## Where to go next - [Rendering overview](https://meep.company-named.com/docs/rendering/overview/) - what the renderer is, the `GraphicsEngine` facade, and the six frame phases. - [Render extensions](https://meep.company-named.com/docs/rendering/render-extensions/) - the mechanism every system on this page registers through. - [Trails](https://meep.company-named.com/docs/rendering/trails/) - `Trail3D`, tubes simulated and extruded on the GPU. - [Meshes & materials](https://meep.company-named.com/docs/rendering/meshes-materials/) - the standard path a dynamic mesh is the exception to. --- # Particles & VFX Section: Rendering Source: https://meep.company-named.com/docs/rendering/particles/ Description: Author GPU particle simulations with ParticleEffect, explicit state layouts and INIT/UPDATE node graphs. Use **`ParticleEffect`** for particle effects in an engine application. Pair it with `Transform64` and register **`GPUParticleEmitterSystem`**. The component holds a compiled simulation program, its particle field layout, texture URL, emission settings, emitter fields and render bindings. The GPU spawns, simulates and draws the particles. Use INIT and UPDATE node graphs to author a `ParticleEffect`; the [migration table](#migrating-particular-effects) maps older Particular effects to this model. The [particles example](https://meep.company-named.com/examples/particles/) contains five effects: buff, magic attack, healing, earth and chimney smoke. **View source** and **Download** include `src/particleGraphs.js`, the complete graph authoring code, plus the layer parameters and curves in `src/specs/`. ## The three parts of a simulation | Part | Responsibility | | --- | --- | | `ParticleLayout` | Declares the named state stored for each particle: position, velocity, age, lifetime, colour, or custom particle fields. | | `INIT` graph | Runs for a newborn: chooses its position, velocity, lifetime and initial appearance. | | `UPDATE` graph | Advances that state and kills expired particles. Nothing ages, moves or expires automatically. | Build ordinary `NodeGraph` objects with `particle_node` and `particle_wire`, then compile them with `create_particle_effect({ layout, init, update })`. The result is `{ layout, program }`, ready to spread into `ParticleEffect.from`. Compile once per effect and share the immutable layout/program between instances. Render bindings connect particle fields to the channels the renderer reads. A graph can store any state it needs, but drawing requires a world-space `position`; `size` is the billboard's **half-extent in metres**, `color` is RGBA, and `orientation` is a unit quaternion (x, y, z, w) that turns the sprite inside its projection mode's frame: under `BILLBOARD` a turn about +Z is a roll, so a roll angle `a` is `vec4(0, 0, sin(a/2), cos(a/2))`, and under `FACING_WORLD` it is the particle's rotation in the world. Optional `frame` and `velocity` bindings support flipbooks and stretched billboards. Build graphs from the stock node types. The engine also ships a library of node groups (`quatFromAxisAngle`, `quatIntegrate`, `sampleRotation` and others, under `shade/renderer/particles/graph/groups/`), but it registers itself through a side-effect import, and the package's `sideEffects` field lets a bundler drop that import: a production Vite or Rollup build of a graph that names a group throws `Unknown particle node type`, while the dev server and Node run it. ## A complete small graph Save this as `riseGraph.js`. It emits white, untextured squares that rise for two seconds, shrink and fade. The example gallery adds textures, random distributions, colour gradients and separate layers to the same structure. ```js import { NodeGraph } from "@woosh/meep-engine/src/core/model/node-graph/NodeGraph.js"; import { ParticleLayout } from "@woosh/meep-engine/src/shade/renderer/particles/layout/ParticleLayout.js"; import { particle_node, particle_wire } from "@woosh/meep-engine/src/shade/renderer/particles/graph/particle_graph_authoring.js"; import { VM_BUILTIN } from "@woosh/meep-engine/src/shade/renderer/particles/isa/ParticleVMISA.js"; import { create_particle_effect } from "@woosh/meep-engine/src/shade/renderer/particles/runtime/create_particle_effect.js"; export function createRiseEffect() { const layout = new ParticleLayout([ { name: "position", components: 3 }, { name: "age", components: 1 }, { name: "size", components: 1 }, { name: "color", components: 4, type: "color" }, ]); // Arrays are literal values; numbers returned by particle_node are node IDs. function node(graph, type, inputs = {}, parameters = {}) { const id = particle_node(graph, type, parameters); for (const [port, source] of Object.entries(inputs)) { particle_wire(graph, id, port, source); } return id; } const write = (graph, name, value) => node(graph, "setParticleField", { value }, { name }); const read = (graph, name) => node(graph, "particleField", {}, { name }); const init = new NodeGraph(); write(init, "position", node(init, "builtin", {}, { id: VM_BUILTIN.EMITTER_POSITION })); write(init, "age", [0]); write(init, "size", [0.1]); write(init, "color", [1, 1, 1, 1]); const update = new NodeGraph(); const dt = node(update, "builtin", {}, { id: VM_BUILTIN.DELTA_TIME }); const age = node(update, "add", { a: read(update, "age"), b: dt }); write(update, "age", age); const expired = node(update, "compare", { a: age, b: [2] }, { op: "ge" }); node(update, "kill", { condition: expired }); const step = node(update, "scale", { v: [0, 0.5, 0], s: dt }); write(update, "position", node(update, "add", { a: read(update, "position"), b: step })); const life = node(update, "div", { a: age, b: [2] }); const fade = node(update, "sub", { a: [1], b: life }); write(update, "size", node(update, "mul", { a: [0.1], b: fade })); write(update, "color", node(update, "vec4", { x: [1], y: [1], z: [1], w: fade })); return create_particle_effect({ layout, init, update }); } ``` The `age` node above feeds both the store and the expiry test. Wiring the new value explicitly makes the data dependency clear. The UPDATE graph reads the particle's stored position, so previously emitted particles stay in world space when the emitter moves. ## Register the system and spawn an effect ```js import { EngineHarness } from "@woosh/meep-engine/src/engine/EngineHarness.js"; import Entity from "@woosh/meep-engine/src/engine/ecs/Entity.js"; import { Transform64 } from "@woosh/meep-engine/src/engine/ecs/transform/Transform64.js"; import { ParticleEffect } from "@woosh/meep-engine/src/engine/graphics/ecs/particles/ParticleEffect.js"; import { GPUParticleEmitterSystem } from "@woosh/meep-engine/src/engine/graphics3/GPUParticleEmitterSystem.js"; import { createRiseEffect } from "./riseGraph.js"; let particles; const engine = await EngineHarness.bootstrap({ configuration(config, engine) { const scene = EngineHarness.shadeScene(engine); particles = new GPUParticleEmitterSystem(engine.graphics, scene, engine.assetManager); config.addSystem(particles); }, }); await EngineHarness.buildBasics({ engine, enableTerrain: false, enableWater: false, enableLights: true, enableShadows: false, distance: 5, }); const effect = ParticleEffect.from({ ...createRiseEffect(), spawn_rate: 30, flags: { soft_depth: true }, render: { position: "position", size: "size", color: "color" }, }); const entity = new Entity() .add(new Transform64()) .add(effect) .build(engine.entityManager.dataset); // Later, in response to gameplay: // effect.emitting = false; // stop spawning; existing particles finish // particles.burst(entity, 40); // queue a one-shot burst ``` The system's `FrameStart` extension enables GPU particles and publishes its shared texture atlas. With the harness, `buildBasics({ enableLights: true })` also connects the scene to the graphics engine. In a custom setup, follow the scene wiring in the [rendering overview](https://meep.company-named.com/docs/rendering/overview/). Assign component fields directly; the system detects changes each frame. Moving `Transform64` still requires `t64_announce_change(dataset, entity)` after updating its matrix. Removing the entity retires its emitter and particles. ### Gameplay bursts and vehicle mounts For a one-shot effect, create an entity with `spawn_rate: 0`, then call `particles.burst(entity, count)`. The system queues that count for the next render frame. Keep the entity alive until the longest particle lifetime has elapsed; removing it also retires its particles. Share the compiled program between bursts and clone the `ParticleEffect` component for each independently placed instance. [Jet Propulsion Alliance](https://meep.company-named.com/examples/jet-propulsion-alliance/) demonstrates continuous exhaust and boost, tyre-dust and collision bursts. Its smoke and dust set `lighting: true`, so their gradients are albedo; the additive boost flame stays unlit. Its `fx/particleGraphs.js` keeps the INIT and UPDATE graphs in source. INIT transforms a sampled emission volume into world space; UPDATE advances the stored position, so old particles stay behind as the car moves. The boost graph applies mount rotation to the emission box while keeping velocity car-backward. When constructing that basis, remember that `EMITTER_DIRECTION` is transformed **−Z**, while `EMITTER_UP` is **+Y**. ## Emitter fields, global fields and transform bindings Beyond per-particle fields (`particleField` / `setParticleField`), an effect's `INIT` and `UPDATE` graphs can read two read-only parameter scopes without recompiling the bytecode: - **Emitter fields (`emitterField` node)** - per-instance values carried on each `ParticleEffect` component so multiple entities sharing one compiled program can vary (e.g. a beam target, tint, or jet strength). Declare them with `ParticleLayout.emitter([...])` and pass `emitter_layout` (and optional default `emitter_fields`) to `create_particle_effect({ layout, init, update, emitter_layout })`. At runtime, update an entity's values with `effect.set_emitter_field(name, values)`. - **Global fields (`globalField` node)** - scene-wide values shared across every effect in the scene. Pass `global_layout: new ParticleLayout([...])` to `create_particle_effect` so the compiler knows each field's component width, and set values at runtime on `GPUParticleEmitterSystem` with `particles.set_global_field(name, values)`. Either scope can also be driven directly on the GPU from any entity's composed `Transform64` every frame using `PARTICLE_FIELD_BINDING_CHANNEL` (`@woosh/meep-engine/src/shade/renderer/particles/data/PARTICLE_FIELD_BINDING.js`): | Channel | Value | Width | Writes | | --- | --- | --- | --- | | `POSITION` | `0` | 3 words | World-space origin `(x, y, z)` | | `DIRECTION` | `1` | 3 words | Normalised world `-Z` axis | | `UP` | `2` | 3 words | Normalised world `+Y` axis | | `ORIENTATION` | `3` | 4 words | World rotation quaternion `(x, y, z, w)` with scale and mirror removed | Bind an emitter field by pushing `{ field, entity, channel }` to `effect.bindings`, or bind a global field with `particles.bind_global_field(name, entity, channel)` (and release it with `particles.unbind_global_field(name)`). Transform bindings are runtime state and are not serialized. ## Textures, curves and layers - **Textures:** set `texture` to an image URL. The asset manager loads it and the system packs images into an atlas, sharing a patch for matching URLs. A missing or pending image samples transparent; `texture: null` samples white. - **Curves:** `curveLiteral` takes an `AnimationCurve`-shaped `{ keys: [{ time, value, inTangent, outTangent }] }`. Tangents are slopes per unit time. The example supplies each segment's slope to retain piecewise linear scale tracks. - **Colours:** `gradientRGBA` takes `stops: [{ position, color: [r, g, b, a] }]`. Feed normalized age (`age / lifetime`) to its `t` input. These values are linear RGBA; alpha is not colour-space converted. - **Randomness:** `random` returns uniform values in `[0, 1)`. Build distributions from nodes; the example shows spherical-volume spawning and conical velocity. Each particle keeps its own sampled base size, lifetime and spin. - **Layers:** one `ParticleEffect` has one texture and one emission rate. Compose a multi-layer effect from several entities. The gallery's five effects contain 13 layers, whose entities follow matching orbits. - **Flipbooks:** `flipbook: [columns, rows]` divides the texture region; bind `render.frame` to a particle field that the graph advances. ## Rendering and capacity The engine advances GPU particles using **simulation seconds since the last drawn frame**. Particle motion, ageing and emission therefore follow the simulation clock's pause and speed modifiers, independent of the display refresh rate. Renderer animation and exposure adaptation use the same delta. Simulation time elapsed while rendering is disabled is included in the next drawn frame. The normal `Engine` loop supplies this delta. If you call `graphics.render(time_delta_seconds)` yourself, pass simulation seconds explicitly to advance the frame; `graphics.render()` defaults to zero and redraws the current state without advancing it. GPU particles draw through the renderer's **AVBOIT** transparency pipeline, compositing with transparent meshes without a particle depth sort. The legacy `MBOIT` mode simulates particles but does not draw them. Keep the renderer's AVBOIT mode for these effects. `flags` accepts `blend` (`EMITTER_BLEND.ALPHA`, `ADDITIVE` or `PREMULTIPLIED`), `projection` (`EMITTER_PROJECTION.BILLBOARD`, `STRETCHED`, `HORIZONTAL`, `VERTICAL` or `FACING_WORLD`), `soft_depth` and `cull`. Import the enums from `shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js`. Set `lighting: true` to treat particle colour as diffuse albedo. The renderer samples the froxel irradiance volume, combining the selected indirect-lighting mode with shadowed directional, point and spot lights, so a lit particle receives the light the surfaces beside it receive. Fog is composited over it afterwards, as over everything else. Light and shadow detail follows the froxel resolution. The Particles example's effects are unlit; Jet Propulsion Alliance lights its smoke and dust. Bounds are measured from live particles on the GPU. There is no authored bounds field. Enable `cull` to allow simulation culling; the example leaves it disabled so the orbiting effects continue while offscreen. Every emitter in a scene draws from one pool, 65,536 particles by default. `renderer.particles(scene_context)` returns that scene's `GPUParticleSystem`, creating it on first use, and its `capacity` can be set at any time: ```js const renderer = engine.graphics.renderer; const scene_context = renderer.scenes.obtain(EngineHarness.shadeScene(engine)); renderer.particles(scene_context).capacity = 262144; ``` The new size takes effect on the next frame. Growing keeps every live particle. Shrinking keeps as many as the smaller pool holds and drops the rest. Spawns past a full pool are dropped. Size it for the sum of emission rate × lifetime across layers, plus bursts and headroom; each particle is a 128-byte record. `prewarm` specifies seconds of simulation before an effect is first shown. It defaults to zero, costs work at registration, and uses at most 32 warmup ticks. Longer durations use larger time steps. ## Migrating Particular effects Meep 3.71.0 does not ship Particular's `ParticleEmitter`, `ParticleEmitterSystem`, `ParticleLayer`, `Sprite` or their serialization adapters. Re-author those effects as `ParticleEffect`; old Particular JSON and binary payloads do not migrate automatically. | Former Particular authoring | `ParticleEffect` authoring | | --- | --- | | `ParticleEmitter.fromJSON(spec)` | Build INIT/UPDATE graphs and compile with `create_particle_effect`. Old JSON is not a `ParticleEffect` program. | | `ParticleEmitterSystem(graphics, assets)` | `GPUParticleEmitterSystem(graphics, scene, assets)` | | `ParticleLayer` | One effect entity per independently textured/emitting layer | | `imageURL`, `emissionRate` | Component `texture`, `spawn_rate` | | Lifetime, size, rotation, speed ranges | Random draws in INIT, stored in layout particle fields | | Emission shape and layer transform | Position-sampling nodes in INIT, added to the emitter's world position | | Full-width particle size | Half-extent `size` binding: divide old sizes by two | | Colour/scale parameter tracks | `gradientRGBA` / `curveLiteral` sampled in UPDATE; initialize appearance in INIT too | | Fixed-physics ageing, movement and death | Explicit age, integration and `kill` nodes in UPDATE | | `Emitting` flag | Component `emitting` boolean | | `PreWarm` flag | `prewarm` duration in seconds | | Rebuild after structural edits | Compile a new immutable program/layout and update render bindings | The engine's serialization registry includes `ParticleEffectSerializationAdapter`, so saved entities carry the compiled program. Authoring graphs need not ship in a game, but **this example keeps them in source to teach the simulation**. ### The GPU particle system Standalone renderer applications can register the renderer's `shade/renderer/particles/runtime/ParticleEmitter.js` node at a scene entity's transform row. That low-level node is the renderer node used by the `ParticleEffect` system. Engine applications should use `ParticleEffect` and let `GPUParticleEmitterSystem` manage registration, transforms and assets. ## Related pages - [Getting started](https://meep.company-named.com/docs/getting-started/) - the ECS and a first rendered scene. - [Particle example and graph sources](https://meep.company-named.com/examples/particles/) - the complete multi-layer effects. - [Jet Propulsion Alliance](https://meep.company-named.com/examples/jet-propulsion-alliance/) - vehicle-mounted effects and gameplay bursts. - [Frame features](https://meep.company-named.com/docs/rendering/frame-features/) - AVBOIT and renderer settings. - [Trails](https://meep.company-named.com/docs/rendering/trails/) - geometry extruded behind moving entities. --- # Trails Section: Rendering Source: https://meep.company-named.com/docs/rendering/trails/ Description: Trail3D - the ECS component that lays a fading world-space tube behind a moving entity, simulated in compute, extruded in the vertex stage and drawn inside the transparency pipeline. A trail records where an entity has been and draws a fading strip of geometry along that path. The engine has one trail component: `Trail3D`, which extrudes a **volumetric tube** around the path in world space, so it has real thickness from every viewing angle. It is a plain ECS component - attach it to an entity that has a `Transform64`, register `Trail3DSystem`, and the engine handles spawning, aging and drawing. `Trail2D` ships as a component but nothing renders it; see [Trail2D renders nothing](#trail2d-renders-nothing) at the end of this page. ## Trail3D `Trail3D` (from `src/engine/graphics/ecs/trail3d/Trail3D.js`) lays down a tube of knots behind the entity. Each knot carries a parallel-transported tangent frame, so the tube's cross-section ring stays smoothly oriented along the centre-line even through tight curves. The component is the trail's description; its knots live on the GPU, where the system simulates and draws them. ```js import { EngineHarness } from "@woosh/meep-engine/src/engine/EngineHarness.js"; import Trail3D from "@woosh/meep-engine/src/engine/graphics/ecs/trail3d/Trail3D.js"; import { Trail3DSystem } from "@woosh/meep-engine/src/engine/graphics3/Trail3DSystem.js"; // Register the system once (at bootstrap), with the scene its entities are in const scene = EngineHarness.shadeScene(engine); config.addSystem(new Trail3DSystem(engine.graphics, scene)); // Attaching to an entity that already exists? Register the component type first. ecd.registerComponentType(Trail3D); const trail = new Trail3D(); trail.maxAge = 0.5; // knots live half a second trail.width = 0.4; // tube diameter, world units trail.color.set(1.0, 0.55, 0.15, 1); ecd.addComponentToEntity(entity, trail); ``` Two import details: the system is a **named** export under `src/engine/graphics3/` and its constructor takes the graphics facade and the scene, as `ShadedGeometrySystem` does; the component is a **default** export. There is no `Trail3DSystem3` - write the unsuffixed `Trail3DSystem`. **The head follows announced transforms.** A trail reads where its entity is from the entity's row in the GPU scene, which a transform write reaches when it is announced. A translation written by hand moves the trail only once it ends with `t64_announce_change(ecd, entity)`, exactly as for a mesh or a particle emitter; systems that announce their own writes (`PhysicsSystem`, `PathFollowingSystem` and the rest) need nothing extra. `Trail3D` properties (all also settable through `fromJSON`): | Property | Type | Default | Notes | |----------|------|---------|-------| | `maxAge` | `number` | `5` | Seconds a knot lives before it disappears; `fade` runs over this span. The [knot count](#knot-count) is taken from it when the system registers the trail | | `width` | `number` | `1` | Tube **diameter**. Written into the head knot every frame, so animating it tapers the tube | | `radialSegments` | `number` | `8` | Subdivisions around the tube, at least 3. Fixed when the system registers the trail - re-add the component to change it | | `spawnMode` | `TrailSpawnMode` | `Time` | When a new knot is committed (see below) | | `spawnDistance` | `number` | `1` | Distance between knots when `spawnMode` is `Distance` | | `color` | `Color` | white | RGB tints the whole tube, in linear colour and unbounded; alpha is the trail's base opacity. Both are read every tick | | `fade` | `AnimationCurve` | `TRAIL3D_FADE_LINEAR` | Opacity over a knot's life: time is age over `maxAge` (`0` at birth, `1` when it disappears), and the value multiplies `color.a` | | `offset` | `Vector3` | `(0,0,0)` | Offset from the entity to the trail head, in the entity's **local** frame - it rides the entity's rotation and scales with it | | `warmup` | `boolean` | `true` | A new trail fades in over its first `maxAge` seconds (see [Warm-up](#warm-up)) | Two more fields are not part of the JSON: `knots`, a `TrailKnots` layout for a trail that is laid down whole (see [Authored knots](#authored-knots)), `null` for a trail the entity draws; and `clearCount`, which `clear()` moves. There is no change signal to send. Once a tick the system compares each component's fields with what it last staged and restages the trails that differ, so a game writes `trail.color` or `trail.width` from code that has never heard of the system. ### Three properties that do nothing `textureURL`, `depthWrite` and `lightingEnabled` exist on the component. They read, they write, they round-trip through `toJSON` / `fromJSON`, and they have no effect on what you see. A trail is drawn by one unlit pipeline whose vertex stage reads a knot's position, frame and thickness and the trail's colour. There is no per-trail material to hang a texture on, no per-trail depth-write switch, and no lighting variant of the shader. All three are accessors over a `TubeXMaterialSpec` the component carries as `trail.material`, `lightingEnabled` through `Trail3DFlags.Lit`. Nothing in the render path reads any of it: the spec is inert bookkeeping that keeps scene JSON round-tripping. A trail that needs to read as lit matter rather than as an emitter is not something this component can do. Either accept the flat colour, or build the geometry yourself on the [dynamic-mesh path](https://meep.company-named.com/docs/rendering/effects/#dynamic-meshes). ### How a trail reaches the screen `Trail3DSystem` simulates every trail on the GPU and draws it **inside the transparency pipeline**, as an AVBOIT transparency channel. A trail composites order-independently against transparent meshes, particles, water and other trails, so a trail behind glass or smoke sits behind it by depth. It tests the opaque scene's depth and never writes depth, both faces of the tube are drawn, and it takes the volumetric fog at its depth. Keep `renderer.transparency_mode` on `ShadeTransparencyMode.AVBOIT` (the default, see [Frame features](https://meep.company-named.com/docs/rendering/frame-features/)): the MBOIT path draws no transparency channels, trails included. **The CPU builds no geometry.** What is the CPU's: registering a trail with the scene's `GPUTrailSystem` (`src/shade/renderer/trails/GPUTrailSystem.js`) - a record, a run of knots in the shared knot pool, the entity's transform row - the once-a-tick comparison of each component's fields, and moving the trails' clock. A frame costs the CPU a comparison per trail, and an upload only for the trails whose fields changed. **Everything per knot is the GPU's.** Each frame a compute pass moves every head to its entity's world matrix, commits a knot when one is due, carries the ring frame along the tangent and finds how many knots can still be visible. A pass per view then drops the segments whose two knots have both faded out or whose bounds miss the frustum. The vertex stage extrudes what is left: each ring vertex sits at `cos(angle) * normal + sin(angle) * binormal`, half the knot's thickness out from its centre. All trails with the same `radialSegments` share one indexed indirect draw in each pass, a segment an instance. A knot stores when it was committed, not how old it is, so nothing rewrites a knot as it ages: a trail that has stopped fades out without further writes, and its faded segments are culled before they reach the rasterizer. **Time is the simulation's.** The trails' clock advances by the delta `Trail3DSystem.update` is given, so a paused game holds its trails still. The head is read when a frame is drawn: a new trail's knots start where its entity stands in the first frame drawn after the component is added. ### Knot count The system sizes the tube from `maxAge` when the trail is registered: **60 knots per second of life, clamped to between 2 and 1024** (`trail_knot_count`, from `src/engine/graphics/ecs/trail3d/trail_knot_count.js`). A 0.5 s trail gets 30 knots, a 3 s trail 180. Past roughly 17 s the cap bites, and a longer `maxAge` buys duration rather than detail - the same 1024 knots are simply spread over more time. The count is fixed from then on. Changing `maxAge` on a live trail moves the fade and how often a knot is laid down, not the length of the ring; re-add the component for a trail that should be resized. ### Spawn modes `TrailSpawnMode` (from `src/engine/graphics/trail/TrailSpawnMode.js`) controls when the head commits a new knot: | Mode | Knots are spaced evenly in | Behaviour | |------|---------------------------|-----------| | `Time` (default) | time | A knot every `maxAge / knotCount` seconds. A fast emitter draws a long trail, a slow one a short trail; both last `maxAge` seconds | | `Distance` | space | A knot every `spawnDistance` world units, regardless of speed - uniform geometry with no stretching under acceleration | Either way a knot is only committed when the head has actually moved, so a stationary emitter does not burn through its knots, and at most one knot is committed per drawn frame. Clearing `Trail3DFlags.Spawning` (`trail.clearFlag(Trail3DFlags.Spawning)`, from `src/engine/graphics/ecs/trail3d/Trail3DFlags.js`) stops the head following the entity: the trail stays where the last frame drew it and fades out. ### Colour, opacity and fading `color` belongs to the trail, not to its knots. RGB tints the whole tube and alpha is the base opacity that the age fade scales, so writing either on a live trail changes the entire tube from the next frame. The colour is linear and unbounded: values above `1` are how a trail is made brighter. The per-knot fade is `trail.fade`, an `AnimationCurve` evaluated at each knot's age over `maxAge`. Every trail starts on `TRAIL3D_FADE_LINEAR` (from `src/engine/graphics/ecs/trail3d/TRAIL3D_FADE_LINEAR.js`), a straight line from full opacity at birth to none at `maxAge`. That one instance is shared by every default trail and frozen, so editing it in place throws: assign a curve of your own, or start from its `clone()`. ```js import { AnimationCurve } from "@woosh/meep-engine/src/engine/animation/curve/AnimationCurve.js"; import { Keyframe } from "@woosh/meep-engine/src/engine/animation/curve/Keyframe.js"; // hold full opacity for the first half of the knot's life, then fall away trail.fade = AnimationCurve.from([ Keyframe.from(0, 1), Keyframe.from(0.5, 1), Keyframe.from(1, 0), ]); ``` The opacity is the tube's as seen. The tube is a closed hull drawn from both sides, so a line of sight crosses two faces; the vertex stage gives each face half the optical depth, `1 - √(1 - α)`, and the two together cover exactly `α`. A curve that overshoots `0..1` is clamped first. To gate a trail on a condition, animating `width` usually reads better than dropping opacity, because `width` is written per head knot: the tube already on screen keeps its thickness and the new end tapers away to nothing, instead of the whole streak dimming at once. ```js // e.g. show the trail only at speed const target = speed > 17 ? 0.55 : 0; trail.width += (target - trail.width) * Math.min(1, dt * 8); ``` ### Warm-up With `warmup` on, the default, a new trail fades in: while the trail is `t` seconds old its head knot is born `maxAge - t` old, so the stretch laid down first is the faintest and the trail reaches its full look after its first `maxAge` seconds. Set `trail.warmup = false` for a trail that must be fully visible from its first frame, a tracer. ### Teleporting the emitter Moving an entity discontinuously (respawn, kickoff reset) would otherwise draw a streak from the old position to the new one. Call `trail.clear()` on teleport: at the next frame every knot expires and collapses onto the head where the entity stands, so no segment can bridge the two. The trail keeps its birth, so its warm-up does not run again. ### Beams: a trail that is born whole A normal trail draws itself by travelling. A beam does not travel - it leaves its source and arrives at its target inside one frame - so there is nothing to lay it down with. `make_gradient_stroke` builds a `Trail3D` that already has its whole shape: a stroke between two world points that only ages. ```js import { make_gradient_stroke } from "@woosh/meep-engine/src/engine/graphics/ecs/trail3d/make_gradient_stroke.js"; const beam = make_gradient_stroke({ from: muzzlePosition, // Vector3, world space to: targetPosition, // Vector3, must not coincide with `from` color: 0xffb02e, // packed RGB thickness: 0.15, // world units duration: 0.35, // seconds to fade out completely age_from: 0.6, // the source end is born 60% through its life age_to: 0, texture: "" // asserted to be a string, but inert - see above }); ecd.addComponentToEntity(entity, beam); ``` The gradient is nothing more than the two ends' starting ages: the end seeded older thins out first, so a stroke whose source end is born most of the way through its life reads as retracting towards its target. `age_from` and `age_to` are fractions of `duration` and are asserted to be in `[0,1]`. `make_gradient_stroke` clears `Trail3DFlags.Spawning` for you, which is what stops the per-frame update dragging the head onto the entity and growing a tail towards it. The entity still needs a `Transform64` - that is `Trail3DSystem`'s dependency - but the stroke does not follow it. ### Authored knots A stroke is the two-knot case of something more general. `trail.knots` takes a `TrailKnots` (from `src/engine/graphics/trail/TrailKnots.js`): knots laid down whole by the author - a stroke, a helix, an arc - instead of by an entity's travel. The knots never move; they only age, and fade by the trail's curve as they do. ```js import { TrailKnots } from "@woosh/meep-engine/src/engine/graphics/trail/TrailKnots.js"; import { Trail3DFlags } from "@woosh/meep-engine/src/engine/graphics/ecs/trail3d/Trail3DFlags.js"; const knots = new TrailKnots(); knots.setCount(count); // at least 2 for (let i = 0; i < count; i++) { knots.setKnot( i, x, y, z, // world position nx, ny, nz, // ring frame's first axis, unit bx, by, bz, // second axis, unit, orthogonal to the first and to the tube's direction thickness, // tube diameter at this knot age // seconds the knot is born having lived ); } trail.knots = knots; trail.clearFlag(Trail3DFlags.Spawning); // the shape is authored; the head must not follow the entity ``` The layout is uploaded when the system registers the trail and again whenever `knots.version` moves, which every `setCount` and `setKnot` does. An authored trail has as many knots as its layout, whatever its `maxAge`; a replaced layout brings its own count. `seed_trail_stroke(trail, from, to, age_from, age_to)` (from `src/engine/graphics/ecs/trail3d/seed_trail_stroke.js`) writes the straight two-knot layout `make_gradient_stroke` uses. ## Live example A sphere flying a figure-eight with a `Trail3D` behind it - drag to orbit, scroll to zoom: ```js import { EngineHarness } from "@woosh/meep-engine/src/engine/EngineHarness.js"; import Entity from "@woosh/meep-engine/src/engine/ecs/Entity.js"; import { Transform64 } from "@woosh/meep-engine/src/engine/ecs/transform/Transform64.js"; import { t64_announce_change } from "@woosh/meep-engine/src/engine/ecs/transform/t64_announce_change.js"; import { ShadedGeometry } from "@woosh/meep-engine/src/engine/graphics/ecs/mesh-v2/ShadedGeometry.js"; import { ShadedGeometrySystem } from "@woosh/meep-engine/src/engine/graphics3/ShadedGeometrySystem.js"; import Trail3D from "@woosh/meep-engine/src/engine/graphics/ecs/trail3d/Trail3D.js"; import { Trail3DSystem } from "@woosh/meep-engine/src/engine/graphics3/Trail3DSystem.js"; import { make_octahedron_geometry } from "@woosh/meep-engine/src/shade/renderer/geometry/primitives/make_octahedron_geometry.js"; import { meshlet_geometry_build_from_geometry } from "@woosh/meep-engine/src/shade/renderer/geometry/meshlet_geometry_build_from_geometry.js"; import { StandardShadeMaterial } from "@woosh/meep-engine/src/shade/renderer/material/StandardShadeMaterial.js"; import { Color } from "@woosh/meep-engine/src/core/color/Color.js"; import Vector3 from "@woosh/meep-engine/src/core/geom/Vector3.js"; const engine = await EngineHarness.bootstrap({ configuration: (config, engine) => { const scene = EngineHarness.shadeScene(engine); config.addSystem(new ShadedGeometrySystem(engine.graphics, scene)); config.addSystem(new Trail3DSystem(engine.graphics, scene)); }, }); await EngineHarness.buildBasics({ engine, enableTerrain: false, enableWater: false, enableLights: true, enableShadows: false, focus: new Vector3(0, 0, 0), distance: 7, pitch: 0.5, yaw: 0.3, showFps: false, }); const ecd = engine.entityManager.dataset; // The emitter: a small bright sphere - a subdivided octahedron, every vertex // of it landing on the radius. const sphereGeometry = meshlet_geometry_build_from_geometry(make_octahedron_geometry(0.22, 3)); const sphereMaterial = new StandardShadeMaterial(); sphereMaterial.diffuse_color.copy(Color.from_sRGB_to_linear(Color.parse("#ffb02e"))); const mesh = ShadedGeometry.from(sphereGeometry, sphereMaterial); // The trail: a 1.2 s orange tube, ~0.3 units thick. 1.2 s of life is 72 knots. const trail = new Trail3D(); trail.maxAge = 1.2; trail.width = 0.3; trail.color.set(1.0, 0.55, 0.15, 1); const t = new Transform64(); t.setTranslation(2.2, 0, 0); // Entity.build registers the component types it carries, so Trail3D needs no // explicit registerComponentType here. const entity = new Entity() .add(t) .add(mesh) .add(trail) .build(ecd); // Fly a figure-eight. The trail's head and the sphere both follow the transform // as the scene holds it, which a translation written by hand reaches only once // it is announced - so the write ends with an announcement. Without it neither // the tube nor the ball moves. const start = performance.now(); engine.graphics.on.preRender.add(() => { const s = (performance.now() - start) / 1000; t.setTranslation( Math.sin(s * 1.7) * 2.2, Math.sin(s * 3.4) * 0.8, Math.cos(s * 1.7) * 2.2, ); t64_announce_change(ecd, entity); }); ``` ## Trail2D renders nothing `Trail2D` (`src/engine/graphics/ecs/trail2d/Trail2D.js`) ships as a component and serializes, and a few utilities reference it. **Nothing draws it.** There is no `Trail2DSystem` and no screen-facing ribbon renderer. A `Trail2D` attached to an entity is inert data. What to use, depending on what the ribbon is for: - **A beam or a streak**: `make_gradient_stroke`, above, which produces a `Trail3D`. - **A trail behind a moving thing**: `Trail3D`, the only trail the engine draws. - **A camera-facing ribbon**: build it yourself on the [dynamic-mesh path](https://meep.company-named.com/docs/rendering/effects/#dynamic-meshes) - a `Geometry` you rewrite each frame inside a `DynamicMesh`, drawn by a render extension of yours. The screen-facing expansion is yours to write, since no shader does it. ## See also - [Effects](https://meep.company-named.com/docs/rendering/effects/) - the dynamic-mesh path, plus decals, outlines and camera shake - [Particles & VFX](https://meep.company-named.com/docs/rendering/particles/) - GPU simulations authored as node graphs with ParticleEffect - [Frame features](https://meep.company-named.com/docs/rendering/frame-features/) - the transparency modes - [Rendering overview](https://meep.company-named.com/docs/rendering/overview/) - what the renderer is and how ECS systems bind to it --- # Virtual texturing Section: Rendering Source: https://meep.company-named.com/docs/rendering/virtual-texturing/ Description: The renderer streams texture pages on demand - opt a material into a VirtualTextureStack and GPU texture memory is bounded by what is on screen instead of by what is loaded. Virtual texturing lets a material sample a texture set far larger than GPU memory - an 8192², 16384² or 65536² albedo/normal/ORM triple - by keeping only the pages the camera can currently see resident. It is a renderer feature, opt-in per material, and it allocates nothing at all until the first material asks for it. Hundreds of virtual textures share one page table, one physical cache and one feedback pass. There is no virtual-texture system, material or page object to construct: the opt-in is one field on the material, and the renderer drives the whole loop. Pre-tiled page files in the coarsest-first `${mip}-${x}-${y}.png` layout are readable too - see [Reading legacy tiles](#reading-legacy-tiles). --- ## Opting a material in Assign a `VirtualTextureStack` to `StandardShadeMaterial.vt_stack`. That is the whole opt-in - registration happens automatically the first time the material is built, and one stack may be shared by any number of materials. ```js import { StandardShadeMaterial } from "@woosh/meep-engine/src/shade/renderer/material/StandardShadeMaterial.js"; import { VirtualTextureStack } from "@woosh/meep-engine/src/shade/renderer/texture/virtual/VirtualTextureStack.js"; import { VTSourceTiled } from "@woosh/meep-engine/src/shade/renderer/texture/virtual/source/VTSourceTiled.js"; const material = new StandardShadeMaterial(); material.vt_stack = VirtualTextureStack.from({ label: "rock", size: 8192, source: new VTSourceTiled({ layers: [ "tiles/rock/albedo/{mip}/{x}_{y}.webp", "tiles/rock/normal/{mip}/{x}_{y}.webp", "tiles/rock/orm/{mip}/{x}_{y}.webp" ] }), wrap: true, uv_set: 0, average_color: [0.4, 0.35, 0.3, 1] }); ``` When `vt_stack` is set, the deferred material pass takes albedo, normal and ORM from the streamed pages and **ignores** `texture_albedo`, `texture_normal` and `texture_orm`. `texture_emissive` stays a regular texture and is sampled normally. ### What a stack is A stack is the unit of virtualization: a set of texture layers that share one UV set and one resolution. The whole set streams, resides and is addressed together - one feedback value, one page-table entry, one residency decision - so the per-pixel addressing work is paid once no matter how many layers the material reads. The standard cache group is three layers, in this order: | Layer | Format | Content | |---|---|---| | 0 | `rgba8unorm-srgb` | albedo (premultiplied on upload) | | 1 | `rgba8unorm` | tangent-space normal | | 2 | `rgba8unorm` | ORM: R = occlusion, G = roughness, B = metalness | A source may provide a subset. Layers it omits fall back per layer in the shader: albedo to the stack's `average_color`, normal to flat +Z, ORM to neutral. ### `VirtualTextureStack.from()` | Option | Default | Meaning | |---|---|---| | `size` | required | Side length in texels. Square, power of two, a multiple of `page_size`, at most 512 pages per axis (65536 texels at the default page size). | | `source` | required | Tile provider - see below. | | `label` | `""` | Name used in error messages. | | `uv_set` | `0` | Which vertex UV set the stack samples: `0` or `1`. A `uv_set: 1` stack re-interpolates uv1 for every sample of that material, emissive included. | | `wrap` | `true` | `true` repeats, `false` clamps to edge. Applied in-shader, not by a sampler. | | `average_color` | `[0.5, 0.5, 0.5, 1]` | Linear-space premultiplied RGBA shown while no page is resident - in practice only for the first frames after registration, before the pinned root page arrives. | `from()` checks that `size` is a non-negative integer and that a source was given; the power-of-two and page-multiple rules are asserted when the stack registers, on first material build. --- ## Tile sources | Source | Constructor | Use for | |---|---|---| | `VTSourceTiled` | `new VTSourceTiled({ layers, legacy_meep_mips })` | Pre-tiled page files fetched over HTTP and decoded with `createImageBitmap` (WebP, AVIF, PNG, JPEG - browser-native, no WASM). One file per page per layer, addressed by a URL template with `{layer}`, `{mip}`, `{x}` and `{y}` placeholders. | | `VTSourceImage` | `new VTSourceImage({ images, wrap })` | Runtime tiling of ordinary decoded images: builds a canvas mip pyramid once, then blits padded tiles on demand. The zero-pipeline adoption path - it wins GPU memory and per-frame bandwidth, not host memory, since the full pyramid stays in canvas memory. | | `VTSourceProcedural` | `new VTSourceProcedural({ latency_ms })` | Labelled debug tiles - colour is the mip actually resident, the text is the page address. `latency_ms` fakes network delay. Also the reference implementation of the source contract. | Import paths follow the module name, for example `@woosh/meep-engine/src/shade/renderer/texture/virtual/source/VTSourceImage.js`. All three are named exports. Serve normal and ORM tiles in a lossless or 4:4:4 profile. Chroma subsampling mangles them. ### The custom source contract A source is any object with these members - there is no base class to extend: | Member | Required | Contract | |---|---|---| | `layer_mask` | yes | Bitmask of layers the source provides, bit 0 = albedo. Defaults to `0b111` if absent. | | `load_page(mip, x, y, signal)` | yes | Resolves to an array with one payload per provided layer (`ImageBitmap`, `OffscreenCanvas`, or `{ data: Uint8Array }`); omitted layers are `undefined`. Each payload is `slot_size` square - that is `page_size + 2 * border`, with the border texels already baked in. Reject with an `AbortError` when `signal` aborts. | | `prepare(geometry)` | no | Called on registration with `{ page_size, border, slot_size, layer_count, size, mip_count }`. This is where a source learns the slot size it must produce. | | `destroy()` | no | Called when the last material referencing the stack unregisters it. | Payloads that do not match `slot_size` are rejected by an assertion, as is a source that omits a layer it declared in `layer_mask`. --- ## Constraints in v1 - **Opaque materials only, and it is asserted.** `material.transparency_mode` must be `TransparencyMode.Opaque` (the default). The alpha-tested visibility pass and the OIT path sample the *regular* albedo texture, where VT residency is not guaranteed, so setting `vt_stack` on an alpha-tested or transparent material fails an assertion rather than rendering wrong. - **Emissive is never virtualized.** It stays a regular texture on the material. - **Feedback covers the primary view only.** The CPU path tracer and the lightmap baker do not sample virtual textures at all - they see the fallback colours. - **Filtering is bilinear with per-pixel nearest mip.** No anisotropy, no trilinear blend between mips. The 4-texel default border already budgets for anisotropy later. - **A stack is at most 512 pages per axis** - 65536 texels at the default 128-texel page - and at most 16 mip levels, both limits set by the bit layout of the feedback request key in `VT_CONSTANTS.js`. - **At most 1022 stacks** may be registered at once - the stack id is 10 bits with `0` and `1023` reserved - and the shared page table is a finite address space besides. Registration throws a plain `Error` (`vt: page table is full` or `vt: stack budget exhausted`) when either runs out. --- ## The residency loop, and what it costs ```pintora activityDiagram start :visibility buffer gives mesh and triangle per pixel; :vt_feedback compute samples one pixel per 4x4 block; :GPU hash set collects unique page requests; :async readback lands one or two frames later; :process_feedback touches resident pages and queues misses; :update uploads arrivals and evicts by LRU; :page table and atlases feed the next material pass; end ``` **Feedback.** After the visibility buffer is resolved, one compute pass walks the primary view at one sample per `feedback_stride`² pixels, jittered over `stride`² frames so every pixel is eventually covered. Each sample recovers the mesh, its material and its stack, computes the UV and analytic gradients with the *same* WGSL chunk the material sampler uses, selects a mip, and inserts a packed `stack:10 | mip:4 | x:9 | y:9` key into a GPU hash set. At 1080p with the default stride of 4 that is about 130,000 samples deduplicated into a 16,384-entry, 64 KB buffer, regardless of how many stacks exist. **Read-back.** The hash buffer is copied to a pooled staging buffer and mapped asynchronously - at most three read-backs in flight, results typically folded in on the next frame. Nothing stalls the frame, and the price is that a page is requested one to two frames after the camera first needs it. The `eviction_protect_window` of 4 frames exists precisely to keep a page that is in flight through this loop from being evicted before its request lands. **Streaming.** `VirtualTextureManager.update()` runs once per frame inside the renderer's frame setup and does the CPU-side work: apply arrived pages within the upload budget, evict by LRU (protected pages excluded, finest mip shed first on ties), flush the page table's dirty rectangles, then issue queued loads coarse-first with exponential backoff on failures. Requests untouched for `queue_stale_window` frames are dropped rather than fetched late. That gives concrete numbers to budget against, at the defaults: | Cost | Default | Note | |---|---|---| | Physical cache | ~64 MB per layer, ~192 MB for the standard three | One 4096² atlas per layer, 30×30 = 900 page slots | | Page table | ~5 MB | One mip-mapped 1024² `r32uint` texture, shared by every stack | | Feedback buffer | 64 KB | Plus one compute dispatch over the primary view per frame | | Upload ceiling | 8 pages per frame | A page is 136² texels per layer, so ~217 KB across the three layers, ~1.7 MB per frame at full budget | | Network concurrency | 32 in-flight loads | Queue capped at 1/3 of cache capacity; stale entries dropped | | Latency to sharp | 1-2 frames of feedback, plus the fetch | The root page of every stack is pinned at registration, so something is always resident once it arrives | **Degradation, not thrash.** Every page-table texel holds the nearest *resident* ancestor rather than a "not resident" marker, so sampling is one `textureLoad` followed by the layer fetches and never a mip walk, and a missing page shows as its parent rather than as a hole. When residency crosses the high watermark the manager raises a global mip bias, so oversubscription costs sharpness instead of collapsing into upload thrash; the bias drops again at the low watermark. --- ## Configuration Geometry freezes at the first stack registration, so `configure()` must be called before any material carrying a `vt_stack` is built. It asserts if called later. The manager lives on the renderer's `GraphicsContext`, reachable once `engine.start()` has resolved (`engine.graphics.renderer` is `null` before that): ```js const renderer = engine.graphics.renderer; renderer.graphics.virtual_textures.configure({ page_size: 128, border: 4, atlas_size: 4096, table_size: 1024 }); ``` | Key | Default | Meaning | |---|---|---| | `page_size` | `128` | Payload texels per page side | | `border` | `4` | Border texels per side, baked into tiles - slot size is 136² at the defaults | | `atlas_size` | `4096` | Physical cache side per layer; capacity is `floor(atlas_size / slot_size)²` | | `table_size` | `1024` | Shared page-table side, in pages. At the default page size this addresses 256 stacks of 8192² or 4 of the maximum 65536² | | `layers` | albedo / normal / orm | Cache group: name, format, premultiply flag | | `hash_capacity` | `16384` | Unique requests the feedback hash set can hold per frame | | `feedback_stride` | `4` | Sample one pixel per stride² block, jittered. Runtime-adjustable | | `max_uploads_per_frame` | `8` | Page-upload budget | | `max_concurrent_loads` | `32` | In-flight source loads | | `request_cap_fraction` | `1/3` | Pending requests capped at this fraction of cache capacity | | `eviction_protect_window` | `4` | Frames a touched page is unevictable, covering read-back latency | | `queue_stale_window` | `30` | Untouched queued requests dropped after this many frames | | `pressure_high_watermark` | `0.9` | Residency fraction at which the mip bias engages | | `pressure_low_watermark` | `0.75` | Residency fraction at which it disengages | ### Switching it off, and looking inside `renderer.feature_virtual_textures` (default `true`) is the global switch, one of the [frame settings](https://meep.company-named.com/docs/rendering/frame-features/). Clearing it stops the feedback pass and all streaming; pages already resident keep rendering, so the picture freezes at its current sharpness rather than reverting to fallback colours. While no stack is registered the feature costs nothing either way - the manager allocates its textures lazily. `renderer.graphics.virtual_textures.stats` is refreshed every `update()` and is the first place to look when streaming misbehaves: ```js const { stacks, resident_pages, cache_capacity, pending_loads, queued_loads, uploads_last_frame, evictions_last_frame, dropped_requests, residency_bias } = renderer.graphics.virtual_textures.stats; ``` A `residency_bias` that never returns to zero, or `evictions_last_frame` tracking `uploads_last_frame`, means the working set does not fit: raise `atlas_size`, lower texture resolution, or accept the blur. --- ## Reading legacy tiles `VTSourceTiled` reads the coarsest-first tiled layout with `legacy_meep_mips: true` - `${mip}-${x}-${y}.png` naming, where mip 0 is the *coarsest* level rather than the finest: ```js const source = new VTSourceTiled({ layers: [ "data/textures/terrain/mega/albedo/{mip}-{x}-{y}.png", undefined, undefined ], legacy_meep_mips: true }); ``` That is the only accommodation. There is no override material and no `makeMaterial()`; you set `vt_stack` on the material you already have. There is no per-system `initialize()`/`setTexture()`/`update()` to call - the renderer drives the whole loop. Stacks are addressed by a 10-bit id in a shared page table, so many can be resident at once. --- ## Virtual textures are not virtual geometry The two share a word and an idea - stream fixed-size pages, keep resident only what is visible. They are separate subsystems with separate file formats and do not depend on each other. Both have renderer integration; virtual geometry requires explicit runtime and feedback setup. | | Virtual texturing | Virtual geometry | |---|---|---| | Streams | texels: albedo, normal, ORM pages | clusters of triangles with their LOD hierarchy | | Opt-in | `material.vt_stack` | `VirtualGeometry` plus scene runtime and feedback setup | | Format | ordinary image tiles, or none for `VTSourceImage` | `.vgeo` container, one per geometry | | Status in 3.71.0 | shipping | GPU cut selection and meshlet expansion, RAM/VRAM residency, and streaming feedback | ### Virtual geometry (`.vgeo`) `.vgeo` is the renderer's container for a meshlet DAG: clusters of at most 128 triangles, grouped and simplified level by level, with error bounds used to pick a cut through the hierarchy per view. The package ships the writer, validator and `VGeoContainerReader` under `shade/renderer/geometry/virtual/format/read/`. The reader opens the header and root page first, fetches requested pages by byte range, and supports eviction. `VGeoResidency` (`.../virtual/runtime/`) owns both residency tiers: a byte budget each for RAM and VRAM, CLOCK eviction under a protect window, and admission against the RAM budget before a page is fetched at all. The `.../virtual/runtime/` directory supplies `VirtualGeometry`, a `MeshletGeometry` subclass backed by an open reader, and the GPU runtime. `GPUSceneContext.enable_virtual_geometry(options)` creates a pool and runtime sharing the renderer's ordinary meshlet storage. The rasterization paths select a view-dependent cut on the GPU and expand it into the same meshlet draw records used by static geometry. The runtime's `tau` controls permitted error in pixels (default `1`). Streaming still needs application setup: `VGeoFeedbackLoop` connects GPU page wants and touches to the residency and the GPU pool. See `shade/playground/vgeo_runtime/` for the complete setup, including `begin_frame` / `end_frame` and feedback readback. The renderer opens one virtual-geometry frame across the main view and shadow graphs. Shadow views select their own cuts, share residency and contribute streaming feedback; pending caster detail can trigger a shadow-map refresh. Loading an ordinary model does not automatically convert it to virtual geometry. For multiple assets, share one `VGeoResidency` and GPU pool across readers; instances of one container share its resident pages. Registration throws if the container's root page cannot fit in RAM and VRAM, so budget for the roots as well as streamed detail. The package's `shade/playground/vgeo_scene/` shows this setup across a whole converted scene. Its asset requests need a server that supports byte ranges with `206` responses; cross-origin hosting must expose `Content-Range`. The cut runtime starts with `max_iterations: 8`. If feedback reports `VGEO_CUT_STAT.QUEUE_REMAINING`, `VGeoFeedbackLoop` calls `runtime.note_incomplete_descent(...)`, increasing the traversal budget for subsequent frames up to `max_iteration_ceiling` (default `64`). Remaining work means incomplete geometry, rather than simply a coarser LOD. `runtime.iteration_escalations` counts these increases. ```js import { vgeo_build } from "@woosh/meep-engine/src/shade/renderer/geometry/virtual/build/vgeo_build.js"; import { VGeoBuildOptions } from "@woosh/meep-engine/src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.js"; // geometry: a `Geometry` in object space const result = vgeo_build(geometry, new VGeoBuildOptions()); result.buffer; // ArrayBuffer - the .vgeo bytes result.page_count; result.levels; // per-level summaries ``` `vgeo_build` takes over the geometry's arrays - welding vertices and re-deriving normals and tangents - so pass a clone if you still need the original. Defaults worth knowing: `codec` is LZ4 at `codec_level` 9 (`LZ4_LEVEL.HC_DEFAULT` - the level is how long the encoder spends looking for matches, not a change to the file: every level writes the same LZ4 block format), `nominal_page_size` is 64 KiB, `level_options.simplification_ratio` is 0.5 (targets half as many clusters in the parent), groups start with 4 clusters, and `weld_ratio` is `1e-5` (the source's own advice is to leave it alone). The page size is a hard decoded-byte cap, advertised by the bounded-pages feature bit. A group cannot be split across pages, so a group larger than the cap makes the build throw; increase the page size and configure the runtime to match. The builder supplies per-vertex normals and tangents even when the input geometry lacks them. Builder support types are grouped under `build/level/`, `build/mesh/`, `build/page/`, `build/partition/`, `build/sphere/` and `build/submesh/`; for example, `VGeoLevelOptions` lives at `shade/renderer/geometry/virtual/build/level/VGeoLevelOptions.js`. Ordinary meshes still use the plain meshlet path - `meshlet_geometry_build_from_geometry()`, a one-time precompute, GPU cluster culling, static residency, no continuous LOD. See [Meshes & materials](https://meep.company-named.com/docs/rendering/meshes-materials/) for that, and [Rendering overview](https://meep.company-named.com/docs/rendering/overview/) for where the visibility buffer that feeds VT feedback comes from. --- # Picking Section: Rendering Source: https://meep.company-named.com/docs/rendering/picking/ Description: PickingSystem answers "what is drawn under this pixel" for entities marked Pickable - an asynchronous, batched read of the GPU's visibility buffer. `PickingSystem` answers one question: what is drawn under this pixel. An entity opts in by carrying a `Pickable` marker, the application hands the system a batch of view points as `PickingQuery` objects, and one `PickingResult` comes back per point. It is the path from a pointer position to an entity id, and it lives at `@woosh/meep-engine/src/engine/graphics3/PickingSystem.js` with the rest of the ECS rendering systems. Three properties change how the calling code is written, and all three are deliberate. ## It is asynchronous and batched, on purpose `pick(queries)` takes an array and returns a promise. There is no synchronous entry point, and there could not be one: the answer is read back off the GPU. A compute pass gathers the queried texels from the frame that draws them, and the results are read when the device has finished with it, so an answer is a frame or two late and arrives for the whole batch at once. Write the calling code as if the answer arrives later, because it does: - The world can change while the question is out. Check `dataset.entityExists(entity)` before acting on a result. - Batch what you can. Asking for four points in one call is one round trip, not four. - Nothing in the current tick can come to depend on the result. ## It picks what was actually drawn The rasterizer already writes, for every pixel, the `meshes` row it drew there and the depth it drew it at. A pick reads those two texels with `textureLoad`, gathers them into a storage buffer and resolves the row back to an entity after readback. The precision is therefore the frame's own: triangle-exact, under skinning, through whatever alpha the material tested - with **nothing kept on the CPU for it.** No bounds, no tree, no per-frame refresh, and no second representation that could disagree with what the player is looking at. Two consequences worth designing around: - **Only what is drawn can be picked.** Something culled, hidden, or standing behind something else is not under that pixel. There is no "everything along the ray" mode, and no way to ask about what is not on screen. - **The answer is the nearest surface, and it is whatever is in front.** A prop with no gameplay meaning standing in front of a chest means "the prop", not "the chest". ## There is no index Nothing pays for picking on a frame where nobody picks, and nothing pays for it per entity either. The system keeps a set of the entities that opted in and nothing else: no spatial structure, no bounds, no per-frame `update` work. A frame with queries waiting adds a compute gather with one thread per query and one readback, carrying eight bytes of results per query; a frame with none adds nothing at all. Both textures are read as bindings, so picking needs neither `COPY_SRC` on the visibility buffer nor an illegal sub-region copy of a depth texture. That also removes a class of bug outright. There is no index to fall out of step with the scene, so a pick can never land on where something used to be. ## Setting it up `PickingSystem` takes one collaborator: the `GraphicsEngine`, whose frames draw the view the picks read. ```js import { EngineHarness } from "@woosh/meep-engine/src/engine/EngineHarness.js"; import { PickingSystem } from "@woosh/meep-engine/src/engine/graphics3/PickingSystem.js"; const engine = await EngineHarness.bootstrap({ configuration(config, engine) { config.addSystem(new PickingSystem(engine.graphics)); }, }); ``` Something still has to get the scene drawn - [meshes & materials](https://meep.company-named.com/docs/rendering/meshes-materials/) covers that side. Three things follow from reading the answer off the frame: - **Anything the renderer draws can be picked.** A pixel names a `meshes` row, and every drawn primitive has one however it got there: a model placed through `SGMesh` and `MeshSystem`, or an entity built directly from a `MeshletGeometry` and a `ShadedGeometry`. There is no separate index to be absent from. - **The opt-in may sit on an ancestor.** A model placed through `SGMesh` does not draw at the entity carrying the component - it draws at the child entities the prefab was spawned into. The system resolves the drawn entity and then walks up `ParentEntity` to the nearest ancestor carrying `Pickable`, so the marker goes on the entity you want back and the primitives beneath it need nothing. - **`PickingSystem.dependencies` is `[Pickable]`.** No transform is required: where a thing is, is where it was drawn. `PickingSystem3` is removed. Import `PickingSystem`. ### The `Pickable` marker ```js import Entity from "@woosh/meep-engine/src/engine/ecs/Entity.js"; import { Pickable } from "@woosh/meep-engine/src/engine/graphics3/Pickable.js"; import { SGMesh } from "@woosh/meep-engine/src/engine/graphics/ecs/mesh-v2/aggregate/SGMesh.js"; import { Transform64 } from "@woosh/meep-engine/src/engine/ecs/transform/Transform64.js"; const model = new SGMesh(); model.url = "/models/crate.glb"; const transform = new Transform64(); transform.setTranslation(3, 0, -2); new Entity() .add(model) .add(transform) .add(new Pickable()) .build(engine.entityManager.dataset); ``` `Pickable` carries no data and has nothing to configure - the picking shape comes from what the entity actually looks like, so there is no second way for it to disagree with the model. It is paid for per entity that asks, which is the point: a level is mostly scenery nobody will ever click on, and scenery costs nothing here. It serializes through `PickableSerializationAdapter` (already in `populateEngineSerializationRegistry`). The adapter writes no bytes: what has to survive a save is that the entity opted in, and the presence of the component is that. ## Queries ```js import { PickingQuery } from "@woosh/meep-engine/src/engine/graphics3/PickingQuery.js"; const query = PickingQuery.from_viewport(0.5, 0.5); // the centre of the view ``` | Field | Type | Meaning | |---|---|---| | `u` | `number` | Across the view. `0` at the left edge, `1` at the right. | | `v` | `number` | Down the view. `0` at the **top** edge, `1` at the bottom. | A query names a **point of the view**, not a ray, because the answer comes off the visibility buffer - the entity the rasterizer drew there, at the depth it drew it - and a ray that does not start at the camera has no pixel to read. It is a fraction rather than a pixel so that a caller holding a pointer position need know nothing about the resolution the frame was drawn at; the frame that answers turns the fraction into the texel it drew. A point outside `[0, 1)` on either axis is off the view: it still produces a result, in order, and that result is a miss. ## Results ```js import { PickingResult } from "@woosh/meep-engine/src/engine/graphics3/PickingResult.js"; ``` | Member | Type | Meaning | |---|---|---| | `entity` | `number` | What was hit, or `PickingResult.NOTHING` (`-1`). | | `position` | `Vector3` | Where the ray met it, in world space. Untouched on a miss. | | `distance` | `number` | How far along the ray that was. `Infinity` on a miss. | | `found` | `boolean` (getter) | `entity !== PickingResult.NOTHING`. | `position` is the world point the pixel's depth stands for, unprojected through what the frame actually projected with rather than through wherever the camera has moved to since; `distance` is how far that point is from the eye that drew it. The contract is positional. A batch always answers with **one result per query, in the order the queries were given**, and a point that found nothing still produces a row - so the two arrays line up by index and a caller never has to search for the answer to its own question. `distance` being `Infinity` on a miss means an unfiltered batch still sorts and compares sensibly. Each query yields whatever was drawn nearest the camera at that pixel. There is no "everything behind it too" mode, no filter callback, and no layer mask - if you need to exclude something, exclude it by not giving it `Pickable`, or filter the entity id after the fact. ## A click, to an entity ```pintora activityDiagram start :pointer position, in viewport pixels; :normalizeViewportPoint, giving clip space; :clip space to a view fraction; :build a PickingQuery; :await pick, one batch; if (hit?) then (yes) :act on result.entity; else (no) :nothing drawn under that pixel; endif end ``` `GraphicsEngine.normalizeViewportPoint(input, result)` turns viewport pixels (origin top-left) into a clip-space point (-1 to 1, +Y up), writing into a `Vector2` you own. A `PickingQuery` wants that same point as a fraction with `v` measured downwards, which is one line either way: `u = (x + 1) / 2`, `v = (1 - y) / 2`. `viewportProjectionRay(x, y, source, direction)` is still there and still builds a world-space ray through the one camera the graphics engine owns - it is what a *terrain* pick or a physics raycast starts from. Picking no longer needs it. ```js import Vector2 from "@woosh/meep-engine/src/core/geom/Vector2.js"; import { PickingQuery } from "@woosh/meep-engine/src/engine/graphics3/PickingQuery.js"; import { PickingSystem } from "@woosh/meep-engine/src/engine/graphics3/PickingSystem.js"; const picking = engine.entityManager.getSystem(PickingSystem); const clip = new Vector2(); engine.devices.pointer.on.tap.add(async (position) => { engine.graphics.normalizeViewportPoint(position, clip); const [result] = await picking.pick([ PickingQuery.from_viewport((clip.x + 1) / 2, (1 - clip.y) / 2), ]); if (!result.found) { return; } const dataset = engine.entityManager.dataset; if (!dataset.entityExists(result.entity)) { // the level went away, or that entity did, while the question was out return; } console.log("picked", result.entity, "at", result.distance, result.position); }); ``` `on.tap` sends `(position, event)`, where `position` is the pointer device's own live `Vector2` - safe to read synchronously, which is all the first two lines do. To ignore clicks that landed on UI rather than on the game field, compare `engine.devices.pointer.getTargetElement()` against `engine.graphics.domElement` before building the query. `TooltipComponentSystem` (`src/engine/graphics3/TooltipComponentSystem.js`) does exactly that and is the reference consumer of this API in the engine: it converts the pointer the same way, awaits a one-query batch every tick, and acts on whatever comes back without checking whether the pointer moved in the meantime - the answer describes where the pointer was, the next tick asks about where it is now. ## Entities whose model has not arrived An entity can be `Pickable` and still not be findable, because its model has not loaded and nothing has yet been drawn for it. Nothing has to notice the moment that changes: the opt-in is a set membership, and the first frame that draws the model is the first frame that can answer for it. The reverse costs nothing either - a model that goes away stops being drawn, and the entity keeps its opt-in. Two counters are exposed as diagnostics. `picking.pickable_count` is how many entities have opted in; `picking.waiting_count` is how many batches have been asked and not yet answered by a frame. Neither is a count of what is pickable on screen right now - only a frame knows that. ## What picking does not cover Picking is one narrow tool: a point of the view in, an entity id out, at the precision of whatever was drawn there. Three neighbouring questions go somewhere else entirely. | The question | The tool | |---|---| | What did the player click on? | `PickingSystem.pick` | | Where on the ground did the player click? | `Terrain.raycastFirstSync`, or the `pick()` grid helper | | Does this ray hit something solid, and at what angle? | `physics.raycast` - see [spatial queries](https://meep.company-named.com/docs/physics/queries/) | | Would a body fit here? Sweep a shape? | `physics.overlap` / `physics.shapeCast` | **Terrain picking does not come through here.** Terrain carries no `Pickable`, and the answer wanted from it is a place rather than an entity. A terrain hit is an exact raycast against the terrain's own height representation: `Terrain.raycastFirstSync(surfacePoint, ox, oy, oz, dx, dy, dz)` fills a `SurfacePoint3` with a position *and a normal*, synchronously. `pick(x, y, graphics, terrain, callback)` in `@woosh/meep-engine/src/engine/ecs/grid/pick.js` wraps the whole thing - it does the viewport-to-ray conversion itself and hands the callback the hit in grid coordinates as well as world coordinates. Reach for it whenever the answer you want is a place rather than an entity; it is more precise than picking, not less. **Physics raycasts are a different world.** [Spatial queries](https://meep.company-named.com/docs/physics/queries/) run against colliders in the physics world, and they are synchronous, exact against each shape, accept a `filter(entity, collider)`, and report surface normals. Reach for `physics.raycast` when the question is about the simulated world - line of sight, a projectile, a ground probe, "what would this bullet hit". Reach for `PickingSystem` when the question is about what the player is pointing at on screen and the answer you want is an entity id. An entity can have a collider and no `Pickable`, or the reverse; the two indexes are unrelated. Finally, picking is not a general CPU raycast against a mesh. For triangle-accurate intersection against one specific primitive there is `ShadedGeometry.query_raycast_nearest(contact, ray, transform_matrix4)` - `contact` is a `SurfacePoint3`, `ray` a 6-tuple `[ox, oy, oz, dx, dy, dz]`, and `transform_matrix4` a 16-element matrix array. It requires a decoded `Geometry`: a `MeshletGeometry` keeps its triangles quantized inside meshlet pages, so a `ShadedGeometry` placed from a loaded model cannot be asked this without decoding it first via `geometry_build_from_meshlet_geometry`. It is a tool for tooling, not for gameplay. ## See also - [Rendering overview](https://meep.company-named.com/docs/rendering/overview/) - the `GraphicsEngine` facade that supplies `normalizeViewportPoint` and `viewportProjectionRay`, and the rest of the rendering systems. - [Meshes & materials](https://meep.company-named.com/docs/rendering/meshes-materials/) - `MeshSystem`, `SGMesh`, and the loaders that get something drawn for picking to find. - [Spatial queries](https://meep.company-named.com/docs/physics/queries/) - `physics.raycast` and the collider world, for the questions picking does not answer. --- # Render extensions Section: Rendering Source: https://meep.company-named.com/docs/rendering/render-extensions/ Description: How an application records its own work into the renderer's frame - the six FramePhase injection points, RenderExtension, the typed frame records, declared ordering, and registration through the graphics engine. The renderer's frame is a closed sequence with declared injection points. You do not insert a pass wherever you like; you write a `RenderExtension`, declare which phase it belongs to, and it records into that frame's graph when the phase comes round. This is the whole extensibility surface: there is no plugin stack and no framebuffer registry. The engine's own extensions use this mechanism; the table at the end of this page lists worked examples. The extension types themselves - `RenderExtension`, `FramePhase`, `FrameContext`, `FrameRecord` and the four built-in records - all live in `@woosh/meep-engine/src/shade/renderer/extension/`, and every export there is named. ## The six phases `FramePhase` is a plain enum of six numbers, and the order below is the order they occur in. ```pintora activityDiagram start :FrameStart; :visibility buffer and G-buffer; :AfterGBuffer; :clustered lighting, deferred shading, volumetrics; :AfterLighting; :transparency; :AfterTransparency; :TAA or NSS upscale - resolution changes here; :BeforePresent; :tonemap to canvas; :Overlay; end ``` Each phase names a moment where a specific set of frame records exists and is stable, and an extension registered against one is handed exactly those. | Phase | Value | What has happened | Records carried | |---|---|---|---| | `FrameStart` | 0 | The view is updated and nothing has been rasterized. The phase for per-frame GPU compute later phases depend on: a visibility grid update, a custom cull, a procedural buffer build. | none | | `AfterGBuffer` | 1 | Albedo, normal, PBR and emissive are written and readable, and nothing is lit. The phase for surface work. | `GBufferTextures`, `ViewTextures` | | `AfterLighting` | 2 | Opaque surfaces are lit and composited and volumetrics are over them. Transparency has not run, so anything drawn here is something transparent surfaces should blend over. | `SceneColor`, `GBufferTextures`, `ViewTextures` | | `AfterTransparency` | 3 | The complete scene, still HDR and still at the internal render resolution. Where an extension drawing into the scene belongs unless it has a reason to be past the upscale. | `SceneColor`, `GBufferTextures`, `ViewTextures` | | `BeforePresent` | 4 | The end of the post chain, immediately before tonemapping and after the upscale: still HDR, at output resolution. The last phase whose output goes through the tonemapper. | `SceneColor`, `GBufferTextures`, `ViewTextures` | | `Overlay` | 5 | After tonemapping, drawing onto the canvas in display space. Nothing further processes this, which makes it the phase for interface: overlays and gizmos. | `PresentTarget` | `frame_phase_name(phase)` from the same module turns a value back into its name for a diagnostic. **The upscale is a phase boundary, and it is the one thing about the frame you cannot assume away.** `AfterGBuffer`, `AfterLighting` and `AfterTransparency` run at the internal render resolution; TAA or the NSS upscaler resolves to the output resolution, so `BeforePresent` and `Overlay` are on the far side of it. With `feature_taa_enabled === false` there is no upscale and both sides are the same size. Never state a resolution as a constant - ask `frame.resolution`, which is derived from the live handle and is right in every configuration, dynamic resolution scaling included. Before the upscale is the common case and the design leans on it: work at `AfterTransparency` is temporally resolved, upscaled and sharpened along with everything else, and it draws at internal resolution. `BeforePresent` is the deliberate other choice, and a trade rather than an upgrade - work there gets no temporal history and pays for full-resolution pixels. ## A minimal extension This one draws a batch of dynamic meshes into the scene. It is the shape every shipped extension has, and it is close to what `PathDisplaySystem` and `DebugDrawSystem` actually do. ```js import { RenderExtension } from "@woosh/meep-engine/src/shade/renderer/extension/RenderExtension.js"; import { FramePhase } from "@woosh/meep-engine/src/shade/renderer/extension/FramePhase.js"; import { SceneColor } from "@woosh/meep-engine/src/shade/renderer/extension/SceneColor.js"; import { ViewTextures } from "@woosh/meep-engine/src/shade/renderer/extension/ViewTextures.js"; import { GPUDynamicMeshRenderer } from "@woosh/meep-engine/src/shade/renderer/dynamic/GPUDynamicMeshRenderer.js"; import { DynamicMesh } from "@woosh/meep-engine/src/shade/renderer/scene/DynamicMesh.js"; import { DynamicMeshBatch } from "@woosh/meep-engine/src/shade/renderer/scene/DynamicMeshBatch.js"; export class MarkerExtension extends RenderExtension { name = "markers"; phase = FramePhase.AfterTransparency; #renderer = new GPUDynamicMeshRenderer(); #batch = new DynamicMeshBatch(); /** * @param {Geometry} geometry a plain Geometry - position attribute and an index * @param {number[]} color RGBA, multiplied with any per-vertex colour * @returns {DynamicMesh} */ add(geometry, color) { const mesh = DynamicMesh.from(geometry, color); // its own transform, with nothing above it - identity until moved, and these // vertices are already in world space this.#batch.add(mesh); return mesh; } record(frame) { if (this.#batch.count === 0) { // nothing to draw, and the frame's colour is left exactly as it was return; } const scene = frame.get(SceneColor); const view = frame.get(ViewTextures); const drawn = this.#renderer.graph_draw({ graph: frame.graph, batch: this.#batch, color: scene.color, depth: view.depth, camera: frame.view.camera.buffer }); scene.color = drawn.color; view.depth = drawn.depth; } destroy() { this.#renderer.destroy(); this.#batch.clear(); } } ``` ```js import { make_box_geometry } from "@woosh/meep-engine/src/shade/renderer/geometry/primitives/make_box_geometry.js"; const markers = engine.graphics.add_extension(new MarkerExtension()); const geometry = make_box_geometry(1, 1, 1); markers.add(geometry, [1, 0.2, 0, 0.8]); // the vertices are yours to rewrite; nothing watches the arrays geometry.needsUpdate = true; // ... later engine.graphics.remove_extension(markers); markers.destroy(); ``` `GPUDynamicMeshRenderer` is the path for content whose vertices change every frame - ribbons, path tubes, debug lines. It takes a plain `Geometry`, not a `MeshletGeometry`, and is covered on [effects](https://meep.company-named.com/docs/rendering/effects/). An extension is not obliged to use it: `frame.graph` is the frame's own graph and anything you can record into a frame graph is fair game - meep's own `DecalExtension` is the shipped example, compositing into the G-buffer through a pass of its own rather than through this one. `graph_draw` returns `{ color, depth }`. Publish both handles as above: an opaque dynamic draw writes a new depth version, and later passes must read that version. A blended draw returns the input depth unchanged. ## The declarations `RenderExtension` is a named object with three declarative fields and one method. | Member | Default | What it is | |---|---|---| | `name` | `""` | Stable identity. It names the graph scope this extension's passes land in, it is what an ordering diagnostic and a decorated error say, and it is the ordering tie-break. | | `phase` | `AfterTransparency` | Which phase it records at. Read at registration to pick the bucket, and read again by `remove_extension` to find it - so do not change it once the extension is registered. | | `relative_order` | `0` | Finite numeric order within the phase; lower runs first. Read at registration. | | `record(frame)` | no-op | Called once per frame when the phase comes round, inside a graph scope named after the extension. **Returns nothing.** | An extension with nothing to draw this frame returns from `record` without recording, and that is the only "off" switch there is - no enabled flag, no null pass. If `record` throws, the registry rethrows it wrapped as `Render extension '' failed to record at ` with the original on `cause`, and closes the graph scope so the real error is not buried behind an unbalanced-scope failure. ## Records are the channel `record(frame)` returns nothing. Everything an extension exchanges with the frame goes through typed **records**: you read a frame-graph handle out of one and write a replacement back, and **writing a field is publication** - everything after you carries what you left. There is no privileged resource. The scene colour is published exactly the way a G-buffer target is, and exactly the way a record of your own is. | Record | Fields | Carried at | Writable at | |---|---|---|---| | `SceneColor` | `.color` - the frame's colour, HDR | `AfterLighting`, `AfterTransparency`, `BeforePresent` | wherever carried | | `GBufferTextures` | `.albedo` (ambient occlusion in alpha), `.normal`, `.pbr`, `.emissive` | `AfterGBuffer` through `BeforePresent` | **`AfterGBuffer` only** | | `ViewTextures` | `.depth`, `.depth_previous`, `.visibility` (one `r32uint` word a pixel: a visible-meshlet slot and the triangle in it), `.visible_meshlets` (the table that resolves the slot to a meshlet and mesh row), `.velocity` (`rgba16float` motion since the last frame, jitter-free: in xy the pixels from last frame's place to this frame's, in z the view depth now less then) | `AfterGBuffer` through `BeforePresent` | wherever carried; `.velocity` reaches the renderer only from `AfterGBuffer` | | `PresentTarget` | `.canvas` | `Overlay` only | `Overlay` | Three of those rows are the whole reason phases exist. - **`SceneColor` is not carried at `Overlay`.** A texture may not be a render attachment and a sampled source in the same pass, so at `Overlay` the canvas is written and cannot be read. An effect that needs the finished image as *input* - a colour grade, a full-screen re-composite, fog over the whole frame - belongs at `BeforePresent`. You find that out from `frame.get(SceneColor)`, which fails with a sentence naming the phases that do carry it, rather than from a `-1` failing inside a binding builder. - **`GBufferTextures` is in/out at `AfterGBuffer` and frozen afterwards.** Changing surface properties means reading the targets, writing replacements and publishing the new handles: two of the four are integer formats and cannot be blended, and nothing can be attachment and source at once. It stays *readable* to `BeforePresent` because outline and selection effects legitimately read it late - and at that phase it is on the far side of the upscale and is therefore **a different size from the colour beside it**. `frame.describe(handle)` is how a pass working across that boundary learns the ratio. - **`PresentTarget` has one field and is not called `SceneColor` on purpose.** There is no colour there to be tempted by. Keep the existing contents with a `load` op, write only your own pixels, and publish the result back - that is what lets two overlay extensions compose, the second drawing over what the first left. `ViewTextures.velocity` is filled from depth and visibility before `AfterGBuffer`. An extension that draws surfaces the visibility buffer cannot describe writes their pixels' motion over it at that phase and publishes the handle it wrote, so temporal passes reproject them correctly; a velocity published at a later phase reaches nothing the renderer runs. `SceneColor.copy` (a readable snapshot of the colour as the phase began) is deliberately absent, not missing. It is an optional frame product, and there is no delivery mechanism for it yet. Every field getter and setter goes through a guard, so the failures are named rather than mysterious: reading a field the frame has not filled in, publishing into a record that is frozen at this phase, publishing a superseded handle, or touching a record after its frame has closed each assert at the line that caused it. Those guards are assertions, and a production build strips them - develop against a build that keeps them. ## Publishing a record of your own The vocabulary is open. An extension can publish a record for another extension to read, and doing so costs no edit to the renderer. ```js import { FrameRecord } from "@woosh/meep-engine/src/shade/renderer/extension/FrameRecord.js"; export class VisibilityGrid extends FrameRecord { #grid = -1; static is_present_at(phase) { return true; } get grid() { return this.read(this.#grid); } set grid(handle) { this.#grid = this.publish(handle); } } ``` ```js // in an extension at FrameStart frame.create(VisibilityGrid).grid = record_the_grid_update(frame.graph); // in another extension, at a later phase if (frame.has(VisibilityGrid)) { const grid = frame.get(VisibilityGrid).grid; } ``` | Member | What it does | |---|---| | `static is_present_at(phase)` | Phases the frame carries this record at. Answered before an instance exists, which is what lets `get` say where a record *is* carried rather than only that it is not here. Defaults to every phase. | | `static is_writable_at(phase)` | Phases a field may be published into. Never wider than `is_present_at`. Defaults to it. A record that is carried but not writable is *frozen* - `GBufferTextures` after shading is the case that matters. | | `read(handle)` | The guard a field's getter goes through. | | `publish(handle)` | The guard a field's setter goes through, and the reason publication is a plain assignment. | `frame.has(T)` / `frame.get(T)` / `frame.create(T)` are three calls rather than one `get_or_create` because **absent has to stay distinguishable from empty.** `create` throws if the frame already carries that type; `get` throws with the phases the type is carried at. The renderer publishes the four built-in records through the same `create`, so there is one mechanism, not two. Publication is the naming step, not the dependency edge: `FramePassBuilder.write` renames a written resource into a versioned clone and records the read, so "this pass consumed the colour as it stood and produced a new one" is already a graph fact. Publishing decides which handle currently *means* "the scene colour". ## Ordering Order is declared, never emergent. ```js import { RenderExtension } from "@woosh/meep-engine/src/shade/renderer/extension/RenderExtension.js"; import { FramePhase } from "@woosh/meep-engine/src/shade/renderer/extension/FramePhase.js"; class DebugMarkersExtension extends RenderExtension { name = "debug markers"; phase = FramePhase.AfterTransparency; relative_order = 1000; } ``` - `relative_order` only orders extensions **within one phase**. Negative values run earlier; positive values run later. The phases already order work across phase boundaries. - Two extensions with the same numeric order record in **ascending `name` order**. If both keys match, their registration order is retained. - The registry reads the order at registration, rather than per frame. Remove and re-add an extension after changing its order. There are no class-based `before` or `after` constraints. - An extension cannot be registered or removed from inside `record`. The three built-in `AfterTransparency` extensions resolve to **outline, path display, debug draw**. The first two use order 0 and record by name; debug draw uses 1000. Decals run at `AfterGBuffer`, with order 1; terrain texturing is already complete in the material pass. ## What keeps your work alive The frame graph elides work whose output nothing consumes, and that applies to an extension exactly as it does to a built-in pass. - Thread a result into a record and it is consumed. - Write something imported - the canvas, an imported texture - and the graph treats it as a side effect automatically. - For work that must run regardless, say so with `make_side_effect()` on the pass builder. An upload that writes a GPU buffer the graph does not know about is the usual case: ```js const upload = {}; frame.graph.add("markers / upload", upload, (data, resources, execution) => { write_the_table(execution.graphics); }).make_side_effect(); ``` **An extension whose whole recording is elided is a correct, cheaper frame, not a failure**, and nothing reports it as one. It is a grey cluster with your extension's name on it in a graph dump. ## The rest of `FrameContext` | Member | What it is | |---|---| | `frame.graph` | The frame's `FrameGraph`. Record into it with `graph.add(name, data, execute)` and the builder's `create` / `read` / `write`, exactly as the built-in passes do. | | `frame.view` | The `GPUViewContext` being drawn: `camera` (whose `.buffer` is what a draw pass binds), `scene`, `resolution`, `frame_index`. | | `frame.phase` | Which phase this is. | | `frame.resolution` | `[width, height]` of what this phase draws into, read from the live handle - so it follows a publication, and the second extension on a phase is told the size the first one left. At `FrameStart` nothing is drawn and it is the view's internal size. **Read it inside `record`, not inside a pass callback**, which runs long after the frame has moved on. | | `frame.describe(handle)` | The descriptor of any resource in the frame's graph. For a texture that is a `TextureResourceDescriptor` - `.resolution`, `.format`, `.usage`, `.mipLevelCount`. The general form of `resolution`, and what a pass relating two differently sized resources needs. | | `frame.is_open` | Records are per-frame. A record held past the end of the frame is a retained handle by another name, and both reading and publishing through one say so. | A pass that needs a scratch texture of its own creates one through the builder, describing it with `TextureResourceDescriptor.from({ resolution, format, usage })` from `@woosh/meep-engine/src/shade/device/graph/TextureResourceDescriptor.js`. It is a transient graph resource: the graph decides its lifetime, and the GPU texture behind it is pooled by descriptor and handed to whoever asks for the same shape next. ## Registering Register through the graphics engine, not through the renderer. ```js import { FramePhase } from "@woosh/meep-engine/src/shade/renderer/extension/FramePhase.js"; const markers = engine.graphics.add_extension(new MarkerExtension()); // returns the extension engine.graphics.extension_count(FramePhase.AfterTransparency); // number engine.graphics.remove_extension(markers); // boolean: was it registered ``` **Registering does not require a device.** `GraphicsEngine` holds the extensions itself and applies them to the renderer when one exists, and again after a restart - so a system can register at startup without knowing where in the lifecycle it is, and `start` -> `stop` -> `start` keeps its extensions. `Renderer` carries the same three methods, but an extension registered straight on the renderer is lost the next time one is built. `extension_count(phase)` is read-only and deliberately narrow: it says how many extensions are registered against a phase, not what they are, which is enough for a system to prove it registered and enough for a test to prove teardown leaks nothing. Every rendering system meep ships follows the same shape: ```js async startup(entityManager) { this.#extension = this.#graphics.add_extension(new MarkerExtension(this)); } async shutdown(entityManager) { if (this.#extension !== null) { this.#graphics.remove_extension(this.#extension); this.#extension = null; } } ``` ## What meep ships These extensions sit beside the ECS systems that own them in `@woosh/meep-engine/src/engine/graphics3/`. All are named exports except `GPUParticleAtlasExtension`, which is internal to `GPUParticleEmitterSystem`, and `Trail3DFrameExtension`, which is internal to `Trail3DSystem`; register the system to get either. | Class | Module | `name` | `phase` | `relative_order` | |---|---|---|---|---| | `GPUParticleAtlasExtension` (internal) | `GPUParticleEmitterSystem.js` | `"gpu particle atlas"` | `FrameStart` | 0 | | `DecalExtension` | `DecalSystem.js` | `"decals"` | `AfterGBuffer` | 1 | | `WaterExtension` (diagnostics only) | `WaterSystem.js` | `"water"` | `BeforePresent` | 0 | | `WaterSurfaceExtension` | `WaterSystem.js` | `"water surface"` | `FrameStart` | 0 | | `OutlineExtension` | `OutlineSystem.js` | `"outline"` | `AfterTransparency` | 0 | | `PathDisplayExtension` | `PathDisplaySystem.js` | `"path display"` | `AfterTransparency` | 0 | | `Trail3DFrameExtension` (internal) | `Trail3DSystem.js` | `"trails"` | `AfterLighting` | 0 | | `DebugDrawExtension` | `DebugDrawSystem.js` | `"debug draw"` | `AfterTransparency` | 1000 | Debug draw's order puts developer geometry over every scene overlay, so a gizmo stays readable over an outline or a path. The trails' extension draws nothing itself: it records the trails' compute simulation once the frame's transforms are composed, and the tubes are then drawn inside the transparency pipeline, through a transparency channel `Trail3DSystem` registers with `engine.graphics.add_transparency_channel(...)`. --- Related: [rendering overview](https://meep.company-named.com/docs/rendering/overview/) for the frame as a whole, [effects](https://meep.company-named.com/docs/rendering/effects/) for the dynamic-mesh path an extension usually draws with, and [trails](https://meep.company-named.com/docs/rendering/trails/) for a system that pairs an extension with a transparency channel. --- # Frame settings & post-processing Section: Rendering Source: https://meep.company-named.com/docs/rendering/frame-features/ Description: Every renderer.feature_* switch with its verified default, the resolution and upscaler controls, the post-process sub-objects, and what ships in the tree without being wired into the frame. The renderer has one frame, and it is configured by plain fields on the `Renderer` rather than by composing effects. There is no post-process stack to build and nothing to register: every stage below already exists in the frame and is switched on or off where it stands. Reach the renderer from an application as `engine.graphics.renderer`, or hold the `Renderer` you constructed yourself. ```js const renderer = engine.graphics.renderer; // null before Engine.start(), null again after stop() renderer.feature_motion_blur_enabled = true; renderer.motion_blur.strength = 2.0; renderer.feature_dof_enabled = true; renderer.dof.applyPreset("cinematic"); renderer.dof.focusOnNearest(); ``` `GraphicsEngine` deliberately exposes almost none of this itself - `renderer` is the escape hatch, and it is `null` outside a started engine, so check it. See [Rendering overview](https://meep.company-named.com/docs/rendering/overview/) for the facade. ## Frame timing The engine passes simulation seconds since the last drawn frame into `GraphicsEngine.render(dt)`. GPU particles, renderer animation and exposure adaptation advance by that delta, following the simulation clock's pause and speed modifiers. Time accumulated while rendering is disabled is included in the next drawn frame. When driving the renderer yourself, pass the delta to `renderer.render(camera, scene, dt)` (or `graphics.render(dt)` through the engine facade). Both default to zero: omitting the delta redraws the current state without advancing simulation. ## Feature switches Every one is a boolean on `Renderer`, readable and writable at any time. Defaults are read from `shade/renderer/Renderer.js`. | Switch | Default | What it does | |---|---|---| | `feature_shadows_enabled` | `true` | Master shadow switch. When off the shadow context is disabled and `CASTS_SHADOW_BIT` is cleared on every light record, so no map is selected or rasterized. | | `feature_tetrahedron_point_shadows` | `false` | Generate point-light shadows with the tetrahedral (4-face) path instead of cube (6-face). Same octahedral atlas encoding either way, so it is safe to flip at runtime; it exists for A/B comparison. | | `feature_ssao_enabled` | `true` | GTAO - ground-truth ambient occlusion plus bent normals. The result lands in the alpha channel of the G-buffer albedo target, which is why `GBufferTextures.albedo` carries AO. | | `feature_ssr_enabled` | `false` | Screen-space reflections in every indirect-lighting mode, with the selected mode supplying fallback specular lighting. In `Brick4`, `ProbeClipmap` and `ScreenProbes`, enabling SSR forces the split indirect-lighting path. | | `feature_restir_di_enabled` | `false` | ReSTIR DI - stochastic screen-bounded direct shadowing of point and spot lights. When on, the deferred pass skips its froxel cluster loop entirely and consumes the ReSTIR-resolved radiance. | | `feature_taa_enabled` | `true` | The temporal resolve, and with it the upscale. The setter resets the temporal filters (SSAO, SSR, TAA, NSS, volumetrics and the screen probes) on a transition without clearing path-tracer accumulation, because the history textures go stale while it is off. | | `feature_sharpening_enabled` | `true` | FidelityFX RCAS, at a fixed sharpness of `0.8`. | | `feature_bloom_enabled` | `true` | Karis-average downsample chain plus tent upsample. The chain also feeds auto-exposure, so it is built when either this or `feature_automatic_exposure_enabled` is on. | | `feature_automatic_exposure_enabled` | `true` | Luminance-histogram eye adaptation. When off, `exposure_compensation` is the fixed value. | | `feature_motion_blur_enabled` | `false` | Jimenez 2014 reconstruction filter. Configure via `renderer.motion_blur`. | | `feature_dof_enabled` | `false` | Depth of field. Configure via `renderer.dof` / `renderer.dof_unreal`, select with `dof_algorithm`. Silently skipped unless `camera.isPerspectiveCamera === true` - the thin-lens circle of confusion has no meaning under orthographic. | | `feature_virtual_textures` | `true` | System-wide kill switch for [virtual texture](https://meep.company-named.com/docs/rendering/virtual-texturing/) streaming. When off, feedback and residency maintenance stop; already-resident pages keep rendering. Costs nothing while no stack is registered. | | `feature_particles_enabled` | `false` | GPU particles. `GPUParticleEmitterSystem` enables this for `ParticleEffect` entities. Every registered renderer emitter node is simulated on the GPU each frame and drawn through the AVBOIT transparency pipeline, order-independently against the transparent meshes and the opaque scene. The pool every emitter of a scene draws from is sized through `renderer.particles(scene_context).capacity`; see [Particles & VFX](https://meep.company-named.com/docs/rendering/particles/). | | `feature_path_tracing_enabled` | `false` | Replaces the rasterized colour with `renderer.path_tracer`'s accumulation for the frame. Prototype-grade. Turn TAA off while it is on - two temporal filters fighting over one image. | | `feature_velocity_debug_view` | `false` | Debug: draws the per-object velocity buffer instead of the shaded image, before TAA. | Non-boolean knobs on the same object: | Property | Default | What it does | |---|---|---| | `indirect_lighting_mode` | `ShadeIndirectLightingMode.IBL` | `IBL: 0`, `Brick4: 1`, `ProbeClipmap: 3`, `ScreenProbes: 4`. Configure `ProbeClipmap` via `renderer.probe_clipmap`; `ScreenProbes` gathers over the same world, so it reads `renderer.probe_clipmap` too, plus its own `renderer.screen_probes`. See [Global illumination](https://meep.company-named.com/docs/rendering/global-illumination/). | | `transparency_mode` | `ShadeTransparencyMode.AVBOIT` | Which order-independent transparency technique draws the transparent buckets: `MBOIT: 0` or `AVBOIT: 1`. Both are wired at the one transparency call site and take the same inputs, so it is safe to flip at runtime. | | `avboit` | `AVBOITSettings` | Switches of the AVBOIT mode, read every frame while it is selected. `transmission_tint_from_base_color` (default `false`) filters what a transmissive surface lets through by its base colour, glTF-style. | | `dof_algorithm` | `"raymarch"` | `"raymarch"` selects `renderer.dof` (`DepthOfField`); `"unreal"` selects `renderer.dof_unreal` (`DepthOfFieldU`). One DoF call site, so exactly one runs. | | `upscale_type` | `ShadeUpscalerType.TAA` | `TAA: 0` or `NSS: 1`. See [The upscaler](#the-upscaler). | | `exposure_compensation` | `0.0` | F-stops, applied on top of auto-exposure and used as the fixed value when it is off. Reads `0` before `initialize()`; the setter asserts the renderer is initialized. | | `tone_mapper` | `ToneMapper`, made by `initialize()` | How the exposed scene colour becomes display colour: `tone_mapper.operator` (`TONE_MAP_OPERATOR_ACES` by default), `tone_mapper.grade`, `tone_mapper.lut_resolution` and `tone_mapper.purkinje_shift`. One operator for every output, so a scene looks alike on SDR and HDR displays. See [Tone mapping and exposure](#tone-mapping-and-exposure). | | `internal_resolution_scale` | `1` | Fraction of output resolution the scene is rendered at. | | `pixel_ratio` | `window.devicePixelRatio` | Device pixels per CSS pixel. | | `profile_session` | `null` | Assign a `GPUProfileSession` to record GPU timings. | Transparency itself cannot be switched off - that flag is private and always on. What is public is **which** order-independent technique draws it: | `ShadeTransparencyMode` | What it does | |---|---| | `MBOIT` (0) | Moment-based OIT (Peters et al. 2017): four power moments of the transmittance function per pixel, additively blended at full resolution into `r32float` + `rgba32float` targets - which is what puts `float32-blendable` on the [device floor](https://meep.company-named.com/docs/installation/). Smooth and cheap, and not depth-complexity invariant: stacked near-opaque layers leak. | | `AVBOIT` (1) | **The default.** Adaptive voxel-based OIT (Drobot, SIGGRAPH 2025): extinction splatted into a 1/8-resolution voxel volume whose depth axis is adaptively packed onto 128 slices, integrated into a 3D transmittance lookup. Depth-complexity and shift invariant, needs no 32-bit float blending, and filters the background per channel for transmissive materials when `renderer.avboit.transmission_tint_from_base_color` is on. | GPU particles draw as a side channel of the AVBOIT pass - through the same volume and the same accumulators as the transparent meshes, which is what makes them composite correctly against those meshes and against the opaque scene without a depth sort of their own. Under `MBOIT` they are simulated and not drawn. ## Order in the frame The post chain is fixed. Reading `Renderer.render_to_target` top to bottom, after the scene is complete and transparency has been composited: ```text AfterTransparency extensions run here; HDR, internal resolution path tracer override feature_path_tracing_enabled velocity debug view feature_velocity_debug_view TAA or NSS feature_taa_enabled + upscale_type <-- resolution changes here depth of field feature_dof_enabled + dof_algorithm motion blur feature_motion_blur_enabled RCAS sharpen feature_sharpening_enabled bloom + auto-exposure feature_bloom_enabled / feature_automatic_exposure_enabled BeforePresent extensions run here; HDR, output resolution tone map always; tone_mapper Overlay extensions run here; display space, drawing onto the canvas ``` Ambient occlusion, reflections, ReSTIR DI, shadows and the indirect-lighting mode all act earlier, during the deferred resolve, and so are not in this list. The phases named on the left are where [render extensions](https://meep.company-named.com/docs/rendering/render-extensions/) attach. ## Resolution | Member | Type | Notes | |---|---|---| | `resize(x, y)` | method | **CSS pixels**, not device pixels. Asserts non-negative integers. The renderer applies `pixel_ratio` itself. | | `pixel_ratio` | `number` | Setter re-derives both resolutions immediately. | | `output_resolution` | `Vector2` | Read-only in practice: the getter returns a **clone**, so writing to it does nothing. | | `internal_resolution_scale` | `number` | Must be finite and greater than zero. Recomputed lazily at the start of the next frame. | | `aspect_ratio` | `number` | Width over height of the **internal** resolution. This is what to assign to `camera.aspect`. | The two derivations, verbatim: ```text output_resolution = clamp(ceil(css_size * pixel_ratio), 1, maxTextureDimension2D) internal_resolution = clamp(floor(output_resolution * scale), 1, maxTextureDimension2D) ``` The floor is one texel: depth and G-buffer textures carry a single mip level, so any scale that leaves at least one pixel along each axis is valid. When `internal_resolution` or `output_resolution` changes, only the current frame's depth and history targets are resized when written, so the previous frame's depth and temporal histories stay intact and are resampled by UV across resolution steps (such as dynamic resolution scaling). `indicate_view_change()` resets SSAO, SSR, TAA, NSS, volumetrics, screen-probe and path-tracer history: call it yourself after teleporting a camera or swapping a scene. Under `Engine`, do not call `resize` directly. `engine.graphics.updateSize()` passes the viewport size to `renderer.resize()`, and is already wired to the viewport's `size.onChanged`. There is no engine-level pixel ratio: render scale is `internal_resolution_scale`, which renders the frame smaller and lets TAA upscale it, rather than the browser stretching a smaller canvas. ### Dynamic resolution scaling `DynamicResolutionScaling` (`shade/renderer/DynamicResolutionScaling.js`) is not owned by the renderer. It reads and writes `internal_resolution_scale` through two assignable functions, and is fed one number per frame. Under `Engine` it is already built and wired: ```js const drs = engine.graphics.dynamic_resolution; drs.enabled = false; // e.g. for a benchmark that wants a fixed resolution drs.target_frame_rate = 60; // the engine sets 30 ``` It is a floor-holder, not a frame-rate governor: at the engine's default target of 30 fps it does nothing at all until a frame costs more than 33 ms, and sits at full resolution on hardware that clears the budget. Standalone, wire it yourself: ```js import { DynamicResolutionScaling } from "@woosh/meep-engine/src/shade/renderer/DynamicResolutionScaling.js"; const drs = new DynamicResolutionScaling(); drs.get_scale = () => renderer.internal_resolution_scale; drs.set_scale = v => { renderer.internal_resolution_scale = v; }; // once per frame drs.notify_frame(frame_time_seconds); ``` | Field | Default | | |---|---|---| | `enabled` | `true` | | | `target_frame_time_s` | `1 / 30` | `target_frame_rate` is an accessor over this. | | `min_scale` / `max_scale` | `0.43` / `1.0` | Hard bounds on the scale. | | `tolerance` | `0.10` | Dead band around the target. | | `probe_step` | `0.05` | Step size when probing for a better scale. | | `min_useful_slope` | `0.005` | Below this, scaling is not buying frame time and it bails. | | `settle_frames` | `30` | Frames to wait after a step before judging it. | | `bail_lockout_frames` | `600` | Frames to stay put after a bail. | | `anomaly_clamp_multiplier` | `6` | Rejects one-off frame-time spikes. | | `fast_half_life_frames` / `slow_half_life_frames` | `8` / `120` | The two smoothing filters. | | `warmup_frames` | `30` | Ignored frames at startup. | Also `reset()` and `notify_frame(frame_time_s)`. ## The upscaler Both upscalers consume the jittered, internal-resolution scene colour and produce an output-resolution image; they differ only in how the resolve is computed. | `upscale_type` | Class | Notes | |---|---|---| | `ShadeUpscalerType.TAA` (default) | `TAA` | Variance-clip TAA in YCoCg with a Blackman-Harris resolve and depth-occlusion clip. Constructed with the renderer. | | `ShadeUpscalerType.NSS` | `NSS` | Neural Super Sampling, a kernel-prediction network. Reached as `renderer.nss`. | **The upscale is a phase boundary, and it is the one thing about the frame you cannot assume away.** `AfterTransparency` is at internal resolution; `BeforePresent` and `Overlay` are at output resolution. The G-buffer stays readable to `BeforePresent` and is therefore a *different size* from the colour beside it there. Never write a resolution down as a constant - ask `frame.resolution`, or `frame.describe(handle)` for the ratio between two of them. Two consequences worth stating: - With `feature_taa_enabled === false` there is **no upscale at all**. The two sides of the boundary are the same size, which is correct only while `internal_resolution_scale` is `1`; with TAA off and the scale below 1, the frame is presented at internal resolution rather than upscaled. - The jitter sequence length is derived from the upscale ratio at every resolution change, for whichever upscaler is selected. Nothing to set. `renderer.nss` is constructed lazily on first access, which is also when the bundled weights blob decodes - so selecting NSS costs one frame and no setup. Its constructor installs the shipped weights; `nss.weights = NSSWeights.from(...)` replaces them with trained weights from elsewhere. Tuning fields include `jitter_sequence_size`, `alpha_blend_scale`, `reset_history` and `debug_view`, plus a dozen network-tuning scalars. ## Sub-objects Ten settings objects hang off the renderer. All are constructed for you; `nss` and `path_tracer` are lazy, `probe_clipmap` and `screen_probes` exist from construction, the rest are built in `initialize()`. | Accessor | Class | Module under `src/shade/renderer/` | |---|---|---| | `renderer.motion_blur` | `MotionBlur` | `postprocess/motion_blur/MotionBlur.js` | | `renderer.dof` | `DepthOfField` | `postprocess/dof/raymarch/DepthOfField.js` | | `renderer.dof_unreal` | `DepthOfFieldU` | `postprocess/dof/gather/DepthOfFieldU.js` | | `renderer.restir_di` | `ReSTIRDI` | `restir/di/ReSTIRDI.js` | | `renderer.ssr` | `SSR` | `postprocess/ssr/SSR.js` | | `renderer.nss` | `NSS` | `postprocess/nss/NSS.js` | | `renderer.volumetrics` | `GPUViewVolumetrics` | `volumetrics/GPUViewVolumetrics.js` | | `renderer.path_tracer` | `AccumulatingPathTracer` | `path_tracer/accumulating/AccumulatingPathTracer.js` | | `renderer.probe_clipmap` | `ProbeClipmapSettings` | `global_illumination/probe_clipmap/ProbeClipmapSettings.js` | | `renderer.screen_probes` | `ScreenProbeSettings` | `global_illumination/screen_probe/ScreenProbeSettings.js` | ### Screen-space reflections SSR traces screen-space depth, resolves against the selected indirect-lighting source, filters spatially and reprojects history. Configure it after the renderer initializes: ```js import { SSRReprojectionMode } from "@woosh/meep-engine/src/shade/renderer/postprocess/ssr/SSRReprojectionMode.js"; renderer.feature_ssr_enabled = true; renderer.ssr.reprojection_mode = SSRReprojectionMode.Parallax; renderer.ssr.spatial_denoising_enabled = true; ``` | Setting | Default | Effect | |---|---|---| | `reprojection_mode` | `SSRReprojectionMode.Parallax` (0) | Parallax-aware history reprojection. `Surface` (1) uses surface reprojection; `CurrentFrame` (2) disables temporal history for comparison. | | `spatial_denoising_enabled` | `true` | Enables the three spatial filtering passes independently of temporal reprojection. | | `reset_history` | `true` initially | Set to `true` after a camera cut or scene change; `renderer.indicate_view_change()` also resets it. | Changing either mode or spatial filtering resets history. History is also invalidated when the resolution, view or indirect-lighting mode changes, or frames are skipped. A recorded frame becomes reusable history only after successful submission. ### MotionBlur One knob: `strength`, default `1.0`. `1.0` is physically plausible, `2.0`-`3.0` reads as cinematic. ### DepthOfField and DepthOfFieldU Two implementations behind one interface. `DepthOfField` is a screen-space ray-march (the Tiny Glade model: aperture sub-rays marched through a half-res depth/CoC buffer, plus tilt-shift); `DepthOfFieldU` is an Unreal-style Diaphragm/Cinematic gather with a foreground coverage bleed. They share every field below. | Field | Default | | |---|---|---| | `quality` | `"medium"` | `"low"` / `"medium"` / `"high"` / `"ultra"` - 12/24/32/48 samples, 16/24/32/48 march steps; firefly cleanup on for `high` and `ultra`. An unknown value silently falls back to `"medium"`. | | `preset` | `null` | Set through `applyPreset(name)`. | | `focus` | `{ mode: "auto" }` | Set through the `focus*` helpers below. | | `focus_smoothing` | `0.15` | | | `focus_region` | `0.0` | | | `f_number` | `2.0` | | | `focal_length_mm` | `null` | `null` derives it from the camera's field of view. | | `sensor_height_mm` | `24.0` | | | `physical_gain` | `1.0` | | | `blade_count` | `0` | `0` is a circular aperture. | | `blade_rotation` | `0.0` | | | `highlight_boost` | `1.0` | | `DepthOfField` adds `march_mode`; `DepthOfFieldU` adds `near_blur_gain` (default `1.0`). Focus is set through helpers rather than by writing `focus` directly: `focusAuto()`, `focusAtDistance(d)`, `focusOnWorldPoint(x, y, z)`, `focusOnScreenPoint(x, y)`, `focusOnNearest()`, `focusOnObject(node)`. `applyPreset(name)` takes one of `subtle`, `portrait`, `cinematic`, `miniature`, `dreamy` (exported as `DOF_PRESETS` / `DOF_PRESET_NAMES` from `postprocess/dof/DOF_PRESETS.js`). ### ReSTIRDI | Field | Default | | |---|---|---| | `m_initial` | `8` | Initial candidate samples per pixel. | | `use_screen_space_shadow` | `true` | | | `denoise_enabled` | `true` | Edge-aware a-trous denoiser on the resolved signal. | | `denoise_iterations` | `3` | More iterations, wider filter, more cost. `0` is equivalent to `denoise_enabled = false`. | ### AccumulatingPathTracer | Field | Default | | |---|---|---| | `render_tile_size` | `256` | One tile per call; the tracer accumulates across frames itself. | | `min_accumulation_alpha` | `0.01` | | | `clear_history` | `false` | Set by `indicate_view_change()`; the tracer also resets whenever the camera moves. | ## Tone mapping and exposure Tone mapping is the last pass before the canvas, and it belongs to `renderer.tone_mapper`, a `ToneMapper` that `initialize()` creates. The tone mapper bakes its `operator` into a 3D LUT for each output, `lut_resolution` texels along each edge (default 32, as in Unreal; at most the device's `maxTextureDimension3D`). Each frame then costs one trilinear fetch per pixel. A LUT is baked again only when the operator, the resolution, the colour grade or (for HDR) the display's peak changes, so all of them can change at runtime. The same operator runs on SDR and HDR displays, so a scene looks alike on both up to the SDR display's limits. The display decides which LUT is used, through `matchMedia("(dynamic-range: high)")`, and the choice is made again whenever that query changes. The code lives in `shade/renderer/deferred/tonemap/`. ```js import { TONE_MAP_OPERATOR_GT7 } from "@woosh/meep-engine/src/shade/renderer/deferred/tonemap/TONE_MAP_OPERATOR_GT7.js"; renderer.tone_mapper.operator = TONE_MAP_OPERATOR_GT7; ``` | Operator | SDR | HDR | |---|---|---| | `TONE_MAP_OPERATOR_ACES` (default) | Unreal's Filmic curve at its default settings | the SDR picture taken back to the scene through the inverse ACES 2.0 SDR output transform, then rendered with the ACES 2.0 output transform for the display; mid-grey rises with the headroom | | `TONE_MAP_OPERATOR_GT7` | clips at the paper white | rolls off to the display's peak | | `TONE_MAP_OPERATOR_PBR_NEUTRAL` | Khronos PBR Neutral as specified | the specification with the display's peak in place of 1 | | `TONE_MAP_OPERATOR_NONE` | clips above 1.0 | shows the exposed colour as far as the display reaches | An exposed 0.18 shows at 0.18 of SDR white under ACES and GT7. ACES has the higher mid-tone contrast (1.36 against GT7's 1.05). PBR Neutral shows it at 0.14. A custom operator is a `ToneMapOperator`: a WGSL chunk that defines `tone_map_operator(scene, peak_nits)`, plus optional bindings of its own. Scene colour past 10000 cd/m² (49.3 × the paper white) clamps at the LUT's edge. **Colour grading.** `renderer.tone_mapper.grade` is a `ColorGrade`. It is neutral by default and is baked into the LUTs ahead of the operator, so it costs nothing per pixel. It follows Unreal's controls, and values from an Unreal project give the same result. The stages apply in this order: - white balance: `white_temperature` (K, 6500 is neutral) and `white_tint` (-1 to 1); - `global`, `shadows`, `midtones` and `highlights`, each a `ColorGradeZone` of `saturation`, `contrast`, `gamma`, `gain` and `offset` (`Vector4`: RGB plus a master value), blended by `shadows_max`, `highlights_min` and `highlights_max`; - gain against luma: `luma_gain_red`, `luma_gain_green` and `luma_gain_blue` (multipliers) and `luma_exposure` (stops); - saturation against luma: `luma_saturation`, times the channel's own `luma_saturation_red`, `luma_saturation_green` or `luma_saturation_blue` (1 leaves the colour, 0 draws it to grey); - hue curves `hue_shift` (degrees), `hue_saturation` (chroma multiplier) and `hue_lightness` (stops), each an `AnimationCurve` over the OkLCh hue in degrees. The luma curves are `AnimationCurve`s too, keyed by the colour's AP1 luma in stops from middle grey, `log2(luma / 0.18)`, and they hold their end keys' values beyond them. Where the three zones split the tonal range into three bands, the luma curves grade any range of it: key a curve at a range's edges to lift or desaturate just that range. A curve with no keys does nothing. A detailed grade (narrow hue bands, a full primary grade) shows more LUT error at 32³. Raise `lut_resolution` to 64 for such a grade. **Your own LUTs.** `set_lut_sdr(resolution, data)` and `set_lut_hdr(resolution, data, peak_nits)` replace the baked LUT for that output until `clear_lut_sdr()` / `clear_lut_hdr()`. `build_lut_sdr_from_hdr()` derives the SDR LUT from a supplied HDR one through the BT.2390 EETF, keeping hue. A LUT you supply is not graded. `data` is `resolution³` RGB triples, red fastest, and must follow the tone mapper's contract: exposed scene-linear Rec.709 in, linear Rec.2020 display light out, both as PQ (ST 2084) signals with 1 at the paper white, over a 0 to 1 domain. Adobe `.cube` files load through `cube_read(text)` in `src/format/lut/cube/`, which returns a `CubeLut` with the same layout; `cube_write(lut)` writes one back. The format carries numbers only, so a `.cube` made for another pipeline (sRGB or log input, say) loads without complaint and looks wrong. Only a file made for the contract above works as is. ```js import { cube_read } from "@woosh/meep-engine/src/format/lut/cube/cube_read.js"; const lut = cube_read(await (await fetch("look.cube")).text()); renderer.tone_mapper.set_lut_sdr(lut.size, lut.data); ``` | | SDR path | HDR path | |---|---|---| | Canvas format | `navigator.gpu.getPreferredCanvasFormat()` | `rgba16float`, context tone-mapping mode `"extended"` | | Output space | Display-P3 when the canvas accepts it, otherwise sRGB | the same | | Dither | 8-bit triangle noise, to kill banding | none - the space is wide enough | The passes write in whichever primaries the canvas actually reports it was configured with. The paper white is 203 cd/m². The browser does not report the display's peak brightness, so an HDR LUT is baked for `renderer.tone_mapper.display.peak_nits`, which is 1000 unless you set it. The SDR LUT tops out at the paper white. Exposure is a single scalar multiplied into the colour just before the curve: - With `feature_automatic_exposure_enabled` on (the default), it comes from a luminance histogram built over the bloom chain's downsampled image and adapted over time. - With it off, the value is `2 ^ exposure_compensation` - f-stops, default `0.0` - so a bare `feature_automatic_exposure_enabled = false` leaves exposure at a fixed 1x. Anything comparing two renders wants adaptation off and this pinned, because eye adaptation keeps drifting for seconds after a change. `exposure_compensation` asserts that the renderer has been initialized, so set it after `initialize()` / `Engine.start()`. **Purkinje shift.** `renderer.tone_mapper.purkinje_shift = true` makes dim scenes look as night vision does: the colour moves towards what the rods see, a single brightness carried by a blue tint. Reds go dark and blues hold up. How far it moves depends on the luminance the view is adapted to, in cd/m²: no shift above 5, the rods alone below 0.005, and a blend linear in log luminance between. With automatic exposure on, that is the luminance the eye has adapted to. With it off, it is `0.18 / 2 ^ exposure_compensation`, so a fixed exposure at compensation 0 sits at 0.18 cd/m², about half rods, and the whole frame darkens under a clear blue cast. The shift is off by default. It runs per pixel ahead of the LUT rather than inside it, so it also applies to a LUT you supply. ## Frame counter and profiling `renderer.frame_count` is a read-only counter, incremented after each submitted frame. It indexes the temporal history and drives the TAA/NSS jitter sequence. `renderer.onFrameFinished` is a `Signal` carrying the same number. `renderer.profile_session` is `null` and **the renderer never makes one** - the profiler is a leaf nothing else imports, so an application that does not mention it does not carry it. Assigning a session and the null checks around it are the whole integration: ```js import { GPUProfileSession } from "@woosh/meep-engine/src/shade/device/timing/profile/GPUProfileSession.js"; import { GPUProfileLevel } from "@woosh/meep-engine/src/shade/device/timing/profile/GPUProfileLevel.js"; const session = new GPUProfileSession({ level: GPUProfileLevel.TIMING }); renderer.profile_session = session; session.start(); // ... frames ... const bytes = await session.stop(); renderer.profile_session = null; ``` GPU timings need the optional `timestamp-query` adapter feature. The renderer takes it when offered and never requires it, so on a browser that withholds it the timers go quiet rather than the renderer refusing to start. ## Present in the tree, absent from the frame Several directories under `src/shade/renderer/postprocess/` ship and are reachable by import, but nothing in the frame calls them. They are not features, and a switch for them does not exist. | Directory | Contents | Status | |---|---|---| | `fxaa/` | `shader_fxaa_311.js` | Zero importers. | | `lens/` | Chromatic-aberration chunks (`chunk_ffx_lens_*`, `chunk_sample_with_chromatic_aberration`) | Import each other and nothing else. | | `perspective/` | `shader_perfect_perspective.js` | Zero importers. | | `upscale-dither/` | `UpscaleDither.js` + its shader | Import each other and nothing else. | | `vrs/` | `vrs_constants.js` | Reached only from `shadow/ray/chunk_vrs.js` to `shadow/ray/graph_vrs_rtx.js`, which nothing imports. The ray-traced shadow prototype beside it (`shadow/ray/RTXShadows.js`) has zero importers too. | Also unused: `postprocess/velocity/graph_add_camera_velocity.js` - only the per-object velocity variant is called, and that one runs every frame regardless of any switch. ## See also - [Rendering overview](https://meep.company-named.com/docs/rendering/overview/) - the `GraphicsEngine` facade and the device floor - [Render extensions](https://meep.company-named.com/docs/rendering/render-extensions/) - putting your own passes into the frame - [Global illumination](https://meep.company-named.com/docs/rendering/global-illumination/) - `indirect_lighting_mode` in full - [Lights & shadows](https://meep.company-named.com/docs/rendering/lights-shadows/) - what the shadow switches govern - [Virtual texturing](https://meep.company-named.com/docs/rendering/virtual-texturing/) - what `feature_virtual_textures` gates --- # Audio overview Section: Audio Source: https://meep.company-named.com/docs/audio/overview/ Description: Meep's audio is event-driven and ECS-native - an AudioEmitter sounds because it linked, an AudioEventTrigger sounds because the entity received an event, and one shared renderer plays both. Meep ships a full audio engine. Not a thin `