@spawnite/engine 0.1.0-beta.15

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

@@ -0,0 +1,64 @@
+---
+title: CRT material
+description: Draws a texture as an old CRT screen on any mesh, with bent glass, scanlines, a phosphor grille, a rolling bar and a flicker.
+useCases:
+    - old tv screen
+    - retro crt monitor
+    - scanlines on a screen
+    - computer terminal in the world
+    - vintage television effect
+    - arcade cabinet screen
+    - glitchy screen with flicker
+sidebar:
+    order: 10
+---
+
+`<CrtMaterial map>` is the material of the mesh it sits in, inside a [World](/engine/structure/world/): an old cathode-ray screen showing `map`. The glass bends the picture toward the corners, scanlines run across it, a phosphor grille splits it into red, green and blue stripes, a bright bar rolls up it, and it flickers. All of it runs on the world's clock, as every [Shader](/engine/graphics/shader/) does, so a paused game holds the bar where it is.
+
+Its props are in [`CrtMaterialProps`](https://wiki.spawnite.com/reference/materials/crtmaterialprops/).
+
+Unity, Unreal and Godot ship a CRT look as a screen-wide pass over the whole game. This one is a material, so a terminal or a television can stand in the world, and the player walks up to it. A screen-wide pass is not in the engine yet.
+
+The shader is [ThreeUI's CRT](https://github.com/MengTo/threeui/tree/68802d5428071ada5c20db8094b1649e6bb770ed/src/shaders/crt) by Meng To, MIT, moved from the whole canvas onto a mesh's UVs. Its source is `crtFragment`, an exported GLSL string with a comment per block: copy it, change a block and pass it to a `Shader` for a screen of your own.
+
+## Sample
+
+A terminal drawn on a canvas, standing on a plane in the meadow:
+
+```tsx
+import { CrtMaterial, Entity, World } from "@spawnite/engine";
+import { useMemo } from "react";
+import { CanvasTexture } from "three";
+
+function drawTerminal() {
+    const canvas = document.createElement("canvas");
+    canvas.width = 640;
+    canvas.height = 480;
+    const context = canvas.getContext("2d");
+    if (!context) throw new Error("no 2d context");
+    context.fillStyle = "#03100a";
+    context.fillRect(0, 0, canvas.width, canvas.height);
+    context.fillStyle = "#8dffb0";
+    context.font = "32px monospace";
+    context.fillText("> hello, world_", 40, 80);
+    return new CanvasTexture(canvas);
+}
+
+export function Terminal() {
+    const map = useMemo(drawTerminal, []);
+    return (
+        <World map="meadow">
+            <Entity position={[0, 1.2, -3]}>
+                <mesh>
+                    <planeGeometry args={[1.6, 1.2]} />
+                    <CrtMaterial map={map} />
+                </mesh>
+            </Entity>
+        </World>
+    );
+}
+```
+
+## Where it runs
+
+Client. The screen changes nothing in the world; each player's browser draws its own.

package/dist/wiki/engine/graphics/energy-orb-material.md

@@ -0,0 +1,52 @@
+---
+title: Energy orb material
+description: Draws a glowing orb of drifting smoke on a plane, for a pickup, a power core or a boss's weak point.
+useCases:
+    - glowing orb pickup
+    - power core
+    - boss weak point glow
+    - magic sphere
+    - energy ball effect
+    - glowing collectible
+    - floating ball of smoke
+sidebar:
+    order: 10
+---
+
+`<EnergyOrbMaterial>` is the material of the plane it sits in, inside a [World](/engine/structure/world/): a sphere of drifting smoke with a bright rim and a soft glow around it. Use it for a pickup, a power core or a boss's weak point. It runs on the world's clock, as every [Shader](/engine/graphics/shader/) does, so a paused game holds the smoke still.
+
+Its props are in [`EnergyOrbMaterialProps`](https://wiki.spawnite.com/reference/materials/energyorbmaterialprops/).
+
+The orb is drawn on a flat plane and reads as a sphere from the front. Stand the plane in drei's `<Billboard>` so that it always faces the camera. The orb fills the middle 62% of the plane, and the glow fades out before the plane's edge.
+
+Roblox builds a glowing orb from a ball with the Neon or ForceField material. Unity, Unreal and Godot ship no orb; creators buy one from a store or copy one from godotshaders.com. This one is a single material with three props.
+
+The shader is [ThreeUI's energy orb](https://github.com/MengTo/threeui/tree/68802d5428071ada5c20db8094b1649e6bb770ed/src/shaders/energy-orb) by Meng To, MIT, moved from the middle of a canvas onto a plane's UVs. Its source is `energyOrbFragment`: copy it, change a block and pass it to a `Shader` for an orb of your own.
+
+## Sample
+
+An orange orb floating over the meadow:
+
+```tsx
+import { Billboard } from "@react-three/drei";
+import { EnergyOrbMaterial, Entity, World } from "@spawnite/engine";
+
+export function Core() {
+    return (
+        <World map="meadow">
+            <Entity position={[0, 1.2, -3]}>
+                <Billboard>
+                    <mesh>
+                        <planeGeometry args={[1.6, 1.6]} />
+                        <EnergyOrbMaterial color="orange" />
+                    </mesh>
+                </Billboard>
+            </Entity>
+        </World>
+    );
+}
+```
+
+## Where it runs
+
+Client. The orb changes nothing in the world; each player's browser draws its own. What touching it does is the game's.

package/dist/wiki/engine/graphics/instanced-model.md

@@ -0,0 +1,89 @@
+---
+title: InstancedModel
+description: Draws many copies of one model in one draw call.
+useCases:
+    - forest of trees
+    - field of coins
+    - many copies of one model
+    - scatter rocks
+    - draw many objects fast
+    - reduce draw calls
+    - grass or decoration scattered over terrain
+sidebar:
+    order: 9
+---
+
+InstancedModel draws a registered model once for each placement in a list, in one draw call for each mesh in the model. Use it for a forest, a field of coins or a scree of rocks: things that stand many times and do nothing on their own. It spawns no entity, so a copy has no behaviours, no collider and no transform a system moves. A thing that moves, collides or is picked up is an [`<Entity model>`](/engine/entities/entity/#models).
+
+A placement is a plain transform, so any code can produce the list:
+
+- `position`: the point the model's lowest point stands on. The model is seated on its own bounds, as the [scatter kit](/engine/structure/world/#scatter) is, so a model centred on its origin still stands on the ground.
+- `turn`: radians about y. It defaults to 0. InstancedModel draws the file unturned, so at 0 its front faces +z, where an [`<Entity model>`](/engine/entities/entity/#models) turns it to face -z.
+- `scale`: a multiple of the model's own size, one number for every axis or one for each. It defaults to 1.
+- `tint`: a colour the copy is multiplied by. Copies without one keep the model's own colours.
+
+Its props are in [`InstancedModelProps`](https://wiki.spawnite.com/reference/entity/instancedmodelprops/) and a placement's fields in [`InstancePlacement`](https://wiki.spawnite.com/reference/entity/instanceplacement/).
+
+Unity's `Graphics.RenderMeshInstanced`, Unreal's Instanced Static Mesh and Godot's `MultiMeshInstance3D` take the same input: one mesh and a list of transforms.
+
+The copies are never culled one by one and have no level of detail: the whole batch draws whenever any of it is in view. A headless scene draws nothing and loads no model.
+
+## Materials
+
+`material` changes what every copy wears, as an [Entity's `material`](/engine/entities/entity/#materials) does: a function handed each of the file's materials, which returns the one the copies wear in its place, asked once for each of the file's materials and kept. Left out, the copies wear the `material` the model registered with, or the file's own. A mesh drawn with several materials asks the function for each of them. Return a new material, such as a clone, since the original is the loaded file's; what the function returns is the game's to dispose. The copies of one batch are drawn as one, so a see-through material draws them in one pass, not sorted one by one. For a colour that differs per copy, give each placement a `tint`.
+
+These firs turn to autumn. The engine's tests mount this file:
+
+```tsx title="packages/engine/test/outside/AutumnTreeline.tsx"
+import {
+    InstancedModel,
+    type InstancePlacement,
+    type ModelMaterial,
+} from "@spawnite/engine";
+import { Color, MeshStandardMaterial } from "three";
+
+//  A row of firs turned to autumn: every copy wears its file's material
+//  with its colour pulled toward orange.
+
+const orange = new Color("#d9822b");
+
+/** A copy of the file's material, since the original is the loaded
+ *  file's, which every other draw of the file wears. Made once, outside the
+ *  component: InstancedModel asks it once for each of the file's
+ *  materials. */
+const autumn: ModelMaterial = (original) => {
+    const turned = original.clone();
+    if (turned instanceof MeshStandardMaterial) turned.color.lerp(orange, 0.6);
+    return turned;
+};
+
+const firs: InstancePlacement[] = Array.from({ length: 50 }, (_, index) => ({
+    position: [index * 3, 0, -10],
+    turn: index,
+}));
+
+export function AutumnTreeline() {
+    return <InstancedModel model="fir" placements={firs} material={autumn} />;
+}
+```
+
+## Where it runs
+
+Client. The copies only change how the world looks.
+
+```tsx
+import { InstancedModel, registerModel } from "@spawnite/engine";
+import fir from "./fir.glb?url";
+
+registerModel("fir", fir);
+
+const firs = Array.from({ length: 50 }, (_, index) => ({
+    position: [index * 3, 0, -10] as [number, number, number],
+    turn: index,
+    scale: 1 + (index % 3) * 0.2,
+}));
+
+export function Treeline() {
+    return <InstancedModel model="fir" placements={firs} />;
+}
+```

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

@@ -0,0 +1,196 @@
+---
+title: Looks
+description: A look sets a scene's sky light, fog, exposure, grading and post-processing with one World prop.
+useCases:
+    - sky and sun lighting
+    - day or night atmosphere
+    - fog in a scene
+    - color grading
+    - change the mood of a scene
+    - exposure setting
+    - pick a visual style for my game
+    - post processing preset
+sidebar:
+    order: 12
+---
+
+A look is a finished setting for a scene's light. Import one and hand it to [World](/engine/structure/world/), and it sets the following together:
+
+- The soft light and reflections every model's material takes from the sky.
+- Fog.
+- Exposure.
+- A colour grade.
+- A [post-processing](/engine/graphics/post-processing/) stack.
+
+A game that picks no look draws with the daylight rig alone.
+
+```tsx
+import { World } from "@spawnite/engine";
+import { dusk } from "@spawnite/engine/looks/dusk";
+
+export function DuskScene() {
+    return <World map="meadow" look={dusk} />;
+}
+```
+
+A look adds nothing to your game's download: it lights the scene from the sky the engine draws.
+
+| Look       | Hour | What it looks like                            |
+| ---------- | ---- | --------------------------------------------- |
+| `noon`     | 10   | A clear meadow with the sun high.             |
+| `morning`  | 2.4  | A low sun through a light haze.               |
+| `dusk`     | 19.3 | A warm sun on the horizon, and a strong glow. |
+| `night`    | 22   | Midnight: the moon over a dark blue meadow.   |
+| `overcast` | 10   | Soft light from a grey sky, and close fog.    |
+
+## The sky and the sun
+
+Each look lights the scene's materials from the engine's own sky at the look's hour: the daylight rig draws that sky once into a cube when the look mounts, and three.js filters it into the scene's environment. The bake holds the scattering sky, the zenith's blue, the cloud decks, the warm band at the horizon and a ground below it. It holds no lights, fog, models or post-processing, and it is drawn whatever the scene shows, so a game that draws no engine sky, with `sky={false}` or a painted `sky`, still takes its light from the engine's sky at the look's hour.
+
+The daylight rig keeps the sky and the light in agreement every frame:
+
+- It clips the sky's own sun, because the rig's directional light is the sun and casts the shadows. Left in, the sky's sun would light every shadow.
+- It scales the environment's light with the hour, as it scales the hemisphere fill. At the look's hour the light is the look's `environment.intensity`.
+- It multiplies the hour's exposure by the look's.
+- It dims the fog with the light on the ground, the sun and the fill together. The fog keeps the look's colour at the look's hour and at any brighter hour, and darkens as the light falls after it, so it never glows past a scene the night has darkened.
+
+A look opens the World on its hour. Pass `startHour` to open elsewhere. The day clock still runs, so the drawn sky and the sun follow the hour from there. The bake keeps the look's hour, and the rig scales its light with the hour instead of drawing it again.
+
+Unity lights a scene from its skybox by default, Godot from its `Sky` resource, and Unreal's Sky Light captures the sky it draws; a look lights from the engine's sky in the same way, and takes an image in its place as each of them takes a cubemap.
+
+### Lighting from an image
+
+To light the scene from an equirectangular `.hdr` or `.exr` in place of the engine's sky, name it as the look's `environment.image`, with `sunU`, the column its sun stands in from 0 to 1 across. The rig clips the image's sun, turns the image so its sun stands on the rig's, and keeps the look's intensity unless you name another. `image: false` drops a base look's image and lights from the sky again. Put the image in your game's `public/assets` folder and name it by its path. The engine's tests mount this file:
+
+```tsx title="packages/engine/test/outside/SunsetScene.tsx"
+import { World } from "@spawnite/engine";
+import { dusk } from "@spawnite/engine/looks/dusk";
+
+//  Dusk, lit from an image in the game's public/assets folder in place of
+//  the engine's sky.
+export function SunsetScene() {
+    return (
+        <World
+            map="meadow"
+            look={{
+                base: dusk,
+                environment: {
+                    image: { file: "/assets/sunset.hdr", sunU: 0.6 },
+                },
+            }}
+        />
+    );
+}
+```
+
+The image is downloaded before it lights the scene: until it arrives the models take no light from the environment. A 1K HDRI from [Poly Haven](https://polyhaven.com/hdris) is about 1.5 MB. A change between an image and the sky compiles every lit material once more.
+
+While the sun is below the horizon, the same directional light is the moon. The moon stands opposite the sun, so it rises at sunset and sets at sunrise, and its light is a cool blue that follows its own height and peaks at midnight. The moon casts the shadows at night, and a night costs no more to draw than a day. The exposure falls to a quarter at night, so the sky goes truly dark and the meadow is lit by the moon.
+
+## Overriding a value
+
+Pass `{ base, ...values }` in place of the look to replace any value of it. A pass's settings merge into the look's, and `false` drops the pass or the fog:
+
+```tsx
+import { World } from "@spawnite/engine";
+import { noon } from "@spawnite/engine/looks/noon";
+
+export function BrightNoonScene() {
+    return (
+        <World
+            map="meadow"
+            look={{
+                base: noon,
+                exposure: 1.2,
+                bloom: { intensity: 1 },
+                vignette: false,
+            }}
+        />
+    );
+}
+```
+
+| Value            | What it sets                                                                                                                                                                                                                                                                                    |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| hour             | The hour the World opens on.                                                                                                                                                                                                                                                                    |
+| environment      | `intensity`, the light the environment lends every surface at the look's hour; `image`, an image to light from in place of the engine's sky, as [Lighting from an image](#lighting-from-an-image) says, or `false` to drop a base look's image.                                                 |
+| sun              | The share of the rig's sun kept: less under cloud.                                                                                                                                                                                                                                              |
+| fill             | The share of the rig's hemisphere fill kept beside the sky's light.                                                                                                                                                                                                                             |
+| exposure         | Multiplies the rig's exposure for the hour.                                                                                                                                                                                                                                                     |
+| fog              | `color`, `near` and `far` in metres, or `false`.                                                                                                                                                                                                                                                |
+| postProcessing   | `false` keeps the look's light and fog and mounts no stack, so the game can mount its own `<PostProcessing>`.                                                                                                                                                                                   |
+| bloom            | [Bloom](/engine/graphics/post-processing/#bloom)'s props, or `false`.                                                                                                                                                                                                                           |
+| ambientOcclusion | [AmbientOcclusion](/engine/graphics/post-processing/#ambientocclusion)'s props, or `false`.                                                                                                                                                                                                     |
+| vignette         | [Vignette](/engine/graphics/post-processing/#vignette)'s props, or `false`.                                                                                                                                                                                                                     |
+| grading          | `hue` in radians, and `saturation`, `brightness` and `contrast` from -1 to 1, applied before tone mapping, which still receives light past 1; no channel goes below zero. 0 leaves the frame as it is. `tint`, a color the frame's light is multiplied by first: white, the default, leaves it. |
+
+## Easing the grade
+
+The look's `grading` is where the grade starts. To move it while the scene runs, such as warming the frame through a sunset and cooling it at midnight, write the live grade that `useLookGrading` returns, in a `useFrame`, as you would a material's color. The look's stack takes it into its passes before it draws each frame, so easing it rebuilds nothing and costs no more than the writes.
+
+```tsx
+import { useFrame } from "@react-three/fiber";
+import { Color } from "three";
+import { useLookGrading } from "@spawnite/engine";
+
+const warm = new Color("#fff0e2");
+const cool = new Color("#e4ebff");
+
+export function NightGrade({ night }: { night: { current: number } }) {
+    const grading = useLookGrading();
+    useFrame(() => {
+        //  0 at dusk, 1 at midnight.
+        grading.tint.lerpColors(warm, cool, night.current);
+        grading.saturation = -0.12 * night.current;
+    });
+    return null;
+}
+```
+
+The live grade holds `hue`, `saturation`, `brightness`, `contrast` and `tint`, the same values as the look's `grading`, with `tint` a three.js `Color` to write in place. The look fills it when it mounts and again when the scene hands `World` another look. A scene that mounts its own `<PostProcessing>`, or a player's quality level whose `grading` is off, draws none of it, and a write to it is harmless.
+
+Unity blends post-processing volumes by weight, and Unreal lerps a post-process volume's settings, to grade by time of day; Roblox tweens a `ColorCorrectionEffect`'s `TintColor` and `Saturation`, and Godot sets an `Environment`'s adjustments from a script. The live grade takes Roblox's and Godot's shape, one grade whose values a script writes, because a game's own clock, such as a night's stops, already knows where it stands: no volumes to place, and the look stays one value.
+
+## Post-processing
+
+Picking a look opts the game in to post-processing: World mounts the look's stack, and the [devtools](/engine/testing/devtools/) show its passes' sliders. A scene that mounts its own `<PostProcessing>` keeps it: the look mounts no stack beside it and logs a warning, so the frame is drawn once. Pass `postProcessing: false` to keep your own stack without the warning.
+
+Roblox sets a scene's light with fixed settings on its `Lighting` service, and Unity and Unreal leave the sky, fog and post-processing volume for the creator to tune. Godot gathers them in one `Environment` resource. A look is closest to Roblox's: the creator picks a look and never tunes a stack, and an agent starts from a finished look and changes one value at a time.
+
+## A scene without a map
+
+A scene that draws its own ground, such as a track, has no map to hand `World`. Mount `Lighting` instead. It sets the same sky, sun, look and stack as `World` does, over a point you name rather than the player's character. With no World and no body, a game loads no physics, and with no World it loads no navmesh unless its loading screen does, as [World](/engine/structure/world/) says:
+
+```tsx
+import { Lighting } from "@spawnite/engine";
+import { morning } from "@spawnite/engine/looks/morning";
+import { Vector3 } from "three";
+
+export function TrackLight() {
+    return (
+        <Lighting
+            look={morning}
+            focus={new Vector3(0, 0, -120)}
+            shadowBox={{ halfWidth: 60, depth: 220 }}
+        />
+    );
+}
+```
+
+With no day clock in the world, the sun stands at the look's hour. `shadowBox` sizes the sun's shadow box in metres around `focus`; the default holds a character's surroundings.
+
+To keep a painted sky, pass `sky`: an equirectangular image, and `sunU`, the column its sun stands in from 0 to 1 across. The image is drawn in place of the rig's sky, turned so its sun stands on the rig's. It is only drawn; the models still take their light from the engine's sky at the look's hour, or from the look's image. `Lighting` takes the same `sky`, `sun` and `fog` as World, and `sky={false}` draws no sky at all, as [World](/engine/structure/world/#sky-sun-and-fog) describes.
+
+```tsx
+import { Lighting } from "@spawnite/engine";
+import { dusk } from "@spawnite/engine/looks/dusk";
+import dawn from "./sky-dawn.webp?url";
+
+export function DawnLight() {
+    return <Lighting look={dusk} sky={{ file: dawn, sunU: 0.5 }} />;
+}
+```
+
+## Where it runs
+
+Client, except the hour. Headless, World mounts no rig and no stack, but the look's hour still seeds the day clock, so a simulation opens on the same hour a player sees.

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

@@ -0,0 +1,185 @@
+---
+title: Particles
+description: Plays a particle effect at a point in the world, such as sparks on a hit, or under a moving object, such as a bolt's trail, from a file made in the three.quarks editor.
+useCases:
+    - explosion effect
+    - sparks on hit
+    - trail behind a projectile
+    - smoke and dust
+    - spell cast effect
+    - sword slash effect
+    - burst of particles
+    - effect attached to a moving object
+    - add a stock particle effect
+    - share a particle effect
+sidebar:
+    order: 13
+---
+
+`<Particles effects>` holds the effects a scene plays. Mount one in a scene, inside a [World](/engine/structure/world/) beside its views. Any view in the scene then plays an effect once with `useParticles().spawn(effect, { at })`, where `at` is a vector, `{ x, y, z }`, or an entity's `[x, y, z]` `position`, or mounts `<Emitter effect>` under an object to play it there for as long as the view stays. Nothing loads until a scene mounts one: the particle library is a chunk of its own.
+
+Its props are in [`ParticlesProps`](https://wiki.spawnite.com/reference/particles/particlesprops/), a burst's in [`ParticleBurst`](https://wiki.spawnite.com/reference/particles/particleburst/), and an emitter's in [`EmitterProps`](https://wiki.spawnite.com/reference/particles/emitterprops/).
+
+The engine draws particles with [three.quarks](https://quarks.art). One batched renderer draws every effect that shares a material in one draw call, and steps them all from the frame's clock, so a paused game holds each particle where it is. A burst removes itself when its last particle dies.
+
+## Making an effect
+
+An effect is one of the following:
+
+- **A file from the [three.quarks editor](https://quarks.art/create).** Export the effect as JSON and import it in the game. The file holds the emission, the forces, the colour ramps and the sprite.
+- **An emitter built in code** with the library's constructors, as `new ParticleSystem({ ... }).emitter`. The game adds `three.quarks` to its own dependencies, at the version `@spawnite/engine` names as its peer, so a published page runs the engine's own copy and a burst's `color` and `count` reach the effect.
+
+- **An effect from the shared assets.** `spawnite add asset <id>`, or the MCP's `add_asset`, copies it into the game as `src/particles/<id>.json`, its sprite inside it, and prints the line that imports it and the call that plays it. The game imports its own copy, so a change to it changes no other game. `spawnite assets list --kind particle`, or the MCP's `list_assets`, lists every effect the library holds, creators' among them, and [the asset store](https://create.spawnite.com/assets) shows a picture of each one in the air.
+
+The library holds these five effects from the platform:
+
+| Id           | What it plays                                        | How                |
+| ------------ | ---------------------------------------------------- | ------------------ |
+| `bolt-burst` | A spell's impact, 28 white sparks                    | `spawn`            |
+| `melee-puff` | A blade's hit, 16 white sparks                       | `spawn`            |
+| `slash-arc`  | A blade's swing, seven crystal shards thrown down -z | `spawn` with `yaw` |
+| `bolt-runes` | Three gold runes orbiting a bolt                     | `Emitter`          |
+| `bolt-trail` | A violet ribbon behind a bolt                        | `Emitter`          |
+
+The sparks and the shards draw white: name a `color` with the burst, or with the `Emitter`, to tint them.
+
+## Sharing an effect
+
+An effect you made goes into the shared assets, so any game adds it with `spawnite add asset`:
+
+1. Put the effect's `.json` in a folder, with each sprite it names by a file name, such as `spark.png`, beside it.
+2. Write its row in the folder's `catalog.json`, with the category `effects`, as [Publish an asset](https://wiki.spawnite.com/platform/assets/#publish-an-asset) shows.
+3. Install Chromium once with `spawnite play install`, because the publish plays the effect in it.
+4. Run `spawnite assets publish <file>`, or the MCP's `publish_assets`.
+
+The command carries each sprite inside the effect, plays it in headless Chromium, and refuses a file three.quarks cannot parse. It also refuses an effect heavy enough to stall a player's tab: one past 64 objects, 16 emitters, 1,000 particles a second, 100 particles a metre or 5,000 particles alive at once, or emitters that prewarm more than 5 seconds of play, with every emitter's load summed, or one with a sprite past 4096 pixels a side. The picture it takes of the effect in the air is the effect's card in the store. The manifest records whether the effect loops, so `add asset` prints `spawn` for an effect that plays once and `Emitter` for one that loops.
+
+Pass every effect the scene plays in `effects`. `Particles` parses each one when the scene mounts, because a sprite decodes after the parse returns, and a burst drawn before then is black. A burst asked for while its sprite decodes waits, and plays where it was asked for. `spawn` throws on an effect that `effects` does not hold.
+
+## Changing a burst
+
+A burst can name three values, and the effect keeps its own for the next burst:
+
+- `color` is the colour every particle starts with.
+- `count` is how many particles each of the effect's bursts throws.
+- `yaw` turns the effect about y before it plays, for one authored pointing down -z, such as the blade's arc.
+
+For anything else, such as a lifetime or a speed, make a second effect.
+
+## Riding an object
+
+`<Emitter effect>` plays an effect under the object it is mounted in, in that object's space, for as long as it is mounted: a bolt's runes and trail, a torch's flame, a companion's dust. When it unmounts, the emission ends, the particles in the air finish their life where they are, and the effect then leaves the scene. `color` tints every particle it emits, as a burst's does. A view that holds a plain three.js object instead calls `useParticles().follow(effect, object, color)` and stops the handle it returns.
+
+## A spell's look
+
+[`<SpellLook>`](/engine/behaviours/abilities/#how-a-spell-looks) plays a spell's effects at its three moments: in the caster's hand during the wind-up, riding each of its projectiles, and where each ends. It plays them through `Particles`, so the scene's `effects` holds every one it names.
+
+An effect that rides is authored looping. One in world space with the trail render mode, as `bolt-trail.json` is, lays its ribbon where the object was and keeps only the head with it.
+
+## Checking a burst
+
+`Particles` exposes `{ bursts, particles, waiting }` to the tools under the page's `particles`: the effects playing, bursts and emitters alike, the particles in the air, and the effects that wait for a sprite. `spawnite play dump` prints them, and `spawnite play eval "views.page.particles"` reads them.
+
+## What the other engines do
+
+Roblox has `ParticleEmitter`, a component with props, placed in the world. Unity has the Particle System and VFX Graph, Unreal has Niagara, and Godot has `GPUParticles3D`: each is an effect made in an editor and played from code. Phaser has an emitter configured in code. PlayCanvas has a particle system component.
+
+This engine takes the editor model, because a finished effect has curves and ramps that are slow to write by hand and quick to tune by eye. It keeps code-built effects for an agent, which writes a constructor call well and cannot drive an editor.
+
+## Sample
+
+Sparks where the player clicks the ground, in `src/scenes/Sparks.tsx` of a game that ran `spawnite add asset bolt-burst`:
+
+```tsx
+// src/scenes/Sparks.tsx
+import { Particles, useParticles, World } from "@spawnite/engine";
+import effectBoltBurst from "../particles/bolt-burst.json";
+
+const effects = [effectBoltBurst];
+
+function Ground() {
+    const particles = useParticles();
+    return (
+        <mesh
+            rotation={[-Math.PI / 2, 0, 0]}
+            onClick={(event) =>
+                particles.spawn(effectBoltBurst, {
+                    at: event.point,
+                    color: "#ffd166",
+                })
+            }
+        >
+            <planeGeometry args={[20, 20]} />
+            <meshStandardMaterial />
+        </mesh>
+    );
+}
+
+export function Sparks() {
+    return (
+        <World map="meadow">
+            <Particles effects={effects} />
+            <Ground />
+        </World>
+    );
+}
+```
+
+## A burst from one entity
+
+A burst that belongs to one entity, such as the sparks where a coin is taken, comes from a view under that entity's `<Entity>` that passes `{ entity: useEntity() }` to `useEvent`. Without it, the view hears every entity's event, so every coin bursts whenever any coin is taken. The scene's `<Particles effects>` holds the sparks the coin is given:
+
+```tsx title="packages/engine/test/outside/Coin.tsx"
+import {
+    Entity,
+    Pickup,
+    TakenEvent,
+    useEntity,
+    useEvent,
+    useFloatingText,
+    useParticles,
+    type ParticleEffect,
+    type Position,
+} from "@spawnite/engine";
+
+export interface CoinProps {
+    position: Position;
+    /** The burst where the coin is taken, one of the scene's
+     *  `<Particles effects>`. */
+    sparks: ParticleEffect;
+}
+
+export function Coin({ position, sparks }: CoinProps) {
+    return (
+        <Entity position={position}>
+            <Pickup reward={1} />
+            <CoinTaken position={position} sparks={sparks} />
+            <mesh>
+                <cylinderGeometry args={[0.4, 0.4, 0.1, 24]} />
+                <meshStandardMaterial color="gold" />
+            </mesh>
+        </Entity>
+    );
+}
+
+//  Under the coin's Entity, so `useEntity()` is this coin. Without
+//  `{ entity }` the view hears every coin's TakenEvent, and each coin
+//  would burst whenever any coin is taken.
+function CoinTaken({ position, sparks }: CoinProps) {
+    const floatingText = useFloatingText();
+    const particles = useParticles();
+    useEvent(
+        TakenEvent,
+        () => {
+            floatingText.show({ at: position, text: "+1", color: "gold" });
+            particles.spawn(sparks, { at: position, color: "#ffd166" });
+        },
+        { entity: useEntity() },
+    );
+    return null;
+}
+```
+
+## Where it runs
+
+Client. A burst changes nothing in the world; each player's browser draws its own. Headless and on a room's server, `Particles` and `Emitter` render nothing and `spawn` does nothing, so a hit's damage belongs in a system and its sparks in a view that hears the hit with [`useEvent`](https://wiki.spawnite.com/reference/entity/useevent/).

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

@@ -0,0 +1,49 @@
+---
+title: Portal material
+description: Draws a glowing, warping ring on a plane, for a door to the next level or a way between places.
+useCases:
+    - portal to the next level
+    - teleport door
+    - glowing warp ring
+    - magic gateway
+    - dimensional rift
+    - level exit door effect
+    - see through portal
+sidebar:
+    order: 10
+---
+
+`<PortalMaterial>` is the material of the plane it sits in, inside a [World](/engine/structure/world/): a white-hot ring inside a wider fringe of colour, both bent by noise, over a faint haze that breathes. Use it for a door to the next level or a way between two places. It runs on the world's clock, as every [Shader](/engine/graphics/shader/) does, so a paused game holds the ring still.
+
+Its props are in [`PortalMaterialProps`](https://wiki.spawnite.com/reference/materials/portalmaterialprops/).
+
+The ring fills about two thirds of the plane, and its glow fades out before the plane's edge. The portal is see-through, so the world behind it shows through the ring.
+
+Roblox has no portal; creators build one from parts, a Beam and a ParticleEmitter. Unity, Unreal and Godot ship none either; creators buy one from a store or copy one from godotshaders.com. This one is a single material with three props.
+
+The shader is [ThreeUI's portal field](https://github.com/MengTo/threeui/tree/68802d5428071ada5c20db8094b1649e6bb770ed/src/shaders/neuform-isolated/sources/portal-field.html) by Meng To, MIT, moved from behind a web page onto a plane's UVs, without the page's pointer parallax or its light theme. Its source is `portalFragment`: copy it, change a block and pass it to a `Shader` for a portal of your own.
+
+## Sample
+
+An orange portal standing in the meadow:
+
+```tsx
+import { Entity, PortalMaterial, World } from "@spawnite/engine";
+
+export function Door() {
+    return (
+        <World map="meadow">
+            <Entity position={[0, 1.2, -3]}>
+                <mesh>
+                    <planeGeometry args={[2, 2]} />
+                    <PortalMaterial color="orange" />
+                </mesh>
+            </Entity>
+        </World>
+    );
+}
+```
+
+## Where it runs
+
+Client. The portal changes nothing in the world; each player's browser draws its own. What stepping through it does is the game's.