@spawnite/engine 0.1.0-beta.15

package/dist/wiki/engine/ui/drag-and-drop.md

@@ -0,0 +1,134 @@
+---
+title: Drag and drop
+description: Drag a potion onto a hotbar slot, an item into a bag cell, a skill onto a pad.
+useCases:
+    - drag items between inventory slots
+    - drag a potion onto a hotbar slot
+    - drag and drop in a game ui
+    - slot based inventory ui
+    - drop an item on a target
+    - drag with a finger on a phone
+    - rearrange the hotbar
+sidebar:
+    order: 14
+---
+
+`<Draggable data>` makes what it wraps draggable, and `<DropTarget onDrop>` is where a drag lands. The data a Draggable carries is the game's own, such as an item's id, and the DropTarget that takes it gets that data in `onDrop`. A drag works with a mouse or a finger, from one [Hud](/engine/ui/hud/) to another.
+
+Their props are in [`DraggableProps`](https://wiki.spawnite.com/reference/ui/draggableprops/) and [`DropTargetProps`](https://wiki.spawnite.com/reference/ui/droptargetprops/).
+
+Both need the `dragAndDrop()` plugin in the Game's plugins, which holds the drags of the whole screen:
+
+```tsx
+import { dragAndDrop, Game, type PluginList } from "@spawnite/engine";
+
+const plugins: PluginList = [dragAndDrop()];
+
+export function App() {
+    return (
+        <Game name="hotbar" start="town" plugins={plugins}>
+            {/* scenes */}
+        </Game>
+    );
+}
+```
+
+The plugin loads [dnd-kit](https://dndkit.com/), about 34 KB gzipped, as a file of its own in the browser, so a game that drags nothing never fetches it, and a room or a test in Node never loads it. The game's first frame waits for that file, as it waits for the save. A Draggable in a game without the plugin throws an error that names it.
+
+```tsx
+import {
+    Button,
+    Draggable,
+    DropTarget,
+    Hud,
+    Panel,
+    Slot,
+} from "@spawnite/engine";
+
+type Potion = { kind: "potion"; name: string };
+
+function isPotion(data: unknown): data is Potion {
+    return (
+        typeof data === "object" &&
+        data !== null &&
+        "kind" in data &&
+        data.kind === "potion"
+    );
+}
+
+interface HotbarProps {
+    bag: Potion[];
+    pads: (Potion | null)[];
+    setPad: (index: number, potion: Potion | null) => void;
+    drink: (potion: Potion) => void;
+}
+
+export function Hotbar({ bag, pads, setPad, drink }: HotbarProps) {
+    return (
+        <Hud>
+            <Panel slot={Slot.Center}>
+                {bag.map((potion) => (
+                    <Draggable key={potion.name} data={potion}>
+                        <Button onPress={() => drink(potion)}>
+                            {potion.name}
+                        </Button>
+                    </Draggable>
+                ))}
+            </Panel>
+            <Panel slot={Slot.Bottom}>
+                {pads.map((pad, index) => (
+                    <DropTarget
+                        key={index}
+                        accepts={isPotion}
+                        onDrop={(potion) => setPad(index, potion)}
+                        className="rounded-xl data-[over]:ring-2 data-[over]:ring-white"
+                    >
+                        <Draggable
+                            data={pad}
+                            disabled={pad === null}
+                            onDragEnd={({ dropped, canceled }) => {
+                                if (!dropped && !canceled) setPad(index, null);
+                            }}
+                        >
+                            <Button
+                                label={`Pad ${index + 1}`}
+                                onPress={() => pad && drink(pad)}
+                            >
+                                {pad?.name ?? "Empty"}
+                            </Button>
+                        </Draggable>
+                    </DropTarget>
+                ))}
+            </Panel>
+        </Hud>
+    );
+}
+```
+
+## Dragging
+
+A mouse press becomes a drag once it moves 8 pixels, and a finger once it holds still for a quarter of a second, so a swipe still scrolls a window. A press that does not become a drag reaches the Button inside as a press, and the release that ends a drag presses nothing.
+
+While dragged, a copy of the children follows the pointer and the children stay where they are, as an item stays in its cell until it lands. `preview` shows something else under the pointer, such as the item's icon for a whole row of the bag. `disabled` takes no drag and leaves every press to the children.
+
+`onDragEnd({ dropped, canceled })` runs when the drag ends: `dropped` is true when a DropTarget took it, and `canceled` is true when Escape called it off, which puts everything back as it was. While a drag runs, Escape cancels it before it closes a [Window](/engine/ui/window/) or opens the menu. A hotbar slot dropped on nothing, neither dropped nor canceled, clears itself.
+
+`useDragging()` is true while any drag is under way, such as to fade a window that stands over the hotbar.
+
+## Dropping
+
+`accepts` is a type guard on what the drag carries. A drag it refuses passes over the DropTarget as if it were not there, and `onDrop` gets the data typed by the guard. A DropTarget with no `accepts` takes every drag, and its `onDrop` gets `unknown`, so TypeScript refuses a typed `onDrop` without the guard that makes it true.
+
+A drop lands on the DropTarget under the pointer through anything drawn over it, such as a window's dimmed screen. While a drag it takes is over it, the DropTarget sets its `data-over` attribute, which a class such as `data-[over]:ring-2` styles.
+
+Both components draw a `div` around their children, which takes `className` and `style` for its size and place, and each shows as a row in the devtools tree.
+
+## Keyboard
+
+A drag takes a pointer. Enter and Space press the Button a Draggable holds, as they do anywhere else, so a keyboard player uses the Button's own action.
+
+## What other engines do
+
+Godot, Unity, Unreal and Phaser split a drag the same way: the thing dragged carries the data, and the target decides whether to take it. Godot overrides `_get_drag_data`, `_can_drop_data` and `_drop_data` on a Control. Unity's UGUI puts `IDragHandler` on the source and `IDropHandler` on the target. Unreal makes a `UDragDropOperation` with a payload in `OnDragDetected`, and the target overrides `OnDrop`. Roblox's `UIDragDetector` and PlayCanvas's `ElementDragHelper` drag without a target, and the game checks what lies under the pointer when the drag ends. Here, `accepts` is Godot's `_can_drop_data`, and `onDragEnd`'s `dropped` is Godot's `is_drag_successful()` and Unity's `OnEndDrag`. The engine builds both on [dnd-kit](https://dndkit.com/).
+
+Cost per frame: none. During a drag, each move of the pointer tests the dragged copy's box against each DropTarget's box.

package/dist/wiki/engine/ui/floating-text.md

@@ -0,0 +1,129 @@
+---
+title: Floating text
+description: Shows a short text at a point in the world, such as a damage number over an enemy, which rises and fades on the screen.
+useCases:
+    - damage numbers
+    - floating text over an enemy
+    - heal numbers
+    - coin amount popup
+    - text that rises and fades
+    - number popup at a hit point
+    - battle damage display
+sidebar:
+    order: 30
+---
+
+`<FloatingText>` holds a pool of texts that stand at a point in the world. Mount one in a scene, inside a [World](/engine/structure/world/) beside its views. Any view in the scene then shows a text with `useFloatingText().show({ at, text })`: a damage number over what was hit, a coin's worth where it was picked up. `at` takes a vector, `{ x, y, z }`, or an entity's `[x, y, z]` `position` as it is.
+
+Its props are in [`FloatingTextProps`](https://wiki.spawnite.com/reference/ui/floatingtextprops/), and a text's in [`FloatedText`](https://wiki.spawnite.com/reference/ui/floatedtext/).
+
+Each text rises and fades over its seconds, then hides. The pool writes its elements in place each frame, so a hit mounts nothing and a crowd of hits renders nothing in React. The pool holds `capacity` texts, 48 unless changed. One more drops the oldest.
+
+## Styling the text
+
+The pool draws small bold white text with a dark edge. Pass `className` to the pool to change the font, the size or the shadow of every text. Pass `color` with a text to colour that one, and `className` with a text for its own size, colour or animation: a crit larger and gold, a burn small and orange. The text's classes sit on the text itself, apart from the element that moves and fades it, so a class that animates the text's own transform runs.
+
+## Checking a text
+
+`FloatingText` exposes `{ shown }`, the texts on the screen, to the tools under the page's `floating text`. `spawnite play dump` prints it, and `spawnite play eval "views.page['floating text']"` reads it.
+
+## What the other engines do
+
+Roblox shows a `BillboardGui` over a part, Unity a world-space TextMeshPro, and Godot a `Label3D`: each is an object in the scene, one per text, which a game pools by hand. Unreal draws a widget component over an actor. Phaser pools text objects. PlayCanvas has an element component.
+
+This engine pools the texts itself and takes one call per text, because every game with damage numbers writes the same pool. The text is DOM over the canvas, not a mesh in the scene, so it stays sharp at any distance and takes the game's fonts.
+
+## Sample
+
+A number over a target each time it is hit:
+
+```tsx
+import {
+    DamagedEvent,
+    FloatingText,
+    useEvent,
+    useFloatingText,
+    World,
+} from "@spawnite/engine";
+
+function DamageNumbers() {
+    const floatingText = useFloatingText();
+    //  Each hit once, where it landed, a killing blow's too.
+    useEvent(DamagedEvent, ({ record: hit }) => {
+        floatingText.show({
+            at: { x: hit.at.x, y: hit.at.y + 2, z: hit.at.z },
+            text: String(Math.round(hit.amount)),
+            color: hit.amount >= 50 ? "#ffe08a" : undefined,
+        });
+    });
+    return null;
+}
+
+export function Arena() {
+    return (
+        <World map="meadow">
+            <FloatingText />
+            <DamageNumbers />
+        </World>
+    );
+}
+```
+
+## A text from one entity
+
+A text that belongs to one entity, such as a coin's "+1", 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 shows a "+1" whenever any coin is taken. The coin's own `position` goes straight to `at`:
+
+```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 text changes nothing in the world; each player's browser draws its own. Headless and on a room's server, `FloatingText` renders nothing and `show` does nothing.

package/dist/wiki/engine/ui/graphics-quality.md

@@ -0,0 +1,254 @@
+---
+title: Graphics quality
+description: The quality levels, how Automatic picks one for a device, dynamic resolution, the frame rate limit, how a game changes what a level means, and the performance overlay.
+useCases:
+    - graphics quality setting
+    - frame rate limit
+    - show an fps counter
+    - low quality on phones
+    - change what low quality turns off
+    - dynamic resolution
+    - pick quality by device
+sidebar:
+    order: 12.1
+---
+
+The Settings panel's Video tab sets the quality the engine draws at; [Settings](/engine/ui/settings/) describes the rest of the panel.
+
+The engine owns graphics quality, and a game wires none of it. The engine reads the device once, applies a quality level to everything it draws, and gives the player the Video tab's Quality rows. A creator changes what a level means with one setting, Game's `quality` prop. The level belongs to the game, under the game's name, because one game's scene costs more to draw than another's.
+
+## The levels
+
+A level is a full set of values. The engine ships four:
+
+| Value                       | Minimum     | Low         | Medium      | High     | What it sets                                                                      |
+| --------------------------- | ----------- | ----------- | ----------- | -------- | --------------------------------------------------------------------------------- |
+| `pixelRatio`                | 0.75        | 1           | 1.5         | 2        | The cap on the canvas's pixel ratio, never above the screen's own.                |
+| `shadowMapSize`             | 0           | 0           | 1024        | 2048     | The side of the sun's shadow map in texels; 0 casts none.                         |
+| `grading`                   | off         | off         | on          | on       | The look's colour grade and its vignette.                                         |
+| `bloom`                     | off         | off         | on          | on       | Bloom, the look's and a scene's own.                                              |
+| `occlusion`                 | off         | off         | on          | on       | Ambient occlusion, the look's and a scene's own.                                  |
+| `occlusionQuality`          | performance | performance | performance | medium   | Ambient occlusion's sample preset.                                                |
+| `occlusionHalfResolution`   | on          | on          | on          | on       | Whether occlusion samples at half the canvas's resolution, a quarter of the cost. |
+| `multisampling`             | 0           | 2           | 2           | 4        | The stack's samples per pixel; none where the level draws at a pixel ratio of 2.  |
+| `scatter`                   | 0           | 0           | 1           | 1        | The share of the decorative scatter that stands.                                  |
+| `scatterNear`, `scatterFar` | 15, 20 m    | 22.5, 30 m  | 34, 45 m    | 45, 60 m | Where bushes and tufts start to shrink, and where they are gone.                  |
+| `grassShare`                | 0           | 0.3         | 0.75        | 1        | The share of the grass blades.                                                    |
+| `grassNear`, `grassFar`     | 0, 0 m      | 4, 12 m     | 9, 28 m     | 9, 28 m  | Where the blades start to thin, and where the last one goes.                      |
+| `grassSway`                 | off         | off         | on          | on       | Whether the blades bend in the wind, until the player sets Grass sway.            |
+| `groundDetail`              | off         | off         | on          | on       | The ground's random turn of each cell's textures, and its noisy seams.            |
+
+Bushes and tufts shrink away over the last quarter of their distance from the eye, and the grass blades thin over theirs, so neither pops. Trees and rocks draw at every distance: they are the map's shape, and what blocks a walker always stands, in a room on the server and every page alike. Ambient occlusion stays at half resolution at every level: at full resolution it cost about 2 ms more of a desktop card's frame, a quarter of the budget.
+
+A scene that passes its own `shadowMapSize` or `scatterShare` to `World`, or mounts its own `<PostProcessing>` with its own props, keeps them at every level, except that its `<Bloom>` and `<AmbientOcclusion>` follow `bloom` and `occlusion`.
+
+## Post-processing by part
+
+The look's stack draws in three parts, and a level sets each one: `grading`, the colour grade (tint, hue and saturation, brightness and contrast) with the vignette; `bloom`; and `occlusion`, ambient occlusion. The grade and the vignette are one value because they draw in one pass with tone mapping, so apart they would cost nothing to drop. The stack mounts while any part draws. Tone mapping draws at every level: in the stack while one mounts, and by the renderer's own ACES curve where none does, so the frame's light maps the same way at Minimum as at High.
+
+The parts follow Unreal's post-processing ladder, where ambient occlusion goes first and the grade, tone mapping and bloom stay through its lowest level:
+
+| Part                | Minimum | Low    | Medium | High | Unreal's Low, Medium, High                       |
+| ------------------- | ------- | ------ | ------ | ---- | ------------------------------------------------ |
+| Grade, tone mapping | ACES    | ACES   | on     | on   | on at every level                                |
+| Vignette            | off     | off    | on     | on   | off, on, on                                      |
+| Bloom               | off     | off    | on     | on   | on at a quarter, a third and half resolution     |
+| Ambient occlusion   | off     | off    | on     | on   | off, on, on, at more samples                     |
+| Anti-aliasing       | canvas  | canvas | 2x     | 4x   | not a scalability level: a project sets its MSAA |
+
+Low keeps no stack until a reading on a weak GPU prices the grade and bloom there, since Low is what a phone and a weak laptop get. A game turns them on for Low with `levels: { [QualityLevel.Low]: { grading: true, bloom: true } }`, and Low then smooths in the stack at its own 2 samples. Unreal's lowest level draws the grade and bloom on a desktop and turns bloom off on Android. Minimum has no counterpart in Unreal: it is the floor below Low. Bloom is one value here, where Unreal also lowers its resolution per level.
+
+## Automatic
+
+Automatic is where a new player starts. On the first visit, before the scene mounts, the engine reads the device: the renderer's name from the canvas's WebGL context, whether the main pointer is a finger, and the screen's size and pixel ratio. It makes one of five device classes of that reading, and each class starts at a level the game can change:
+
+| Device class                          | What the engine reads it from                                                                                                                                                                                                                 | Starts at |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
+| `DeviceClass.Software`                | A renderer that draws on the CPU, such as SwiftShader, llvmpipe or Microsoft Basic Render: a browser with no GPU, or a test machine.                                                                                                          | Minimum   |
+| `DeviceClass.Touch`                   | A main pointer that is a finger: a phone or a tablet.                                                                                                                                                                                         | Low       |
+| `DeviceClass.Computer`                | Any other computer, and any device whose browser hides the renderer's name.                                                                                                                                                                   | Medium    |
+| `DeviceClass.GraphicsCard`            | A renderer that names a recent graphics card, an NVIDIA RTX, an AMD Radeon RX 5000 or later, an Intel Arc, or an Apple M-series Pro, Max or Ultra, on a screen up to a 3440x1440 ultrawide: at most 5.5 million pixels at High's pixel ratio. | High      |
+| `DeviceClass.GraphicsCardLargeScreen` | The same card on a larger screen, such as 4K or a 5120x1440 ultrawide, or on a screen the page cannot read.                                                                                                                                   | Medium    |
+
+The screen counts whole, whatever the window's size, since a player picks in a window and then goes fullscreen. It counts because the pixels a level draws are most of its cost. On an RTX 4070 SUPER, Holdfast's full room of four wardens at High drew the GPU's slowest 5% of frames in 5.7 to 5.8 ms at 3440x1440, well under the 120 Hz budget of 8.33 ms, and in 9.4 to 9.8 ms at 3840x2160, past it. Medium drew no faster at 4K's pixels, 9.2 to 9.6 ms; it saves time where its lower pixel-ratio cap draws fewer pixels than High, on a dense screen such as a 4K one at twice the page's scale.
+
+The engine saves its reading under the game's name, and every later visit keeps it, so a player's level does not move between visits; a new renderer reads the device again. The level comes from the game's setting as it stands on each visit, so a game that changes its start reaches its returning players too. Automatic never changes the level during play, and a level the player picked stays hers. The quality row says what it picked and for which class, such as "Automatic chose High for a recent graphics card",. Nothing is fetched: detect-gpu's benchmark data comes from a CDN a game page's policy refuses. Headless, in a room's server and in `spawnite simulate`, the engine reads no device, and Automatic draws Medium's values.
+
+### Setting where each device starts
+
+`quality.start` maps a device class to the level it starts at. A class it leaves out starts at the engine's level, which `engineStartLevels` exports:
+
+```tsx
+import { DeviceClass, Game, QualityLevel } from "@spawnite/engine";
+
+<Game
+    name="bladebound"
+    start="lobby"
+    quality={{
+        start: {
+            [DeviceClass.GraphicsCardLargeScreen]: QualityLevel.High,
+            [DeviceClass.Touch]: QualityLevel.Minimum,
+        },
+    }}
+>
+    {/* scenes */}
+</Game>;
+```
+
+Where the classes are too coarse, `start` also takes a function. It receives the device's reading, a `DeviceReading`: `deviceClass`, the class the engine made of it; `renderer`, the name as the browser gives it, which a browser may mask, as Safari's "Apple GPU" does, or leave empty; `coarsePointer`; `screenPixels`, the screen's own pixels; and `devicePixelRatio`. It returns a level, or `undefined` to keep the engine's level for that device. This one starts one family of cards a level lower, which a map cannot say:
+
+```tsx
+import { QualityLevel, type QualityOptions } from "@spawnite/engine";
+
+//  Passed as Game's quality prop.
+export const quality: QualityOptions = {
+    start: (device) =>
+        /RTX 20\d\d/.test(device.renderer) ? QualityLevel.Medium : undefined,
+};
+```
+
+The function runs once each time the game loads, before the scene mounts, never during play. A map that names a class with anything but Minimum, Low, Medium or High throws when Game mounts, naming the class. A function runs on the player's device, so one that throws or returns anything else starts that device at the engine's level, with one console warning that says what it returned.
+
+The boot checks open each game at `?quality=minimum`, so the software GPU they run on never decides what Low means.
+
+## Dynamic resolution
+
+Dynamic resolution is a row of its own, a switch the player owns. While it is on, the engine lowers the canvas's resolution when the frames run slow and raises it again once they keep up, between the game's bounds and never above the render scale row. While it is off, the resolution is the level's pixel ratio times the render scale, fixed. It starts on where the main pointer is a finger, since a phone slows as it heats and its players rarely open a settings panel, and off on a computer, where a player expects the resolution she set. A creator sets the default and the bounds with `quality.dynamicResolution`; the player's row wins over both.
+
+The scaler steps through 100%, 85%, 70%, 60% and 50% of the level's pixel ratio. It counts frames in half-second windows and reacts to their average, never to one slow frame, so a game that holds its frame rate with a poor 1% low keeps its resolution:
+
+- It holds 60 frames a second, or the game's `targetFrameRate` up to the screen's rate. The screen's rate, which the page reads from its own frames, never takes the target under 60: a page that falls behind would read a slower screen.
+- It drops one notch when three of the last four windows ran under 85% of that, or two in a row under half of it.
+- It rises one notch only after five seconds at a notch and two seconds at 95% or more, as a trial: the first half second that misses puts the notch back, and that notch waits 10 seconds before the next try, twice as long each time it fails again, up to five minutes.
+- A drop that buys no frame time is put back, and after two in a row the scaler stops until the scene changes: the frame is not the GPU's, and fewer pixels would blur it for nothing.
+- It counts nothing while the loading screen shows, the tab is hidden or the devtools hold the world, and it starts afresh on a new scene, level or render scale.
+
+Each step resizes the canvas's drawing buffer and the post-processing targets, so the steps are few and coarse. Unity and Unreal render into part of a target allocated at the largest size and resize nothing; that needs an upscale pass on every frame here, at every level, and is left for later.
+
+## The player's rows
+
+The quality preset picks Automatic or a level. Under it, a row for each feature group picks which level's values that feature draws, as Unreal's scalability groups do:
+
+| Row               | Values it takes from its level                                                             |
+| ----------------- | ------------------------------------------------------------------------------------------ |
+| Shadows           | `shadowMapSize`                                                                            |
+| Post-processing   | `grading`, `bloom`                                                                         |
+| Ambient occlusion | `occlusion`, `occlusionQuality`, `occlusionHalfResolution`                                 |
+| Anti-aliasing     | `multisampling`                                                                            |
+| Foliage           | `scatter`, `scatterNear`, `scatterFar`, `grassShare`, `grassNear`, `grassFar`, `grassSway` |
+| Terrain detail    | `groundDetail`                                                                             |
+
+The pixel ratio follows the preset, and the 3D resolution row scales it. A feature row offers one option for each look it draws across the levels, after the game's overrides, so no two options draw alike. An option reads Off where it draws none of its feature, the Anti-aliasing row names its samples, such as 2x, and any other option takes the name of the highest level that draws it: the engine's Shadows row offers Off, Medium and High, Anti-aliasing offers Off, 2x and 4x, Terrain detail and Post-processing are switches, and a group that draws one look at every level shows no row. Every level that draws none of a feature shares the one Off. Two choices make a switch only where one is Off; any other pair, and Anti-aliasing always, shows its names. Where the quality row's level and the render scale draw at a pixel ratio of 2 or more, as on a Retina screen at High, the stack draws no samples at any level, so the Anti-aliasing row hides. A feature row the player sets is pinned, and the preset then reads Custom; picking a level or Automatic there unpins every row. A row nobody pinned follows the preset, Automatic included.
+
+The Post-processing and Ambient occlusion rows follow what the scene draws. A look's stack offers its grade, its bloom and its ambient occlusion, and a scene's own `<Bloom>` or `<AmbientOcclusion>` offers its part, whether or not the level draws it now; a row compares the levels only on the parts something offers, and hides where they all draw alike. A scene whose own stack draws bloom alone, as Depthfield's field does, shows no Ambient occlusion row, and no Post-processing row where its bloom draws at every level. A row the player pinned stays while it is pinned, whatever the scene offers, since the preset reads Custom until she unpins it and the row is where she does; it then offers every look its group draws.
+
+A change the player makes applies at once, all of it, the scatter included. The menu is open, so a moment's hitch there is fine.
+
+## Changing what a level means
+
+Pass Game's `quality` prop with only what your game changes; the engine's values fill in the rest:
+
+```tsx
+import { Game, QualityLevel } from "@spawnite/engine";
+
+export function App() {
+    return (
+        <Game
+            name="bladebound"
+            start="lobby"
+            quality={{
+                levels: {
+                    [QualityLevel.Low]: { scatter: 0.12 },
+                    [QualityLevel.Medium]: { scatter: 0.3 },
+                    [QualityLevel.High]: { shadowMapSize: 1024 },
+                },
+                dynamicResolution: { minimumScale: 0.7 },
+            }}
+        >
+            {/* scenes */}
+        </Game>
+    );
+}
+```
+
+Game reads `quality` once, when it mounts, and throws for a value no level can draw, naming the level and the field, or for a start that is no level, naming the class. Its fields:
+
+- `levels`: each level's values over the engine's own, as `QualitySettings` names them.
+- `start`: the level each device class starts at under Automatic, as [Setting where each device starts](#setting-where-each-device-starts) shows.
+- `dynamicResolution`: `true` or `false` sets whether the row starts on; an object also sets `minimumScale` and `maximumScale`, the shares of the level's pixel ratio the scaler keeps between, 0.5 and 1 by default, and `targetFrameRate`, the rate it holds.
+
+A game reads quality with three hooks:
+
+- `useQualitySettings()` returns the values in force: each row's level, Automatic resolved, the game's overrides applied. With a selector it returns one value, as zustand's hooks do: `useQualitySettings((settings) => settings.shadowMapSize)`.
+- `useActiveQualityLevel()` returns the level in force, Automatic resolved, or given a `QualityGroup`, that feature row's. A game maps its own per-level values from it, such as a particle count for each level.
+- `useQualityLevel()` returns what the quality row holds, Automatic included.
+
+`useQualityStore()` returns the store for its verbs: `setLevel`, `setGroupLevel`, `setRenderScale`, `setDynamicResolution` and `resetQuality`. A game's own quality setting is a `<SettingRow>` on the Video tab over a store of its own, or a value it maps from `useActiveQualityLevel`.
+
+## Frame rate limit
+
+The frame rate limit draws one frame every second, third or fourth refresh the screen offers, so a 120 Hz screen offers 60, 40 and 30, a 144 Hz screen 72, 48 and 36, and a 60 Hz screen 30 and 20. Only a whole divisor of the refresh rate keeps the frames even: a cap of 50 on a 60 Hz screen would alternate one refresh and two, the stutter a cap is meant to prevent. A browser cannot draw faster than the screen, so no option is higher. The engine reads the refresh rate from the frames, so the options follow the screen the page is on, and a saved cap paces to the nearest divisor on another screen. The cap is the player's own, carried from game to game, because it is about her device's battery, heat and fan. Roblox offers 60, 120, 144 and 240 on a computer, Lyra 30 to 360, and Unity's web docs advise leaving the cap off, since a cap that is no divisor stutters.
+
+## How other games do it
+
+Each choice here, beside what the engines and the games a player knows do:
+
+| Choice here                                                 | What others do                                                                                                                                                                                                                                                                                      |
+| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Automatic picks a level once, from the device, and keeps it | Valorant and Counter-Strike 2 detect the PC at first launch and change no setting on their own; Unreal's hardware benchmark runs once; Unity picks nothing. Roblox's Automatic moves the level during play from the frame rate, and its players report the level rising while the frame rate falls. |
+| No level changes during play                                | Fortnite on PC changes no quality setting by itself. Phone games limit each device's options by chipset or model rather than move them.                                                                                                                                                             |
+| Dynamic resolution is its own switch                        | Fortnite's Dynamic 3D Resolution and Apex's adaptive resolution are switches a PC player turns on, and Unreal ships it off. Consoles scale resolution by default.                                                                                                                                   |
+| On where the pointer is a finger, off on a computer         | Consoles and phone games scale without asking. Epic keeps PC resolution fixed because "we could not guarantee a consistent quality when reducing the resolution".                                                                                                                                   |
+| The game sets where each device class starts                | Unity sets a default quality level for each build platform, and Unreal's device profiles match a device by rules and set its scalability levels; Godot and PlayCanvas leave the pick to game code, and Roblox gives a game no say.                                                                  |
+| Each value of a level is the creator's                      | Unity's quality levels and Unreal's `[ShadowQuality@0]` sections let a project redefine each level; Roblox and PlayCanvas offer no levels to redefine.                                                                                                                                              |
+| Feature rows under a preset that reads Custom               | Fortnite, Counter-Strike 2, Minecraft and the Nixxes ports do this; Unreal's `GetOverallScalabilityLevel` returns -1 for custom.                                                                                                                                                                    |
+
+## The performance overlay
+
+The overlay is small corner text, 11 and 12 px on the menu's pane, as Overwatch's and Fortnite's readouts stand over play. It stands in the top-left corner's row, after the Menu and microphone buttons, its top level with theirs, as Roblox's stats bar runs beside its buttons; where the row shows no button, it stands in the corner itself. On a touch screen it stands under the buttons, its left edge with theirs, since a phone's narrow top edge holds the game's own panels; and where any screen is too narrow for the buttons and the overlay side by side, less the app's insets, the row wraps and the overlay stands under them too. It has four levels, as Steam's and PlayCanvas's performance readouts do:
+
+- **Off**, the default.
+- **FPS:** one line, about 22 px tall: the frame rate and, in a game with a room, the ping, such as `120 FPS  58 ms`.
+- **Graph:** FPS's line, then a second line with the 1% low and the last ten seconds of frame times as a small line beside it: one thin grey stroke with no guide, no label and no red, so a steady frame is a flat line low in its box and a stutter is a peak.
+- **Full:** Graph's lines, with the ping's jitter beside the ping as a plus-minus, such as `58 ms ±4`, then a third line with the CPU's and the GPU's time per frame: three short lines. The jitter shows at Full alone.
+
+The quality level and the 3D resolution are settings rather than live numbers, so the overlay leaves them to their rows in the Video tab. The screen's refresh rate shows nowhere: the overlay reads it only to colour the frame rate, as [What each number measures](#what-each-number-measures) says. The draw calls, the triangles and the server's tick time are in the devtools' [Frame tab](/engine/testing/devtools/#the-frame-split), beside the frame split.
+
+The overlay never scrolls. On a screen too short for every line, such as a phone held sideways with something above the corner, it drops lines from the bottom until it fits its corner, and shows them again when the window grows.
+
+F2 steps through the levels while the game plays, and so does a tap or a click on the overlay. No browser binds F2 and no game on the platform does; on a Mac keyboard it needs the Fn key. A key press in a text field stays with the field.
+
+### What each number measures
+
+The frame readings count the frames the canvas draws, sampled twice a second, so a paused world that stops drawing reads 0 FPS. Each frame is timed from the moment the browser hands it to the canvas to the moment it hands the next, the timestamp `requestAnimationFrame` passes, so a frame whose code starts a few milliseconds late but still makes its refresh reads as an on-time frame, as it looks on the screen.
+
+- **FPS:** the frames drawn in the last half second, per second.
+- **1% low:** the frame rate of the slowest 1% of the frames of the last ten seconds, from the average of their times: at 120 Hz, the slowest 12 of about 1,200. CapFrameX's "1% low average" and NVIDIA FrameView define it the same way; RTSS's integral mode instead reads the frame time at which the slowest frames reach 1% of the ten seconds, which moves less for one long stall. The 99th-percentile frame, which PresentMon reports, reads one frame and ignores how slow the rest of the slowest are. Because only about a dozen frames decide it, one missed refresh in ten seconds at 120 Hz reads about 111, two about 103, and one 75 ms stall about 72, while the FPS holds 120: the number says how bad the worst moments of the last ten seconds were, not how often they came.
+- **CPU:** the page's own work per frame, from the start of Fiber's frame to the end of its render, averaged over the last 60 frames. It holds the game's code, the engine's systems and the draw calls three.js makes.
+- **GPU:** the graphics card's time per frame, from the browser's timer query, `EXT_disjoint_timer_query_webgl2`, averaged over the last 60 frames. Only desktop Chrome and Edge offer it; Firefox, Safari and every phone read n/a, since the frame less its CPU time would be a guess.
+- **The screen's refresh rate,** which the overlay does not show but rates the frame rate against, and which no browser reports. The overlay reads it from the frames that waited one refresh: a frame that misses one waits two, so the fastest frames of the last ten seconds carry the rate, not their average. It snaps to a rate screens ship with when within 3% of one, so 59.94 reads 60, and it changes only once four readings in a row, two seconds, agree on another rate, so one odd window, such as the loading screen's frames, does not set it, and moving the window to a slower screen brings it down. A game that never once reaches the screen's rate, such as one that draws a steady 30 frames a second on a 144 Hz screen from its first frame, reads its own rate as the screen's: every frame the browser draws waits on the same main thread and the same refresh, so no second measure would see more.
+- **Ping:** the round trip to the room and back, the mean of the last eight.
+- **Jitter:** how much the ping wanders: the mean change from one of those round trips to the next.
+
+Colour says how a value stands: green, amber past the first bound, red past the second. The frame rate's bounds follow the screen, so 100 FPS is amber on a 144 Hz screen and green on a 60 Hz one.
+
+| Value                   | Amber past                                              | Red past |
+| ----------------------- | ------------------------------------------------------- | -------- |
+| FPS and 1% low          | below 55 on a 60 Hz screen, the same share of any other | below 30 |
+| CPU, GPU and frame time | the time a frame has at that rate                       | 33.3 ms  |
+| Ping                    | 80 ms                                                   | 150 ms   |
+| Jitter                  | 10 ms                                                   | 30 ms    |
+
+The overlay costs the frame almost nothing: it adds one number to a list each frame, and renders twice a second. [Its measured cost](#the-overlays-own-cost) is below.
+
+### The overlay's own cost
+
+Measured on a desktop machine, with ten seconds of frames in the history:
+
+| Work                                                     | How often      | Cost                                 |
+| -------------------------------------------------------- | -------------- | ------------------------------------ |
+| Keep the frame's time                                    | every frame    | about 0.015 µs                       |
+| Read the 1% low, the refresh rate and the graph's points | twice a second | 0.04 ms at 144 Hz, 0.07 ms at 240 Hz |
+| Render the overlay                                       | twice a second | one React render of the panel        |
+
+Full also turns on the frame timing the devtools use: a few clock reads and one GPU timer query per frame, which the browser answers a frame or two later without stalling the frame. At 144 Hz a frame has 6.9 ms; the measured work above comes to about 0.001 ms a frame once the twice-a-second reads are spread over the frames between them.

package/dist/wiki/engine/ui/heading.md

@@ -0,0 +1,43 @@
+---
+title: Heading
+description: A title drawn straight onto the game, at one of four levels.
+useCases:
+    - game title text
+    - level name on screen
+    - wave title
+    - big heading over the game
+    - title screen text
+    - screen heading
+sidebar:
+    order: 4
+---
+
+`<Heading>` draws a title over the world with the same white and thin dark edge as [Text](/engine/ui/text/), at one of four levels. The level picks the element, `h1` to `h4`, and a default size and weight from [shadcn's typography scale](https://ui.shadcn.com/docs/components/typography):
+
+| level | element | size and weight                     |
+| ----- | ------- | ----------------------------------- |
+| 1     | `h1`    | `text-4xl font-extrabold`, balanced |
+| 2     | `h2`    | `text-3xl font-semibold`            |
+| 3     | `h3`    | `text-2xl font-semibold`            |
+| 4     | `h4`    | `text-xl font-semibold`             |
+
+Every level draws with `tracking-tight`. A [Modal](/engine/ui/modal/) draws its title as a level 2 Heading.
+
+Its props are in [`Heading`](https://wiki.spawnite.com/reference/ui/heading/).
+
+```tsx
+import { Hud, Panel, Slot, Heading, Text } from "@spawnite/engine";
+
+export function Wave({ number }: { number: number }) {
+    return (
+        <Hud>
+            <Panel slot={Slot.Top}>
+                <Heading level={1}>Wave {number}</Heading>
+                <Text>Hold the gate</Text>
+            </Panel>
+        </Hud>
+    );
+}
+```
+
+There is no `size` prop: the level is the default, and a `className` such as `text-2xl` is the override that shows in the diff.