@spawnite/engine 0.1.0-beta.15

package/dist/wiki/engine/graphics/post-processing.md

@@ -0,0 +1,130 @@
+---
+title: Post-processing
+description: A screen-space stack of passes drawn over the finished frame, such as bloom, ambient occlusion and a vignette, ending in the tone-mapping curve.
+useCases:
+    - bloom glow
+    - ambient occlusion
+    - vignette screen edges
+    - screen effects
+    - tone mapping
+    - anti aliasing
+    - make the game look nicer
+    - quality levels for slow devices
+sidebar:
+    order: 12
+---
+
+`<PostProcessing>` mounts a stack of screen-space passes in a scene, beside [World](/engine/structure/world/), not inside [Game](/engine/structure/game/): Game's children are DOM, and the stack draws over the canvas. No scene mounts one means no composer and no cost, so a game pays for the stack only where it uses it. The stack's libraries load as a chunk of their own when a scene first mounts one, and the scene draws without the stack until they arrive.
+
+Its props are in [`PostProcessingProps`](https://wiki.spawnite.com/reference/post-processing/postprocessingprops/).
+
+A prop the scene leaves out follows the player's quality level, the one the [Game](/engine/structure/saves/)'s quality store keeps, and changes with it while the game runs. A prop the scene passes always wins over the level.
+
+| Level   | multisampling | Bloom draws | AmbientOcclusion draws | AmbientOcclusion quality | halfResolution |
+| ------- | ------------- | ----------- | ---------------------- | ------------------------ | -------------- |
+| Minimum | 0             | no          | no                     | "performance"            | true           |
+| Low     | 2             | no          | no                     | "performance"            | true           |
+| Medium  | 2             | yes         | yes                    | "performance"            | true           |
+| High    | 4             | yes         | yes                    | "medium"                 | true           |
+
+`<Bloom>` draws at a level whose `bloom` is on, and `<AmbientOcclusion>` at one whose `occlusion` is on, in a scene's own stack as in a look's, so the player's rows mean the same in every scene. A game that wants either at another level turns that one value on for it, as [Graphics quality](/engine/ui/graphics-quality/) shows. Every other pass, the vignette and a library pass included, draws in a scene's own stack at every level. Automatic draws the row of the level the engine picked for the device, as [Automatic](/engine/ui/graphics-quality/#automatic) describes, and the player's Post-processing, Ambient occlusion and Anti-aliasing rows can each take another level's row. A game changes a level's row with Game's `quality` prop. Ambient occlusion stays at half resolution at every level: at full resolution it cost about 2 ms more of the GPU's frame on a desktop card, a quarter of the frame's budget. Unity and Unreal scale post effects per level from their quality settings; here the level the player picks decides, the same one that sets the pixel ratio.
+
+Where the level draws at a pixel ratio of 2 or more, as on a retina screen at High, a stack that names no `multisampling` draws none. The ratio is the level's and the player's render scale's, before dynamic resolution's share, so a resolution step never turns samples on and rebuilds the composer. A jagged edge is half a CSS pixel wide there and hard to see, and 4 samples of the half-float frame at that size cost more of the GPU's frame than bloom does. Godot ships with multisampling off; Unity, Unreal and Roblox tie it to a quality level and not to the screen's density. PlayCanvas draws at a pixel ratio of 1 unless a game asks for the screen's own.
+
+A stack takes one of each pass: two of a kind share one set of settings. To turn a library pass on and off, set it from state the stack's parent holds, so the stack renders again and picks up the change; the engine's own passes can also be toggled from state inside a child. Ambient occlusion goes first among the children, so bloom and the vignette draw over the darkened contact rather than under it. Tone mapping always runs last, after every other pass, because a pass such as bloom reads the frame's true brightness rather than the compressed screen curve. The [daylight rig](/engine/structure/world/)'s exposure still applies underneath it: the rig sets `renderer.toneMappingExposure` from the hour of day, and the composer's tone-mapping curve reads that same exposure when it draws.
+
+## Bloom
+
+A glow around whatever is brighter than the threshold: the sun, a lamp, an emissive material.
+
+Its props are in [`BloomProps`](https://wiki.spawnite.com/reference/post-processing/bloomprops/).
+
+## AmbientOcclusion
+
+Darkens where surfaces meet: under a tree, at the foot of a wall.
+
+Its props are in [`AmbientOcclusionProps`](https://wiki.spawnite.com/reference/post-processing/ambientocclusionprops/).
+
+A see-through object, such as a glow, smoke or water, stays unshaded: the pass draws the scene's transparent objects twice more each frame to find where they cover the occlusion. The engine draws those two targets with its own pass rather than the library's. The library's walked the whole scene five times a frame, and each of its two draws updated every matrix and drew the shadow maps again; with 60 skinned monsters on screen that cost 3.7 ms of a 12 ms frame. The engine's pass gives the same two targets from one walk, and skips the draw of a target no object shows in. Each extra draw still costs every transparent object two more draw calls, so a crowd's glows and shadows are cheapest as one instanced mesh each.
+
+## Vignette
+
+Darker corners, which pull the eye to the middle of the screen.
+
+Its props are in [`VignetteProps`](https://wiki.spawnite.com/reference/post-processing/vignetteprops/).
+
+Roblox offers bloom, blur and colour correction as post effects under `Lighting`, with no ambient occlusion pass or vignette of its own. Unity and Unreal build the same passes into a volume-based post stack, and Godot's WorldEnvironment resource does the same. The engine mounts them as components instead, so a pass turns on or off with the rest of a scene's JSX rather than a separate settings object, and an agent reads its cost the same way it reads any other child of the scene.
+
+## In the devtools
+
+The stack is a **PostProcessing** row in the [devtools](/engine/testing/devtools/) tree, with a leaf per pass: Bloom, AmbientOcclusion and Vignette. Each leaf shows the pass's number props as sliders, and an edit shows on the next frame. A prop the scene changes replaces the edit, and Reset goes back to the props, as for a behaviour. Tone mapping and multisampling are not in the inspector: they are set where the stack mounts. The row cannot be deleted, because the stack's component owns it.
+
+A devtools capture, an entity's screenshot or `capture(view)`, draws through the mounted stack from the capture's own camera, so it shows the frame the player sees, passes and tone mapping included.
+
+## Sample
+
+Ambient occlusion, bloom and a vignette over the meadow, tone mapped with ACES:
+
+```tsx
+import {
+    AmbientOcclusion,
+    Bloom,
+    PostProcessing,
+    Vignette,
+    World,
+} from "@spawnite/engine";
+
+export function MeadowScene() {
+    return (
+        <World map="meadow">
+            <PostProcessing>
+                <AmbientOcclusion />
+                <Bloom intensity={0.8} />
+                <Vignette darkness={0.6} />
+            </PostProcessing>
+        </World>
+    );
+}
+```
+
+## Your own effect
+
+A stack takes any effect or pass from the [postprocessing](https://github.com/pmndrs/postprocessing) library, one it ships or one you write. Build it once with `useMemo` and mount it as `<primitive object={effect} />` among the stack's children, where it draws in its place in the order. The library ships depth of field, outlines, pixelation, chromatic aberration, SMAA and a lookup-table grade, among others. To write your own, extend its `Effect` class with a GLSL `mainImage` function, which runs once for each pixel of the finished frame. This file turns the frame to night-vision green, and the engine's tests mount it:
+
+```tsx title="packages/engine/test/outside/NightVision.tsx"
+import { useEffect, useMemo } from "react";
+import { PostProcessing } from "@spawnite/engine";
+import { Effect } from "postprocessing";
+
+//  Runs once per pixel, after the scene draws: the pixel's brightness in
+//  goggle green.
+const fragment = /* glsl */ `
+void mainImage(const in vec4 inputColor, const in vec2 uv, out vec4 outputColor) {
+    float light = dot(inputColor.rgb, vec3(0.299, 0.587, 0.114));
+    outputColor = vec4(vec3(0.2, 1.0, 0.3) * light, inputColor.a);
+}`;
+
+export class NightVisionEffect extends Effect {
+    constructor() {
+        super("NightVisionEffect", fragment);
+    }
+}
+
+export function NightVision() {
+    const effect = useMemo(() => new NightVisionEffect(), []);
+    useEffect(() => () => effect.dispose(), [effect]);
+    return (
+        <PostProcessing>
+            <primitive object={effect} />
+        </PostProcessing>
+    );
+}
+```
+
+Add `postprocessing` to your game's dependencies at the version `@spawnite/engine` names as its peer. A published page then loads the engine's own copy through the release, as [Publishing](https://wiki.spawnite.com/platform/publishing/#the-engine-and-its-peers) says, so your effect is one the stack can use. The stack keeps only effects and passes from that copy. A child it cannot draw, such as an effect from another version of the library, throws in development, naming the child and the fix. Outside development, the stack draws without that child and logs the same message once.
+
+Unity takes a custom pass as a renderer feature, Unreal as a post-process material, Godot as a compositor effect and PlayCanvas as a post effect. Roblox offers its fixed set of effects only. Here the pass is a class of the same library the engine's own passes come from, so it mixes with them in one stack.
+
+## Where it runs
+
+Client. The stack changes nothing in the world; each player's browser draws its own frame through it.

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

@@ -0,0 +1,103 @@
+---
+title: Your renderer and your own three.js
+description: Set the renderer Game draws with, its shadow filter and its settings, and reach three.js yourself for the rest.
+useCases:
+    - stencil buffer for a portal mask
+    - logarithmic depth buffer for a planet
+    - transparent canvas
+    - soft blurred shadows
+    - change tone mapping at run time
+    - draw before or after the engine's frame
+    - my own post-processing pipeline
+    - tsl node material
+sidebar:
+    order: 14
+---
+
+[Game](/engine/structure/game/) draws one canvas with three's `WebGLRenderer`, made the way React Three Fiber makes it. Three props on Game change that renderer, and fiber's `useThree` hands it to any component for what can change while the game runs. Each prop takes the shape fiber's own `<Canvas>` takes, so a game that knows fiber knows them.
+
+| Prop        | What it sets                                                                                                                                                                             |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `gl`        | The settings three's `WebGLRenderer` is made with, over fiber's defaults, or a factory that makes the renderer itself and may return a promise. A factory may return a `WebGPURenderer`. |
+| `shadows`   | How the shadow map filters a shadow's edge: `"basic"`, `"percentage"` (the default) or `"variance"`, or `false` for no shadow map at all.                                                |
+| `onCreated` | A function Game calls once the canvas has made its renderer, scene and camera, before its first frame.                                                                                   |
+
+Game reads all three once, when it mounts, as it reads `room` and `quality`. A later render that passes other values changes nothing, so a game that switches renderers reads its choice before Game mounts, such as from the page's address. `gl` takes either form, and a game may pick one at run time: `gl={useWebGPU ? factory : { stencil: true }}`. A scene mounted headless, as a room's server and `spawnite simulate` mount it, reads none of them: its `useThree((state) => state.gl)` is a stand-in that draws nothing.
+
+## Settings fixed when the renderer is made
+
+Some settings belong to the WebGL context, and the browser fixes them when it makes the canvas's context. Pass them in `gl`:
+
+| Setting                  | Use it for                                                                                                                                                                        |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `stencil`                | A stencil buffer, which a portal or a mirror masks the world with.                                                                                                                |
+| `logarithmicDepthBuffer` | Depth precision across a planet's scale, where near and far are kilometres apart.                                                                                                 |
+| `reversedDepthBuffer`    | The same precision on a GPU that supports it, at less cost than a logarithmic buffer.                                                                                             |
+| `alpha`                  | `false` clears the canvas opaque. Fiber's default, `true`, clears it clear, so the page shows where nothing draws. The HUD draws in the page over the canvas either way.          |
+| `preserveDrawingBuffer`  | A canvas that keeps its last frame, for a page that reads it with `toDataURL`. It can cost a copy of the frame each frame on some GPUs, and the engine's captures do not need it. |
+| `powerPreference`        | Fiber asks for `"high-performance"`. Pass `"low-power"` for a game that should spare a laptop's battery.                                                                          |
+| `antialias`              | Fiber turns it on. The look's post-processing stack draws off the canvas and takes its samples from the player's quality level instead.                                           |
+
+The following game asks for a stencil buffer and blurred shadow edges:
+
+```tsx title="packages/engine/test/outside/StencilGame.tsx"
+import { Game, Scene, ShadowType, World } from "@spawnite/engine";
+import { noon } from "@spawnite/engine/looks/noon";
+
+//  A game whose portals mask the world behind them with the stencil buffer,
+//  and whose shadows blur at the edge.
+function Lobby() {
+    return <World map="grid" look={noon} />;
+}
+
+export function App() {
+    return (
+        <Game
+            name="portals"
+            start="lobby"
+            gl={{ stencil: true }}
+            shadows={ShadowType.Variance}
+        >
+            <Scene name="lobby" component={Lobby} />
+        </Game>
+    );
+}
+```
+
+`shadows` takes `ShadowType.Basic`, `ShadowType.Percentage` or `ShadowType.Variance`, or the same words as strings. Fiber's `true` and `"soft"` are not offered: they ask for three's soft filter, which three r186 removed, so three would warn and fall back to the percentage filter. A variance map blurs each light's shadow by its `shadow.radius` and `shadow.blurSamples`, at the cost of one blur pass per light; the sun of a [look](/engine/graphics/looks/) sets its own radius. Fiber puts the shadow type back each time the canvas renders again, as a resize, the devtools' pause and the player's frame rate cap each make it, so set the type with this prop rather than on the renderer.
+
+To make the renderer yourself, pass a factory. Game hands it a [`RendererDefaults`](https://wiki.spawnite.com/reference/game/rendererdefaults/): the canvas, `powerPreference`, `antialias` and `alpha`. `RendererDefaults`, `RendererFactory`, `RendererOptions`, `GameRenderer` and `ShadowType` are exports of `@spawnite/engine`. The canvas mounts nothing until the factory's promise resolves, and the loading screen stays up until the first frame draws. A factory that throws or rejects stops the game: a built game shows the engine's error screen, and the dev server shows its overlay.
+
+PlayCanvas takes the same context settings in `createGraphicsDevice(canvas, options)`, and Unity and Godot hold the depth, stencil and shadow choices in a project's settings. Here they belong to the game's `Game`, read once, so one page can mount two games with two renderers.
+
+## Settings you change while the game runs
+
+The renderer's other settings, such as `toneMapping`, `localClippingEnabled` or `outputColorSpace`, can change at any time. Read the renderer with `useThree((state) => state.gl)` in any component under a scene, and set them in an effect. It is the same renderer `gl` made, and `onCreated` hands it over once at the start.
+
+Two settings belong to the engine while its parts run:
+
+- The daylight rig writes `toneMappingExposure` every frame from the hour of day, under either renderer. To scale it and keep the rig, set the look's `exposure`, which multiplies the rig's: `look={{ base: noon, exposure: 0.6 }}`. `lighting={false}` on the [World](/engine/structure/world/) hands you the exposure, but it also takes away the look's sun, sky, fill, fog and stack, so you light the scene yourself. The look's stack tone maps with the same exposure, so the value reaches the screen either way.
+- The player's quality level sets the pixel ratio. Change a level's ratio with Game's `quality` prop, as [Graphics quality](/engine/ui/graphics-quality/) shows.
+
+## The frame's order
+
+Each frame runs fiber's `useFrame` callbacks in order of their priority, lowest first:
+
+| Priority    | What runs                                                                                                                                         |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Below 0     | Your callbacks that must run before the world steps.                                                                                              |
+| 0           | The engine's step, which mounts first, then your callbacks at the default priority, which read the world as this frame's step left it.            |
+| 1 and above | Whatever renders the frame. The look's post-processing stack renders at 1. Any callback at 1 or above tells fiber not to render the scene itself. |
+
+To draw the frame yourself, such as a second camera's view or a pipeline of your own, render in a `useFrame` at priority 1 or above, and pass `postProcessing: false` to the look so its stack stands aside. The look's stack also steps aside on its own when a scene mounts its own `<PostProcessing>`, as [Post-processing](/engine/graphics/post-processing/) says.
+
+## TSL node materials, a preview
+
+three r186 can draw a TSL node material under `WebGLRenderer`: call `setNodesHandler(new WebGLNodesHandler())` on the renderer from `three/examples/jsm/tsl/WebGLNodesHandler.js`, in an effect, before the first node material draws. Lights, percentage shadows, fog, instancing and skinning draw on the first build. Treat it as a preview, not a shader language to build a game on:
+
+- At most 12 distinct node materials draw. Each takes 2 of the GPU's 24 uniform buffer slots, and the 13th draws black. 24 is WebGL2's minimum, so phones sit at or near it.
+- A program that builds again, such as when the sun's shadow turns on or off with a quality change, uses slots it never frees, and every node material then draws black.
+- The handler draws no variance shadow, so leave `shadows` at `"percentage"` beside it.
+- It loads `three/webgpu`, about 193 KiB gzipped more for a page that uses it.
+
+These numbers were measured on three r186 in Chromium on a desktop GPU. For a shader that works today, use [Shader](/engine/graphics/shader/). To run on WebGPU itself, see [WebGPU (experimental)](/engine/graphics/webgpu/).

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

@@ -0,0 +1,331 @@
+---
+title: Shader
+description: Draws a mesh with a fragment shader you write, on the world's clock, with the mesh's UVs and the pointer as inputs.
+useCases:
+    - custom shader
+    - glsl fragment shader
+    - dissolve effect
+    - glowing ring
+    - scrolling scanlines
+    - noise fog
+    - port a shadertoy shader
+    - animated material
+    - shader that reacts to the mouse
+sidebar:
+    order: 9
+---
+
+`<Shader fragment>` is the material of the mesh it sits in, inside a [World](/engine/structure/world/), drawn by a GLSL fragment shader you write. Every shader in the engine draws through it, the [CRT](/engine/graphics/crt-material/), [portal](/engine/graphics/portal-material/) and [energy orb](/engine/graphics/energy-orb-material/) materials included, so a shader you write takes the same inputs as one the engine ships, and you can start from the engine's source.
+
+Its props are in [`ShaderProps`](https://wiki.spawnite.com/reference/shader/shaderprops/).
+
+A `ShaderValue` is a number, a three `Vector2`, `Vector3`, `Color` or `Texture`. Change a uniform's value from React state, and the next frame draws it; no frame callback is needed.
+
+Godot's shading language is the model: it declares `TIME` and `UV` for you, and you add a `uniform` per knob. Roblox has no shaders. Unity and Unreal build materials in a node graph, which an agent cannot write as text.
+
+## What the fragment gets
+
+The engine declares these ahead of your code. Do not declare them yourself.
+
+| Name                | GLSL type                              | What it holds                                                                                                    |
+| ------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `uTime`             | `float`                                | Seconds of world time, from the same clock the [frame](/engine/testing/frame/) steps. A paused world holds it.   |
+| `uPointer`          | `vec2`                                 | The pointer over the canvas, -1 to 1 on each axis, 0 at the centre.                                              |
+| `vUv`               | `vec2`                                 | The mesh's texture coordinates: 0 to 1 across a plane, from the bottom left.                                     |
+| `vWorldPosition`    | `vec3`                                 | The point's place in the world, in metres. With three's `cameraPosition`, it gives the view angle.               |
+| each `uniforms` key | `float`, `vec2`, `vec3` or `sampler2D` | The value you passed, typed from it: a number is a `float`, a `Color` is a `vec3`, a `Texture` is a `sampler2D`. |
+
+Because `uTime` is the world's clock and not the wall's, a paused game freezes every shader, a devtools step advances them by one step, the devtools' speed scales them, and a headless screenshot taken at a given step is the same image every run. A game's shader keeps the world's clock so it can show gameplay time, such as a charge filling or a door's glow counting down. The engine's [water material](/engine/graphics/water-material/) and a map's sea run on the effects' clock instead, with the grass's wind: the pause holds them and the speed leaves them at 1x. Two screenshots of the same step compare pixel for pixel, which is how an agent checks that a change did what it meant.
+
+Write GLSL ES 1.00 as three's own examples do: `texture2D`, `varying` and `gl_FragColor`. Three sets the precision and the GLSL version. Pass `smoothstep` its lower edge first: GLSL leaves `smoothstep(0.5, 0.4, x)` undefined, so a phone may draw it differently. For a falling edge, write `1.0 - smoothstep(0.4, 0.5, x)`.
+
+## Sample
+
+A ring that breathes on the world's clock, in a colour the game chooses:
+
+```tsx
+import { Entity, Shader, World } from "@spawnite/engine";
+import { Color } from "three";
+
+const ring = `void main() {
+    float distance = length(vUv - 0.5);
+    float radius = 0.3 + 0.05 * sin(uTime * 3.0);
+    float band = 1.0 - smoothstep(0.0, 0.03, abs(distance - radius));
+    gl_FragColor = vec4(uTint * band, band);
+}`;
+
+export function Portal() {
+    return (
+        <World map="meadow">
+            <Entity position={[0, 1.2, -3]}>
+                <mesh>
+                    <planeGeometry args={[2, 2]} />
+                    <Shader
+                        fragment={ring}
+                        uniforms={{ uTint: new Color("cyan") }}
+                        transparent
+                    />
+                </mesh>
+            </Entity>
+        </World>
+    );
+}
+```
+
+## Include a LYGIA function
+
+[LYGIA](https://lygia.xyz) is a GLSL library with one function per file: noise, distance shapes, colour, blur and lighting. Include a file by its path in the package, and call its function:
+
+```glsl
+#include "lygia/generative/snoise.glsl"
+
+void main() {
+    gl_FragColor = vec4(vec3(snoise(vUv * 4.0)), 1.0);
+}
+```
+
+Include the function rather than retyping it from memory: a retyped noise or distance function can compile and still draw the wrong thing.
+
+When the game builds, the engine's Vite plugin, `spawnite()`, replaces each `#include` with the file, along with the files that file includes. The shader therefore needs nothing at runtime: it draws offline, headless and the same way every run. A game whose fragments include nothing gets no LYGIA text in its bundle. Every game loads the plugin, and [Game](/engine/structure/game/#the-vite-plugin) says what else it does.
+
+The plugin reads an include only where the fragment is written in the source: at the start of a line inside a template literal, as in the recipes below. It skips an include inside a `//` or `/* */` comment, so commenting one out takes its file out of the shader. A fragment put together at runtime, such as one typed into a text box, cannot include: the `#include` reaches the GLSL compiler, which fails on it as on any compile error below.
+
+Browse the files at [lygia.xyz](https://lygia.xyz) or in [the repository](https://github.com/patriciogonzalezvivo/lygia). Each file's header comment names its function, what it takes and an example.
+
+A path that names no file stops the build. The dev server shows the same error over the page, with the module that holds the include:
+
+```text
+[plugin spawnite] src/Portal.tsx
+Shader: no LYGIA file at "lygia/generative/noise.glsl"
+```
+
+Godot includes a `.gdshaderinc` when it imports the shader, and Unity and Unreal include `.hlsl` or `.ush` files when they compile it. The engine resolves LYGIA's files at the same point: when the game builds, not when it runs.
+
+### Licence and credit
+
+Games on the platform earn money, so a shader you copy or port needs a licence that allows commercial use: MIT, BSD, CC0 or CC BY. Shadertoy's default licence, CC BY-NC-SA, does not. Port a Shadertoy shader only when its own licence line allows commercial use. Keep the author's name and link in a comment above the fragment, and the licence line when the licence asks for it.
+
+LYGIA has two licences: the Prosperity License for noncommercial use, and the Patron License for sponsors. The platform uses LYGIA under the Prosperity License's 30-day commercial trial, and sponsors it on GitHub before the trial ends, so the Patron License's Applications clause covers the engine and the games built on it. A LYGIA file you include keeps its header, so it needs nothing from you.
+
+## Recipes
+
+Each recipe is a mesh you can copy into a scene and change. Put the mesh inside an [Entity](/engine/entities/entity/) to place it.
+
+### Glow ring
+
+A ring that breathes, with a glow falling off on both sides. `circleSDF` gives the distance from the centre: 0 at the centre and 1 at the plane's edge.
+
+```tsx
+import { Shader } from "@spawnite/engine";
+import { Color } from "three";
+
+const glowRing = `#include "lygia/sdf/circleSDF.glsl"
+
+void main() {
+    float radius = 0.6 + 0.05 * sin(uTime * 3.0);
+    float distance = abs(circleSDF(vUv) - radius);
+    float glow = 0.02 / distance;
+    gl_FragColor = vec4(uTint * glow, clamp(glow, 0.0, 1.0));
+}`;
+
+export function GlowRing() {
+    return (
+        <mesh>
+            <planeGeometry args={[2, 2]} />
+            <Shader
+                fragment={glowRing}
+                uniforms={{ uTint: new Color("cyan") }}
+                transparent
+            />
+        </mesh>
+    );
+}
+```
+
+### Scrolling scanlines
+
+Horizontal lines that scroll upwards, with a brighter band passing through them. LYGIA has no function for this, so the recipe is plain GLSL.
+
+```tsx
+import { Shader } from "@spawnite/engine";
+import { Color } from "three";
+
+const scanlines = `void main() {
+    float lines = 0.5 + 0.5 * sin((vUv.y - uTime * 0.05) * 300.0);
+    float band = 1.0 - smoothstep(0.0, 0.1, abs(fract(vUv.y - uTime * 0.3) - 0.5));
+    vec3 colour = uTint * (0.4 + 0.4 * lines + band);
+    gl_FragColor = vec4(colour, 1.0);
+}`;
+
+export function Scanlines() {
+    return (
+        <mesh>
+            <planeGeometry args={[2, 2]} />
+            <Shader
+                fragment={scanlines}
+                uniforms={{ uTint: new Color("#40ff90") }}
+            />
+        </mesh>
+    );
+}
+```
+
+### Noise fog
+
+A layer of fog that drifts, fading out towards the plane's edges. `fbm` layers four octaves of noise. The third coordinate is time, so the fog changes shape as it moves. Lay the plane flat above the floor with `rotation={[-Math.PI / 2, 0, 0]}`.
+
+```tsx
+import { Shader } from "@spawnite/engine";
+import { Color } from "three";
+
+const fog = `#include "lygia/generative/fbm.glsl"
+
+void main() {
+    float noise = 0.5 + 0.5 * fbm(vec3(vUv * 3.0, uTime * 0.2));
+    float density = smoothstep(0.35, 0.75, noise);
+    float edge = 1.0 - smoothstep(0.25, 0.5, length(vUv - 0.5));
+    gl_FragColor = vec4(uTint, density * edge);
+}`;
+
+export function Fog() {
+    return (
+        <mesh rotation={[-Math.PI / 2, 0, 0]}>
+            <planeGeometry args={[6, 6]} />
+            <Shader
+                fragment={fog}
+                uniforms={{ uTint: new Color("#f4f8ff") }}
+                transparent
+            />
+        </mesh>
+    );
+}
+```
+
+### Dissolve by threshold
+
+The surface burns away in patches, with a hot edge where it is about to go. Each point compares its noise value to a threshold and discards itself below it. The sample runs the threshold on `uTime`. To drive it from the game, pass a `uProgress` uniform from 0 to 1 in its place.
+
+```tsx
+import { Shader } from "@spawnite/engine";
+import { Color } from "three";
+
+const dissolve = `#include "lygia/generative/snoise.glsl"
+
+void main() {
+    float noise = 0.5 + 0.5 * snoise(vUv * 6.0);
+    float threshold = 0.5 + 0.5 * sin(uTime);
+    if (noise < threshold) discard;
+    float edge = 1.0 - smoothstep(threshold, threshold + 0.06, noise);
+    vec3 colour = mix(uTint, vec3(1.0, 0.45, 0.1), edge);
+    gl_FragColor = vec4(colour, 1.0);
+}`;
+
+export function Dissolve() {
+    return (
+        <mesh>
+            <planeGeometry args={[2, 2]} />
+            <Shader
+                fragment={dissolve}
+                uniforms={{ uTint: new Color("#8060ff") }}
+            />
+        </mesh>
+    );
+}
+```
+
+### Port a Shadertoy shader
+
+A Shadertoy shader runs here once you rename its inputs. This recipe shows the renaming on Shadertoy's default new shader, the editor's starting code rather than a published shader. Before you port a published one, check that its own licence line allows commercial use, as [Licence and credit](#licence-and-credit) says. The default new shader is:
+
+```glsl
+void mainImage(out vec4 fragColor, in vec2 fragCoord) {
+    vec2 uv = fragCoord / iResolution.xy;
+    vec3 col = 0.5 + 0.5 * cos(iTime + uv.xyx + vec3(0, 2, 4));
+    fragColor = vec4(col, 1.0);
+}
+```
+
+To port it, make the following changes:
+
+1. Replace `void mainImage(out vec4 fragColor, in vec2 fragCoord)` with `void main()`, and `fragColor` with `gl_FragColor`.
+2. Replace `fragCoord / iResolution.xy` with `vUv`. It runs from 0 to 1 across the mesh, as the division does across the screen.
+3. Replace `iTime` with `uTime`, and `iMouse` with `uPointer`, which runs from -1 to 1.
+4. Write each integer in a `vec` as a float, such as `vec3(0.0, 2.0, 4.0)`, because GLSL ES 1.00 does not convert them.
+5. Keep the author's credit and licence in a comment, as [Licence and credit](#licence-and-credit) says.
+
+```tsx
+import { Shader } from "@spawnite/engine";
+
+//  Ported from Shadertoy's default new shader.
+const rainbow = `void main() {
+    vec2 uv = vUv;
+    vec3 colour = 0.5 + 0.5 * cos(uTime + uv.xyx + vec3(0.0, 2.0, 4.0));
+    gl_FragColor = vec4(colour, 1.0);
+}`;
+
+export function Rainbow() {
+    return (
+        <mesh>
+            <planeGeometry args={[2, 2]} />
+            <Shader fragment={rainbow} />
+        </mesh>
+    );
+}
+```
+
+A shader that reads `iChannel0` needs a `Texture` uniform in its place, such as `uniforms={{ uChannel: texture }}`. A shader in several passes, with a Buffer A tab, does not port to one fragment.
+
+## Read a compile error
+
+A fragment that does not compile draws nothing, and three prints the error to the console: the GL compiler's message, then the source around the failing line, with that line marked `>`. The MCP's next `screenshot` or `describe_entity` reply and the next `spawnite play screenshot` name each shader that failed since the shot before it, with the compiler's message and the line marked `>`, so a blank mesh in a shot comes with its reason. The `read_console` tool returns the whole error. The line numbers count three's own header of about 150 lines ahead of your code, so read the line marked `>`, not the number. This one names `colour`, which the fragment never declared:
+
+```text
+THREE.WebGLProgram: Shader Error 0 - VALIDATE_STATUS false
+
+Material Name:
+Material Type: ShaderMaterial
+
+Program Info Log: Fragment shader is not compiled.
+
+FRAGMENT
+
+ERROR: 0:162: 'colour' : undeclared identifier
+ERROR: 0:162: 'constructor' : not enough data provided for construction
+
+  158: uniform float uTime;
+  159: uniform vec2 uPointer;
+  160: varying vec2 vUv;
+  161: uniform vec3 uTint;
+> 162: void main() { gl_FragColor = vec4(colour, 1.0); }
+```
+
+The browser then repeats `WebGL: INVALID_OPERATION: useProgram: program not valid` for every frame the broken material draws. Those lines follow from the first error; fix that one.
+
+## See it
+
+`pnpm exec spawnite play screenshot --until "steps >= 60"` steps the game headless to the first second and writes a PNG, as [Your first game](https://wiki.spawnite.com/learn/your-first-game/#7-playtest-and-run) shows. The same step gives the same image, so take one before a change and one after, and compare them.
+
+## Start from a scaffold
+
+The MCP's `add_shader` tool writes `src/shaders/<Name>.tsx` into the game: a fragment with a LYGIA include, and a `<Name>Material` component to put inside a mesh. [Templates](https://wiki.spawnite.com/platform/templates/#shader) shows the file.
+
+## Start from the engine's shaders
+
+Each shader the engine ships is an exported GLSL string with a comment per block, so an agent can copy it, change one block and pass it as `fragment`. The [CRT material](/engine/graphics/crt-material/) and the [water material](/engine/graphics/water-material/) link their source.
+
+## References
+
+Each of these collections can teach you a technique or give you a shader to copy:
+
+| Source                                                                                                                                          | Good for                                                                           | How to use it here                                                                                                                                                             |
+| ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [LYGIA](https://lygia.xyz)                                                                                                                      | Noise, distance shapes, colour, blur and lighting functions, tested and ready.     | `#include "lygia/…"` as [Include a LYGIA function](#include-a-lygia-function) shows.                                                                                           |
+| [Shadertoy](https://www.shadertoy.com)                                                                                                          | Thousands of complete effects: skies, water, fire, tunnels and glows.              | The default licence, CC BY-NC-SA, does not allow commercial use: port only a shader whose own licence line does, as [Port a Shadertoy shader](#port-a-shadertoy-shader) shows. |
+| [godotshaders.com](https://godotshaders.com)                                                                                                    | Short shaders for game objects: outlines, dissolves, water, holograms and toon.    | Take the `fragment()` body. Rename `TIME` to `uTime` and `UV` to `vUv`, and set `gl_FragColor` from `ALBEDO` and `ALPHA`. Keep the licence the page names.                     |
+| [three.js examples](https://threejs.org/examples/)                                                                                              | Shaders written for the same renderer and GLSL version this engine uses.           | Open an example's source and copy its `fragmentShader` string from `void main()` on. Rename its time and UV inputs to `uTime` and `vUv`.                                       |
+| [The Book of Shaders](https://thebookofshaders.com)                                                                                             | Learning the ideas: shaping functions, colour, patterns, noise and cellular noise. | Read a chapter to learn why a recipe works. Its examples use `u_time` and `gl_FragCoord.xy / u_resolution`; rename them to `uTime` and `vUv`.                                  |
+| Inigo Quilez's [distance functions](https://iquilezles.org/articles/distfunctions2d/) and [palettes](https://iquilezles.org/articles/palettes/) | The exact formula for a 2D shape's distance, and a cosine colour palette.          | Copy a function above `main()` and call it with `vUv - 0.5`. LYGIA includes many of them, such as `lygia/color/palette.glsl`.                                                  |
+
+## Where it runs
+
+Client. A shader changes nothing in the world; each player's browser draws its own.