@spawnite/engine 0.1.0-beta.15

package/dist/wiki/engine/graphics/skinned-batch.md

@@ -0,0 +1,115 @@
+---
+title: Skinned batches
+description: Draws every animated copy of one model in one draw per mesh, each copy posed by its own skeleton and clips.
+useCases:
+    - crowd of animated enemies
+    - horde of monsters
+    - many animated characters at once
+    - draw 60 monsters efficiently
+    - herd of animals
+    - village full of npcs
+    - reduce lag with many characters
+sidebar:
+    order: 9
+---
+
+A skinned batch draws every animated copy of one model in one draw for each mesh of the model, and once more into each shadow map, however many copies stand. Each copy keeps its own skeleton and its own `AnimationMixer`, so its clips blend, layer and cross-fade as they would on a copy drawn alone. Use a batch for a crowd of one kind: a wave of monsters, a herd, a town's villagers.
+
+Without a batch, three.js draws each skinned copy on its own. Every copy is one draw into the frame and one into the sun's shadow map, refreshes its material's uniforms, and uploads its own bone texture each frame. In Holdfast, a Horde of 60 husks spent about 3 ms of a frame on those draws alone.
+
+## Entities batch on their own
+
+Every [`<Entity model animation>`](/engine/entities/entity/#models) that loops a clip draws in its model's batch, as do the entities `Replicas` draws with a clip. A game declares nothing:
+
+```tsx
+<Entity model="duck" animation="walk" />
+<Entity model="duck" animation="idle" position={[4, 0, 0]} />
+```
+
+The two ducks draw in one draw for each of the duck's meshes, and each plays its own clip on its own skeleton. An Entity's [`material`](/engine/entities/entity/#materials) keys the batch: every entity handed one function draws in that function's batch of the model, and a second function draws in a batch of its own.
+
+## Batch a game's own view
+
+A view that builds its own copy of a model, with its own mixer, adds the copy to the scene's batch of that model:
+
+```tsx
+import { useFrame } from "@react-three/fiber";
+import { useLayoutEffect, useMemo, useRef } from "react";
+import { AnimationMixer, Color } from "three";
+import { clone } from "three/addons/utils/SkeletonUtils.js";
+import { useModel, useSkinnedBatch, type SkinnedCopy } from "@spawnite/engine";
+import goblinUrl from "./goblin.glb?url";
+
+type GoblinUniforms = { emissive: Color };
+
+/** A goblin that glows red for as long as `hurt` is above 0. */
+export function Goblin({ hurt }: { hurt: number }) {
+    const { scene, animations } = useModel(goblinUrl);
+    const batch = useSkinnedBatch<GoblinUniforms>(scene, {
+        uniforms: { emissive: new Color(0, 0, 0) },
+        castShadow: true,
+    });
+    //  Bones of its own, so each goblin moves apart.
+    const copy = useMemo(() => clone(scene), [scene]);
+    const mixer = useMemo(() => new AnimationMixer(copy), [copy]);
+    const drawn = useRef<SkinnedCopy<GoblinUniforms>>(undefined);
+    useLayoutEffect(() => {
+        drawn.current = batch.addCopy(copy);
+        mixer.clipAction(animations[0]).play();
+        return () => drawn.current?.remove();
+    }, [batch, copy, mixer, animations]);
+    useFrame((_state, delta) => {
+        mixer.update(delta);
+        //  This goblin alone.
+        for (const part of drawn.current?.parts ?? [])
+            part.uniforms.emissive.setRGB(hurt, 0, 0);
+    });
+    return <primitive object={copy} dispose={null} />;
+}
+```
+
+`useSkinnedBatch(scene, options)` returns the scene's one batch of the loaded model. The batch stays in the scene while a view holds it or a copy is in it, and 30 seconds after, so a copy that comes back soon draws in a batch whose first draw is done. The first view to ask for a `key` makes the batch with its options, so views that dress one model differently pass a `key` each.
+
+`batch.addCopy(root)` draws the copy's skinned meshes in the batch from the next draw on and hands back the copy. `copy.remove()` gives the copy's meshes back their own draws. Add a copy in a layout effect rather than in `useMemo`, which a development build runs twice.
+
+Each of `copy.parts` stands for one of the copy's meshes and holds its own values, which the batch reads at each draw:
+
+- `color` multiplies the part's colour for this copy alone. White keeps the model's own.
+- `uniforms` holds this copy's value of each of the batch's `uniforms`. The part's fragment shader reads each one in place of the material's own uniform of the same name, such as `emissive` for a hit's flash. Three.js multiplies a material's `emissive` by its `emissiveIntensity` before the shader reads it, and a copy's value replaces the product.
+
+The options are the following:
+
+- `uniforms`: each per-copy value by name, at the value a new copy starts with. A number is a `float`, a `Vector2` a `vec2`, a `Vector3` or `Color` a `vec3`, and a `Vector4` a `vec4`.
+- `dress`: a function handed a part's mesh's own material, which returns the material the part draws with, such as a copy with an `onBeforeCompile` of the game's. The batch draws what it returns as it is, never a copy, since three.js leaves the hook out of a copy, and keys each part's program by the hook, so two dresses with different hooks never share one. What it returns is the game's: the batch never disposes it, and one material can dress the parts of several batches, whatever their `uniforms`. A see-through one leaves the part to draw itself, each copy in its own mesh's material, so dress the copy's own meshes too. A copy of the mesh's own material, which the batch disposes of, when left out. Each part casts its shadow through a depth material of the batch's own, so a hook that discards pixels, as a dissolve does, leaves the shadow whole.
+- `castShadow` and `receiveShadow`: off by default, as a mesh's are.
+
+## First draws under the loading screen
+
+A batch with no copy draws nothing, so the first copy's draw would be each part's first, and Chrome's GPU process builds a draw's vertex layout then: 24 and 44 ms of its time at Holdfast's first wave. `useSkinnedBatch` holds the batch's warm-up while the loading screen covers the page, so a batch a view holds from the first frame, as Holdfast's `WarmUp` holds each monster's, draws there instead.
+
+`batch.holdWarmUp()` draws one instance in each part, with every bone zero, so it covers no pixel, into the frame and into each shadow map, until the function it returns is called. Holds count: the instance goes once every hold has let go, and calling a release twice lets go once. A copy added meanwhile draws in a slot of its own. A view that builds its batch itself and draws it under a loading screen of its own calls it the same way.
+
+## What draws on its own
+
+A copy the game never adds draws on its own, as any skinned mesh does. Holdfast keeps its colossus, the night's boss, out of the batch: one boss's own draws cost nothing a player notices, and its outline and slam read as one character's.
+
+A batch also leaves the following parts of a model to draw themselves:
+
+- A part whose material is see-through, the mesh's own or what `dress` returns, whose copies need drawing back to front.
+- A part with morph targets, whose copies each hold their own weights.
+- A mesh the copy holds hidden as it is added.
+- A mesh drawn with more than one material, which a batch does not split into its groups. A glTF file splits a mesh of several materials into one mesh of each material, so a model loaded from one has no such mesh.
+
+Under a `WebGPURenderer`, the [experimental WebGPU mode](/engine/graphics/webgpu/), the batch has no part at all, because its instancing library calls WebGL itself: every copy added draws its own meshes, its `parts` list is empty, and the console says the batch is off.
+
+While a copy is in a batch, the batch draws it with the part's material, not the copy's own, and keeps the copy's meshes' own `visible` false. Hide a copy, or one of its meshes, by hiding a group that holds it. A raycast at the copy still meets its own mesh, posed.
+
+## How it draws
+
+Before a part's first draw of each render, once the frame's matrices are up to date, the batch writes each shown copy's bone matrices into the part's one bone texture, taken into the batch's space. A vertex then lands where the copy's own mesh would put it. The batch is an [`InstancedMesh2`](https://github.com/agargaro/instanced-mesh) for each part, with a slot for each copy; a copy's slot moves nothing, and its bones carry its place in the world. The copies are never culled one by one, as a copy drawn alone that plays its clips is not either.
+
+## What the other engines do
+
+Unity draws each `SkinnedMeshRenderer` on its own: its batched GPU skinning merges the skinning work and its SRP Batcher makes each draw cheaper, but the draws stay one per character, and its GPU instancing does not take skinned meshes. Unreal's Animation Budget Allocator and Roblox's animation throttling update a far character's animation less often, and leave its draws alone. Unreal's Instanced Skinned Mesh component and vertex animation textures, Unity's Animation Instancing, Godot's crowd add-ons and Babylon.js's baked vertex animation draw a crowd in one draw by baking the clips into a texture, so a copy plays one clip, or cross-fades two, and loses blends and layers. Godot's `MultiMesh`, PlayCanvas's batcher and three.js's `InstancedMesh` and `BatchedMesh` take no skinned mesh.
+
+A batch keeps each character's own live pose, as the three.ez instanced mesh library does and three.js's morph-target instancing example does for morph targets. A game's clips, blends and layers look the same batched as drawn alone, and a creator's agent writes nothing to bake. The pose is still computed on the CPU for each copy, which cost under a millisecond for 60 husks in Holdfast.

package/dist/wiki/engine/graphics/track-scatter.md

@@ -0,0 +1,124 @@
+---
+title: TrackScatter
+description: Stands copies of models along a track, placed in track coordinates and drawn in one draw per model.
+useCases:
+    - trees beside a road
+    - scenery along a track
+    - row of posts down a lane
+    - rocks beside the course
+    - forest along a race track
+    - decorate a track with props
+    - place props along a path
+sidebar:
+    order: 12
+---
+
+`<TrackScatter>` stands copies of registered models along a [track](/engine/behaviours/track-mover/#the-track): a row of trees each side, a line of posts down the lane, a rock at 120 m and 1.5 m right. You place every copy in track coordinates, the engine seats it on the drawn ground, and each model draws through one [InstancedModel](/engine/graphics/instanced-model/), so a forest of two species costs two draws per mesh.
+
+Its props are in [`TrackScatterProps`](https://wiki.spawnite.com/reference/world/trackscatterprops/).
+
+## Placements
+
+Track coordinates are metres along the centerline, metres across it (positive to the right of travel), and metres above the surface. A placement is one of the following:
+
+- A copy: `at` metres along. It may name its `model`, `turn` and `scale`; left out, the model is drawn by weight, the turn is hashed and the scale is 1.
+- A row: copies about `spacing` metres apart from `start` to `end`, the whole track by default, each in the middle of its own cell. The spacing rounds to the nearest that cuts the stretch into whole cells, so the row ends where its stretch does. A spacing of 0 or less throws.
+
+Both take the following fields:
+
+- `across`: metres across, measured from `from`.
+- `from`: `"center"` by default, or the track's `"left"` or `"right"` edge, as a [TrackSurface cross-section](/engine/graphics/track-surface/#the-cross-section) measures. A row measured from an edge keeps its distance to that edge as the track widens.
+- `height`: metres above the ground the copy is seated on.
+
+A row takes the following fields as well:
+
+- `jitter`: metres a copy wanders across, the whole range.
+- `slide`: the share of its cell a copy may slide along. Keep it under 1, or neighbours leave a gap.
+- `size`: the low and high multiple of the model's size, spread evenly over the copies.
+- `stretch`: the low and high multiple of a copy's height over its width, so squat and slender copies mix.
+
+`models` names each model with how often it is drawn, such as `{ fir: 3, spruce: 1 }`. A model with weight 0 stands only where a copy names it, and a copy that needs a draw throws when no model weighs more than 0.
+
+Every draw is a hash of the copy's place in the list, so the same placements stand the same copies on every device. `placeTrackScatter(options)` returns the same list without drawing it, for a headless test or a tool that reads a course as numbers.
+
+## Seating and clearing
+
+Pass the drawn ground as `surface`, the geometry [`buildTrackSurface`](/engine/graphics/track-surface/#standing-things-on-it) returns. A ray straight down seats each copy on the triangles drawn, so a copy never floats over a wide span of hillside. A copy with no surface under it is left out. Without a `surface`, a copy stands at the track's own height.
+
+A copy is also left out where it stands nearer another leg of the track, past the middle of a hairpin or on the inside of a tight bend, by the same rule the surface clips its sides by.
+
+`clear` keeps rows off the single copies: a row copy within `clear` metres of one steps that far out, away from the centerline, and is left out if it is still too near.
+
+`tint(index, model)` returns the colour a copy is multiplied by, from its index among its model's copies. Hash the index for a colour that differs from copy to copy.
+
+## Where it runs
+
+Client. The copies have no colliders and spawn no entity, and a headless scene draws nothing. A rock the rider hits or a coin she picks up is a [TrackTrigger](/engine/behaviours/track-trigger/). The copies are never culled one by one and have no level of detail.
+
+Unity's `SplineInstantiate` and Unreal's PCG spline sampler place copies along a path. Godot and Roblox leave it to a script. `TrackScatter` shares its word with the [map's scatter](/engine/structure/world/#scatter), and places in track coordinates so an agent writes a treeline as a short list of numbers.
+
+## Sample
+
+Two rows of firs each side, and a rock in the lane:
+
+```tsx
+import {
+    buildTrackSurface,
+    registerModel,
+    Track,
+    TrackScatter,
+    TrackSurface,
+    type TrackScatterCopy,
+    type TrackScatterRow,
+} from "@spawnite/engine";
+import fir from "./fir.glb?url";
+import rock from "./rock.glb?url";
+
+registerModel("fir", fir);
+registerModel("rock", rock);
+
+const track = new Track([
+    { x: 0, y: 0, z: 0, width: 10 },
+    { x: 10, y: -8, z: -60, width: 12 },
+    { x: 0, y: -16, z: -120, width: 10 },
+]);
+const ground = buildTrackSurface({
+    track,
+    section: [
+        { from: "left", across: -30, height: 5 },
+        { from: "left", across: 0 },
+        { from: "right", across: 0 },
+        { from: "right", across: 30, height: 5 },
+    ],
+});
+const models = { fir: 1, rock: 0 };
+const placements: (TrackScatterCopy | TrackScatterRow)[] = [
+    { at: 80, across: 1.5, model: "rock" },
+    ...[-1, 1].flatMap((side) =>
+        [3, 10].map((out): TrackScatterRow => ({
+            from: side < 0 ? "left" : "right",
+            across: side * out,
+            spacing: 6,
+            jitter: 2,
+            size: [2, 3],
+        })),
+    ),
+];
+
+export function Course() {
+    return (
+        <>
+            <TrackSurface
+                geometry={ground}
+                materials={{ snow: <meshStandardMaterial color="white" /> }}
+            />
+            <TrackScatter
+                track={track}
+                surface={ground}
+                models={models}
+                placements={placements}
+            />
+        </>
+    );
+}
+```

package/dist/wiki/engine/graphics/track-surface.md

@@ -0,0 +1,107 @@
+---
+title: TrackSurface
+description: Draws the ground a track rides from a cross-section laid along it, each zone in its own material.
+useCases:
+    - race track ground
+    - road surface
+    - icy section of a track
+    - ground for a sled run
+    - lane with walls
+    - kart circuit surface
+    - snow and dirt zones
+    - endless runner ground
+sidebar:
+    order: 11
+---
+
+`<TrackSurface>` draws the ground a [track](/engine/behaviours/track-mover/#the-track) rides: a lane, its shoulders, a wall each side and an apron beyond, extruded along the centerline. A stretch the track tags as ice or dirt draws in its own material. A sled run, a kart circuit and an endless runner each draw their ground this way.
+
+Its props are in [`TrackSurfaceProps`](https://wiki.spawnite.com/reference/world/tracksurfaceprops/).
+
+In a scene whose ground is a `TrackSurface`, mount [`Lighting`](/engine/graphics/looks/#a-scene-without-a-map) rather than `<World>`, as Sled does. A `<World>` with no `map` mounts the engine's `grid` map, an 8 m floor at y = 0, and a track at that height cuts through it.
+
+## The cross-section
+
+The shape is data: a list of points, from the left of travel to the right, in track coordinates. Each point takes the following fields:
+
+- `across`: metres across, positive to the right of travel.
+- `from`: where `across` is measured from, `"center"` by default, or the track's `"left"` or `"right"` edge. A shoulder measured from an edge keeps its width as the lane widens.
+- `height`: metres above the track, along its up.
+- `spans`: how many strips the surface to the next point is cut into. More strips follow a `lift` more closely.
+- `wall`: the surface to the next point is a wall face, which shades flat from its crease instead of blending into the ground beside it.
+
+A cross-section is laid every `spacing` metres, half a metre by default. Where a side past the track's edge reaches over another leg of the track, as at a hairpin, it stops at the line between the two legs, so an apron never covers the other lane. A spot belongs to another leg when the cross-section it lies beside, the nearest one whose line passes within a spacing of it, lies more than 20 m further along or back. A spot past the track's end lies beside the stretch whose side reaches it, not beside the end, so the inside of a bend near the finish keeps its apron. A side cut short there ends at the other leg's height rather than the one `lift` gives it, so the two meet with no step where the other leg's side runs on past it.
+
+## Zones
+
+A track point may carry a `zone`, such as `"ice"`, that blends to the next point. `track.zoneWeight(distance, zone)` gives how much of the zone the track is at a distance, from 0 to 1, so a game can make an icy stretch fast as well as shiny. `materials` names a material for each zone. A strip draws in the zone that weighs more than half there, and in the first material when none does.
+
+## Lift and paint
+
+Two optional functions of the point's track coordinates shape the surface further:
+
+- `lift(across, along, point)` returns metres to raise the surface straight up: loose snow, wind drifts or a hillside. It also receives the world point before the raise, for a height that comes from the map rather than the track.
+- `paint(across, along)` returns a vertex colour as linear red, green and blue. Turn on `vertexColors` in the materials to see it.
+
+The normals follow the lifted surface, so a drift a few centimetres deep still catches the light. The uvs run in metres across and along, over `tile` metres per texture repeat.
+
+## Terrain to the horizon
+
+Pass `terrain` to stand the surface in land that reaches the horizon, so the sky never shows below it. The land draws in the same mesh, as a last zone named `terrain`, in the material `materials.terrain` names. It has the following shape:
+
+- Under the surface, the land lies up to 8 m below it, so its wider triangles never show through the lane. It rises to the surface's height at the rims and over the last 4 m of each end.
+- Past the surface, the land leaves the nearest vertex of the surface's outline at that vertex's height, and carries its slope on only in the direction the surface rises there. Land beside a rim, in a notch where one side stops short of its neighbour, stays at the rim's height, so the two meet without a step.
+- Further out, the land blends every outline vertex that lies about as near as the nearest: up to 2 m further for each metre out, and at most 30 m further. Where two parts of the outline at different heights lie about as near, such as a long apron and the low end of a bend past it, the land ramps from one to the other instead of stepping where the nearer one changes.
+- Further out, mountains rise out of a ridged noise, over the first 90 m and up to `height` metres, 340 by default.
+
+The land is one disc of rings round the track's middle, reaching `radius` metres from it, 1200 by default. Keep the radius inside the camera's far plane, and keep `terrain` out of the render, or the land is built again on every render. Its normals are smooth, its uvs are world x and z over `tile`, and its vertex colours are white, so a material can shade it by how steep it is.
+
+`{}` takes every default. A `height` of 0 stands no mountains: the land carries the outline's own slope on and eases it level over the next few tens of metres.
+
+Unreal's Landscape Splines deform a landscape to a road, and Unity's terrain tools stamp a spline into a heightmap: in both, the game places a terrain and a path and joins them. Godot, Roblox and PlayCanvas leave the join to the game. `TrackSurface` builds the land from the track, so an agent gets a world with no seam from one option.
+
+## Standing things on it
+
+`buildTrackSurface(options)` builds the same geometry without drawing it. Build it once, stand trees or props on it with a [TrackScatter](/engine/graphics/track-scatter/), on the land as well when it has some, and pass it to `<TrackSurface geometry>` with the materials. The game keeps and disposes a geometry it built. A surface the component builds itself is disposed on unmount.
+
+A game that raises its apron with a height function of the map, as a hillside, reads it off `weighPlanRings(rings, spot)`, where each ring is a cross-section's position, tangent and metres along. It returns the cross-sections that count at a plan point, each with a weight, the weights summing to one. A cross-section weighs less the further the point lies from its line, and less the further along, so a point between two neighbours reads mostly the nearer. Where two stretches meet or the lines of a bend's inside cross, the weights hand one to the other over a metre or so, and past the track's ends the end cross-sections weigh most. Every weight changes smoothly as the point moves, so the height ramps rather than steps.
+
+The surface has no collider. A [TrackMover](/engine/behaviours/track-mover/) rides the track, not the mesh.
+
+Unity's `SplineExtrude`, Unreal's `SplineMeshComponent` and Godot's `CSGPolygon3D` in path mode each sweep a 2D shape along a path. Roblox and PlayCanvas leave it to the game. `TrackSurface` sweeps a shape too, but measures it in track coordinates and from either edge, so an agent writes a course's cross-section as a short list of numbers.
+
+## Sample
+
+A lane with shoulders and low walls, icy in the middle:
+
+```tsx
+import { Track, TrackSurface, type TrackSectionPoint } from "@spawnite/engine";
+
+const track = new Track([
+    { x: 0, y: 0, z: 0, width: 12 },
+    { x: 8, y: -4, z: -20, width: 14, zone: "ice" },
+    { x: -8, y: -8, z: -45, width: 12 },
+]);
+
+const section: TrackSectionPoint[] = [
+    { from: "left", across: -1.5, height: 1.5, wall: true },
+    { from: "left", across: 0, spans: 3 },
+    { from: "left", across: 3, spans: 8 },
+    { from: "right", across: -3, spans: 3 },
+    { from: "right", across: 0, wall: true },
+    { from: "right", across: 1.5, height: 1.5 },
+];
+
+export function Course() {
+    return (
+        <TrackSurface
+            track={track}
+            section={section}
+            materials={{
+                snow: <meshStandardMaterial color="#f4f7fb" roughness={0.95} />,
+                ice: <meshStandardMaterial color="#9fd3f0" roughness={0.3} />,
+            }}
+        />
+    );
+}
+```

package/dist/wiki/engine/graphics/water-material.md

@@ -0,0 +1,60 @@
+---
+title: Water material
+description: Draws moving water on any flat mesh, with shallows and foam at its edge and the sky caught at a low angle, in one pass a phone can afford.
+useCases:
+    - lake or sea water
+    - river or lake
+    - waves and ripples
+    - foam at the shore
+    - shallow water color
+    - water plane
+    - water that reflects the sky
+sidebar:
+    order: 11
+---
+
+`<WaterMaterial>` is the material of the mesh it sits in, inside a [World](/engine/structure/world/). It draws the mesh as water: a lake, a river or a sea. Two layers of noise drift across each other as waves. The water turns lighter in the shallows near its edge and breaks into foam at the shore. Where the view grazes the surface, it catches the sky. The waves run on the effects' clock, as a map's [sea](/engine/structure/world/#sea) and its grass do: the devtools' pause and a pausing modal hold them, and the devtools' speed leaves them at the wall clock's pace, so a pond keeps the sea's pace at 2x. A devtools step does not move them. A water you write on [Shader](/engine/graphics/shader/) runs on the world's clock instead.
+
+Its props are in [`WaterMaterialProps`](https://wiki.spawnite.com/reference/materials/watermaterialprops/).
+
+The shore is the edge of the plane's texture coordinates: the square, or the circle inside it when `round` is on. Draw the water on a `planeGeometry`, because another mesh's edge does not follow that square, and part of its rim would have no foam. Lay the plane flat where the water should be, a little above the ground, and size it to the lake or the river. The waves keep the same size on any plane, because they follow the ground rather than the plane's corners.
+
+The water draws in one pass, without a depth texture or a second render of the scene, so a phone can afford it. Its sky is a fixed colour, not a true reflection: trees and the sun do not mirror in it.
+
+Roblox makes water a terrain material, with wave size and speed set on the terrain. Unity's HD pipeline ships a water system, and Godot leaves water to community shaders. Three's own `Water` draws the scene a second time for its reflection, which costs a phone a frame's worth of work. Here water is a material with props, as the [CRT material](/engine/graphics/crt-material/) is, and a map's [sea](/engine/structure/world/#sea) lays the same water across the whole map, its shallows and foam where the ground under each point rises to the surface rather than at the plane's edge. Its waves run on the effects' clock rather than the world's, as Godot's shader `TIME` runs unscaled while Unity's `_Time` follows `timeScale`: water is the map's ambient motion, so it keeps the grass's pace whatever the devtools' speed.
+
+The shader's source is `waterFragment`. It is an exported GLSL string with a comment per block: copy it, change a block, such as the sky colour or the foam, and pass it to a `Shader` for water of your own.
+
+## A pond in a map
+
+A water plane laid on a map's ground draws over the ground, and the map's grass, tufts, bushes and rocks keep growing through it. Clear the ground under the pond with two brushes of the map editor: the MCP's `edit_terrain`, `spawnite map terrain`, or the devtools' Terrain section. Give each the pond's centre and a radius a metre past its edge, since a brush weakens toward its rim, and a `strength` of 1:
+
+1. `scatter` with `multiplier: 0` over the families `tuft`, `bush` and `rock`. The `tuft` multiplier thins the grass blades as well as the tufts. `erase` is for the single instances left standing once the multiplier is 0.
+2. `paint` with a material that grows no grass, such as `sand`, for a shore.
+
+`map_query` at the pond then reads its grass as bare, and both edits live in the map's file, `src/maps/<map>.json`.
+
+## Sample
+
+A round pond in the meadow:
+
+```tsx
+import { Entity, WaterMaterial, World } from "@spawnite/engine";
+
+export function Pond() {
+    return (
+        <World map="meadow">
+            <Entity position={[0, 0.05, -4]}>
+                <mesh rotation={[-Math.PI / 2, 0, 0]}>
+                    <planeGeometry args={[6, 6]} />
+                    <WaterMaterial round waveSize={1.5} />
+                </mesh>
+            </Entity>
+        </World>
+    );
+}
+```
+
+## Where it runs
+
+Client. The water changes nothing in the world; each player's browser draws its own. A player walks over it as over the ground: it has no collider, and no swimming.

package/dist/wiki/engine/graphics/webgpu.md

@@ -0,0 +1,87 @@
+---
+title: WebGPU (experimental)
+description: Mount a game on three's WebGPURenderer, what works there, and which engine parts stay off until after launch.
+useCases:
+    - run my game on webgpu
+    - webgpu renderer
+    - try WebGPURenderer
+    - compute shaders
+    - why is the sky missing on webgpu
+    - node materials on webgpu
+sidebar:
+    order: 15
+---
+
+A game can draw with three's `WebGPURenderer` instead of `WebGLRenderer`. The mode is experimental: the step, the room, input, audio, the HUD and the devtools work, but many of the engine's own looks need WebGL and stay off. They follow on WebGPU after launch. WebGL2 stays every game's default, and the renderer is each game's own choice.
+
+## Mount a game on WebGPU
+
+Return a `WebGPURenderer` from Game's `gl` factory, as [Your renderer and your own three.js](/engine/graphics/renderer/) describes, and wait for its `init()` before you return it:
+
+```tsx title="packages/engine/test/outside/WebGPUGame.tsx"
+import { Game, Scene, World } from "@spawnite/engine";
+import { noon } from "@spawnite/engine/looks/noon";
+
+//  A game drawn by three's WebGPURenderer, the engine's experimental mode.
+//  The look keeps its sun and fog; its post stack is left out, and its sky
+//  and baked light stay off on their own, each named once in the console.
+function Lobby() {
+    return <World map="grid" look={{ base: noon, postProcessing: false }} />;
+}
+
+export function App() {
+    return (
+        <Game
+            name="lab"
+            start="lobby"
+            gl={async (defaults) => {
+                //  Loaded here, so a page on WebGL never downloads it.
+                const { WebGPURenderer } = await import("three/webgpu");
+                const renderer = new WebGPURenderer({
+                    ...defaults,
+                    stencil: true,
+                });
+                await renderer.init();
+                return renderer;
+            }}
+        >
+            <Scene name="lobby" component={Lobby} />
+        </Game>
+    );
+}
+```
+
+The canvas mounts nothing until `init()` resolves, and the loading screen waits for the first frame. The factory imports `three/webgpu` itself, so a page that draws with WebGL never downloads it. The example game opens this way with `?renderer=webgpu` in its address.
+
+On a browser or a device with no WebGPU, `WebGPURenderer` falls back to a WebGL2 backend of its own, not to `WebGLRenderer`. The engine treats both backends the same: every part on the list below stays off on either.
+
+To check which renderer drew, read the page's console, as `spawnite play console` prints it: under WebGPU it holds the `Off under WebGPURenderer` lines below. `useThree((state) => state.gl)` reads the renderer the factory returned. Fiber types it as `WebGLRenderer` whatever it is, so a component that calls a WebGPU method reads it as a [`GameRenderer`](https://wiki.spawnite.com/reference/game/gamerenderer/) and checks `"isWebGPURenderer" in gl` first.
+
+## What stays off
+
+Each part below needs WebGL. Under WebGPU it stays off, and the console names it once a page, with what stands in for it, in a line that starts `Off under WebGPURenderer`. Nothing crashes, and nothing goes quiet without a line.
+
+| Part                                                                                                          | Under WebGPU                                                                              |
+| ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| The daylight rig's sky dome                                                                                   | The sky shows the canvas's clear colour. A look's sky image still draws.                  |
+| The look's light baked from the sky                                                                           | Surfaces take the sun and the fill alone.                                                 |
+| `<PostProcessing>` and the look's stack                                                                       | The frame draws with no pass. `postProcessing: false` on the look only silences the line. |
+| `<Shader>`, `WaterMaterial`, the sea, `CrtMaterial`, `PortalMaterial`, `EnergyOrbMaterial`                    | The mesh draws nothing.                                                                   |
+| `<Particles>`                                                                                                 | Every burst and `Emitter` plays nothing.                                                  |
+| A weapon's tracer, an ability's line to its target, the terrain brush's outlines                              | None draws. The brush shows its fill.                                                     |
+| The World's ground shading                                                                                    | The ground draws in one plain colour.                                                     |
+| The World's grass and scatter                                                                                 | Neither draws. The scatter's colliders still stand.                                       |
+| A VRM avatar                                                                                                  | She draws as the placeholder capsule. A GLB `model` on `CharacterSpawn` draws.            |
+| The skinned batch an animated `Entity` model and [`useSkinnedBatch`](/engine/graphics/skinned-batch/) draw in | Each copy draws its own meshes, one draw per mesh.                                        |
+| The shader warm-up under the loading screen                                                                   | Each program builds as it first draws.                                                    |
+| The performance overlay's GPU time, and the GPU spans of `spawnite play profile`                              | The overlay shows the CPU time alone, and the profile lists no GPU span.                  |
+
+A material patched with `onBeforeCompile` draws unpatched: three's WebGPU renderer ignores the hook without a word, so a game's own patches stop too. A `ShaderMaterial` of your own draws nothing, and three logs `Material "ShaderMaterial" is not compatible`. Write your own materials as node materials from `three/tsl` instead.
+
+`spawnite play see` refuses under WebGPU: it reads the canvas's pixels back at once, which WebGPU cannot. `spawnite play screenshot`, `dump`, `stats` and the devtools' capture work.
+
+## What draws
+
+Everything three's node materials draw from a standard material: an `Entity` or `InstancedModel` model, a GLB character and its clips, the sun's shadow, fog, a look's sky image, and the HUD, which draws in the page. Your own meshes take node materials from `three/tsl`, and three's `RenderPipeline` from `three/webgpu` draws a post-processing pipeline of your own in a `useFrame` at priority 1, as [the frame's order](/engine/graphics/renderer/#the-frames-order) says.
+
+Unity marks its WebGPU web export experimental beside WebGL2, its default; Godot's web export draws with WebGL2 alone; PlayCanvas's engine keeps WebGL2 as its default and offers WebGPU. The engine follows them: WebGPU is a choice a game makes, and WebGL2 is what a game gets without one.