@spawnite/engine 0.1.0-beta.15

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

@@ -0,0 +1,303 @@
+---
+title: Settings
+description: The Escape menu's Settings panel, what each row does, which rows a game shows, and how a game adds its own rows.
+useCases:
+    - settings menu
+    - volume sliders
+    - camera sensitivity setting
+    - field of view slider
+    - add my own setting row
+    - accessibility options
+    - key binding settings
+sidebar:
+    order: 12
+---
+
+The Escape menu has a Settings button between Play and Fullscreen. It opens a panel with a tab for each kind of setting every game shares, and a Game tab for the game's own rows when it has any. The tabs run Video, Audio, Game, Controls, Interface and Accessibility, the order of Counter-Strike 2 and Lyra (video, audio, the game's own, then controls). The panel opens on Video, as Counter-Strike 2 and Lyra do and Fortnite lists first, and within a session it reopens on the tab the player last chose, as Counter-Strike 2 does; a reload opens on Video again. The browser keeps the shared settings across reloads and sessions, and in the player app the player's own settings follow them from game to game, as [Where the settings live](#where-the-settings-live) says. Escape or Back returns to the menu.
+
+[Graphics quality](/engine/ui/graphics-quality/) describes the Video tab's Quality rows and the performance overlay.
+
+A game wires none of it. Each row shows only where it can apply to what the game mounts, so a top-down game with no mouse look never shows Camera sensitivity, and a single-player game never shows the microphone. A game adds its own rows with `<SettingRow>`, on its own tab or on any of the engine's.
+
+## The panel
+
+On a wide screen the tabs run down the left, the rows fill the middle, and a column on the right describes the row under the pointer or the row that holds the focus: its name, what it does, what it costs the device, and an image where the row has one. Before a row is described, the column says what the tab is for. On a narrow screen, such as a phone held upright, the tabs run across the top, and a tapped row opens its description under it.
+
+The keyboard reaches everything. The arrow keys move along the tabs, down the column or across the strip, and wrap at the ends. Each choice, such as the quality preset, is one tab stop, and the arrow keys choose along its options.
+
+A tab whose rows change what is drawn behind the panel is see-through: the world stays in view, lightly dimmed and not blurred, so the player sees each change as she makes it. Video is see-through, for the quality and the field of view, and so is Interface, for the names over other players. Every other tab dims and blurs the world behind it, so its rows read. On a phone the panel covers the game and stays opaque on every tab. Roblox draws its menu over the running game behind a dark translucent layer, Minecraft dims and blurs the world behind its options, and Fortnite and Valorant cover the game with a settings screen that is all but opaque.
+
+Each tab's Reset puts that tab's settings back to their defaults and leaves the other tabs as they are. Reset all puts every setting back on its second press, which it asks for by reading Confirm reset all for four seconds.
+
+The other engines give a game a quality API and leave the menu to it: Unity's quality levels, Unreal's scalability groups, Godot's project settings. Roblox is the one with an engine-owned menu, and a game cannot add to it. This panel takes its layout from the games players praise: an Accessibility tab of its own, as in Cyberpunk 2077 2.1 and Forza Horizon 5; a description and a cost beside each option, as in Call of Duty; and the world in view behind the graphics, as in the Nixxes ports. The Video tab runs its rows as Fortnite, Lyra and Minecraft do: a Display group first, with fullscreen, the frame rate limit, the field of view and the performance overlay, then a Quality group headed by the preset, with each feature's row under it and Post-processing last.
+
+## The rows
+
+| Tab           | Group   | Row                       | Range                            | Default      | Shows where                                                                                                                              |
+| ------------- | ------- | ------------------------- | -------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Video         | Display | Fullscreen on Play        | On or off                        | On           | The device has a mouse and the page, or the app around it, can go fullscreen.                                                            |
+| Video         | Display | Frame rate limit          | Off, or a divisor of the rate    | Off          | The screen's rate is known and leaves a cap of 20 or more.                                                                               |
+| Video         | Display | Field of view             | 60° to 120°, or the game's range | The game's   | The camera offers the player's field of view.                                                                                            |
+| Video         | Display | Performance stats         | Off, FPS, Graph, Full            | Off          | Every game.                                                                                                                              |
+| Video         | Quality | Quality preset            | Automatic or a level             | Automatic    | The game has its stores, as every `Game` does.                                                                                           |
+| Video         | Quality | 3D resolution             | 100%, 85%, 70%, 50%              | 100%         | The game has its stores.                                                                                                                 |
+| Video         | Quality | Dynamic 3D resolution     | On or off                        | The device's | The game has its stores.                                                                                                                 |
+| Video         | Quality | A feature's level         | The levels that differ           | The level's  | Its group draws more than one look in what the scene mounts, as [The player's rows](/engine/ui/graphics-quality/#the-players-rows) says. |
+| Video         | Quality | Grass sway                | On or off                        | The level's  | A `World`'s ground stands. It sits after Foliage.                                                                                        |
+| Audio         |         | Master volume             | 0 to 100                         | 100          | Every game.                                                                                                                              |
+| Audio         |         | Music volume              | 0 to 100                         | 60           | Every game.                                                                                                                              |
+| Audio         |         | Effects volume            | 0 to 100                         | 100          | Every game.                                                                                                                              |
+| Audio         |         | Interface volume          | 0 to 100                         | 100          | Every game.                                                                                                                              |
+| Audio         |         | Voice volume              | 0% to 200%                       | 100%         | The room has opened voice.                                                                                                               |
+| Audio         |         | Microphone                | On or off                        | The voice's  | The room has opened voice, or says it runs none, as the development room does.                                                           |
+| Controls      |         | Camera sensitivity        | 0.02 to 4; typed, 0.001 to 100   | 1.00         | The camera turns by the player's look.                                                                                                   |
+| Controls      |         | Invert vertical look      | On or off                        | Off          | The camera turns by the player's look.                                                                                                   |
+| Controls      |         | Lock camera with Shift    | On or off                        | On           | The camera offers Shift's lock, and there is a mouse.                                                                                    |
+| Interface     |         | Show other players' names | On or off                        | On           | The scene's `<CharacterSpawn>` draws [names over other players](/engine/entities/player/#names-over-other-players).                      |
+| Interface     |         | Window layout             | Reset                            |              | The player has moved a [Window](/engine/ui/window/).                                                                                     |
+| Accessibility |         | Reduced motion            | On or off                        | The device's | Every game.                                                                                                                              |
+| Accessibility |         | Screen shake              | 0 to 100                         | 100          | The game mounts a camera that can shake.                                                                                                 |
+
+The feature rows run Anti-aliasing, Shadows, Ambient occlusion, Foliage, Terrain detail and Post-processing. The names are the ones most games use: Quality preset and 3D resolution as Fortnite and Lyra name them, Dynamic 3D resolution as Fortnite does, and Frame rate limit as Fortnite, Lyra, Minecraft Bedrock and Valorant do, where Roblox, Minecraft Java and Counter-Strike 2 say maximum.
+
+A tab with no row to show does not show. The Audio tab ends with People: a row for each other player in the room, by name, whatever the room's voice. Once the room opens voice, each row says whether that player is speaking, in voice, muted by you or not in voice, and a player this page hears gets a volume and a mute there, as Roblox's player list and Discord's user menu offer each person's volume. In the development room, which runs no voice, the Microphone row shows alone and says that voice runs when the game plays on the platform. Once a room opens voice, the Audio tab also shows the voice rows under Microphone: the voice mode, open mic or push to talk, with the push-to-talk key on a device with a keyboard, the microphone's volume, noise suppression, automatic gain, and a volume and a mute for each other player. [Voice](/engine/audio/voice/) describes them.
+
+What each row changes:
+
+- **Quality preset:** every value a level sets, as [Graphics quality](/engine/ui/graphics-quality/) sets out. Under Automatic the row says the level the engine picked and the kind of device it read, such as "Automatic chose High for a recent graphics card".
+- **3D resolution:** how sharp the world is drawn, as a share of the level's pixel ratio. Lower looks softer and runs at a higher frame rate; menus and the HUD stay sharp.
+- **Dynamic 3D resolution:** whether the world softens for a moment when the frame rate drops, and sharpens again once it recovers, as [Dynamic resolution](/engine/ui/graphics-quality/#dynamic-resolution) describes. Menus and the HUD stay sharp.
+- **The feature rows:** the level each feature draws at, apart from the preset, which then reads Custom.
+- **Frame rate limit:** the most frames a second the game draws, as [Frame rate limit](/engine/ui/graphics-quality/#frame-rate-limit) describes.
+- **Grass sway:** whether the grass moves in the wind. Until the player sets it, it follows the quality level, on at Medium and High and off at Low, and off under Reduced motion. Off skips the wind's work in the blades' shader.
+- **Field of view:** the degrees the camera sees across a 16:9 screen, over the game's figure.
+- **Fullscreen on Play:** whether the click on Play also fills the screen.
+- **Performance stats:** how much of [the performance overlay](/engine/ui/graphics-quality/#the-performance-overlay) shows.
+- **Show other players' names:** whether the plate with each other player's name shows over their head.
+- **Window layout:** Reset puts every [Window](/engine/ui/window/) the player moved back in its slot.
+- **The volumes:** every sound, music and ambience, every other sound, menu and HUD sounds, and the other players' voices, each under the master.
+- **Microphone:** whether the room takes the player's microphone.
+- **Camera sensitivity:** the camera's look speed and drag speed, as a multiplier on the game's own.
+- **Invert vertical look:** moving the mouse up looks down.
+- **Lock camera with Shift:** whether Shift turns the camera's lock on and off, in a game whose camera has the toggle.
+- **Reduced motion:** whether the interface animates less, and whether the camera shakes at all.
+- **Screen shake:** how much a game's big moments shake the screen, from none at 0 to the game's own at 100.
+
+Reset audio puts the voice rows back and leaves the Microphone row alone, since a reset that turns a microphone on is a surprise. Reset video puts the quality preset back to Automatic, unpins every feature row, puts the 3D resolution back to 100% and dynamic 3D resolution back to its default, Grass sway back to the level's, the field of view back to the game's figure, and Fullscreen on Play, the frame rate limit and Performance stats back to theirs. The Microphone row writes the voice store's mute, which is the player's own and follows her from game to game with the other carried settings.
+
+## Rows that hide themselves
+
+The panel reads what the game mounts, and follows the camera while it is open, so a scene that swaps its camera swaps the camera rows:
+
+- **The camera.** The engine's `Camera` says on its entity which of the player's settings reach it. Its look follows Camera sensitivity and Invert vertical look, and its preset says whether it offers Shift's lock. A game's own rig built on `useCamera` says the same through `tuning`: `playerLook: true` where it reads the two look settings, and `lockToggleOffered` where Shift toggles its lock. The field of view shows where the camera offers the player's figure, and Screen shake where a camera stands that a shake moves.
+- **The device.** The Shift lock and Fullscreen on Play need a mouse to capture, so a phone never shows them. iPhone Safari has no fullscreen for a page.
+- **Voice.** The voice rows show once the room opens voice, so a single-player game, or a room run without voice, never shows them.
+- **Other players.** People shows while the room holds another player, and Show other players' names while the scene's `<CharacterSpawn>` draws their names.
+- **Windows.** Window layout shows once the player has moved a window.
+
+A camera that keeps its own lens, such as the chase, track, side and fly cameras, shows no Field of view row. A game that offers the setting and then fixes the figure, with `fixedFieldOfView`, shows the row greyed out at its figure, and its description says the game sets its own.
+
+A game hides one of the engine's rows by its key with `<HideSetting>`, for as long as it is mounted. The key is the shared setting the row writes, such as `cameraShake` or `fieldOfView`, `quality`, `renderScale`, `dynamicResolution`, a feature group such as `shadows`, `microphone` for the voice chat rows and the voice volume, which come and go together, `people` for the People section, or `windowLayout` for the Window layout row; the type lists every key that names a row. The `microphone` key leaves the engine's microphone button in the top-left corner, the one place every player mutes; a game removes that only by turning voice off, as [Voice](/engine/audio/voice/#the-microphone-button) describes. Hiding a row leaves its setting as it is and still applied: a game that wants one field of view says so on its camera with `fixedFieldOfView`.
+
+```tsx
+import { HideSetting } from "@spawnite/engine";
+
+export function PuzzleRoom() {
+    // The puzzle never shakes the camera, so the row would do nothing.
+    return <HideSetting setting="cameraShake" />;
+}
+```
+
+## Camera sensitivity
+
+The player sees and types a multiplier on the game's own look speed, as Roblox's sensitivity box and every PC shooter show theirs: 1.00 is the game's speed and 2.00 turns twice as fast. In the shooter camera, 1.00 turns half a degree per mouse count, Roblox's speed.
+
+The slider is logarithmic. Each step turns about 6% faster, so twelve steps double the speed. It runs from 0.02 to 4, which in the shooter camera is 0.01 to 2 degrees per count. The low end sits well below the defaults of the popular shooters: CS2 at 0.055 degrees per count, Valorant at 0.07, Overwatch at 0.1 and Apex at 0.11. The field beside the slider takes any value from 0.001 to 100, the range of Roblox's box, and a value past the slider's ends pins the slider there. Enter, or leaving the field, keeps the typed value; text that is not a number keeps the old one.
+
+The store keeps the multiplier, so a sensitivity saved before the slider changed keeps its speed.
+
+The engine asks the browser for raw mouse input when it captures the cursor, so the system's pointer acceleration never bends the aim. A browser without raw input gets a plain pointer lock.
+
+## Field of view
+
+The row shows the degrees the camera sees across a 16:9 screen, as Overwatch and Call of Duty measure theirs, and the engine converts them to three.js's degrees top to bottom. It runs from 60 to 120, Call of Duty's range, or the narrower range the game's camera sets. Until the player moves it, it shows the game's own figure: 102 in the shooter camera, 80 in the others. Reset video clears it back to the game's figure. A wider screen keeps the height a 16:9 screen sees and shows more at the sides: at 90, a 21:9 screen sees 105 across. A screen held upright keeps that angle across its short side, so its long side sees the figure: 90 top to bottom on a 9:16 phone. The row's description says both.
+
+[The camera's page](/engine/entities/camera/#field-of-view) says how a game sets its figure, its range and a fixed lens.
+
+A value saved before the row showed degrees across reads as degrees across, so a player who set one may want to set it again.
+
+## Volume
+
+Each volume slider runs 0 to 100 and is heard in decibels: every point is half a decibel, so every 20 points under 100 is 10 dB quieter, about half as loud to the ear, and 0 is silent. Equal steps of the slider sound like equal steps. The master's decibels and the channel's add, so master 80 with effects 80 plays effects 20 dB down.
+
+The voice volume runs to 200%. Past 100%, the slider adds up to 6 dB, so 200% plays every voice at about twice its amplitude. Roblox's voice volume runs to twice as well, and Discord's per-user slider has the same two ranges: 50 dB under 100%, and a 6 dB boost over it. A limiter on the voices keeps a boosted voice from clipping.
+
+### Default volumes
+
+Master, effects, interface and voice start at 100, the game's own mix, as Fortnite and Minecraft Java start theirs. Music starts at 60, 20 dB under the effects: CS2 plays its music 16 to 28 dB under its effects, and Minecraft Bedrock lowered its music to 30% in 2025. The following table lists where the top games start:
+
+| Volume    | Here | Fortnite | Minecraft Java | Minecraft Bedrock | Roblox                   |
+| --------- | ---- | -------- | -------------- | ----------------- | ------------------------ |
+| Master    | 100  | none     | 100%           | 50%               | one slider, 0 to 10      |
+| Music     | 60   | 100%     | 100%           | 30%               | part of the master       |
+| Effects   | 100  | 100%     | 100%           | 100%              | part of the master       |
+| Interface | 100  | none     | 100%           | 100%              | part of the master       |
+| Voice     | 100% | 100%     | none           | none              | 0 to 2, and 1 per player |
+
+Fortnite's figures come from the settings defaults in its 2019 client, and its current defaults are not published. Roblox's come from its client scripts.
+
+### A game's own mix
+
+A game that wants the sliders to start elsewhere says so on `Game` with `defaultVolumes`. It names each volume by its setting, and each value is the slider's position:
+
+```tsx
+import { Game, Scene, Sound, VolumeChannel } from "@spawnite/engine";
+
+function Night() {
+    return <Sound url="/night.mp3" loop channel={VolumeChannel.Music} />;
+}
+
+export function App() {
+    // The file is mixed under the effects already, so music starts at full.
+    return (
+        <Game name="night" start="night" defaultVolumes={{ musicVolume: 100 }}>
+            <Scene name="night" component={Night} />
+        </Game>
+    );
+}
+```
+
+A player starts at those volumes until they move a slider, and Reset audio puts the volumes back there. A volume the player saved on this device keeps its value.
+
+`defaultVoiceMode` beside it starts players on a voice mode in the same way, such as `defaultVoiceMode={VoiceMode.PushToTalk}` for a competitive game. Open mic is the default everywhere else.
+
+## On a touch screen
+
+A phone has no Escape key and no pointer lock to let go, so on a device whose main pointer is a finger the engine shows a menu button in the top-left corner. It stands first in that corner's row, with the [microphone button](/engine/audio/voice/#the-microphone-button) beside it in a game with voice and the performance overlay under them, and opens the same menu Escape does. Roblox keeps its menu button in the same corner. No game's HUD uses the top-left slot, and a Panel a game stands there stacks under the row rather than covering it. The row draws above the other slots, so a game's panel that runs past its own slot on a narrow screen never covers the buttons.
+
+## Menu colours
+
+The menus and the overlay draw with ui's menu tokens, listed on [the theme page](/engine/ui/theme/). A game sets them on `:root` in its own stylesheet, as Holdfast does, so its Escape menu matches its HUD. A game's HUD can stand its own panels on the same colours through the engine's `menuPane`, the translucent pane on the menu's surface colour, which the performance overlay also uses.
+
+## Adding a game's rows
+
+Mount a `<SettingRow>` anywhere in the game. It shows for as long as it is mounted, on the Game tab unless it names another. The game keeps the value, and saves it where it likes; the panel calls `onChange` with each new value.
+
+```tsx
+import { useState } from "react";
+import { SettingKind, SettingRow } from "@spawnite/engine";
+
+export function CrosshairSetting() {
+    const [size, setSize] = useState(1);
+
+    return (
+        <SettingRow
+            kind={SettingKind.Slider}
+            label="Crosshair size"
+            description="How large the crosshair draws."
+            min={0.5}
+            max={2}
+            step={0.1}
+            value={size}
+            defaultValue={1}
+            onChange={setSize}
+        />
+    );
+}
+```
+
+A row is one of four kinds:
+
+- `SettingKind.Slider`: a number between `min` and `max`, moved by `step`.
+- `SettingKind.Toggle`: on or off.
+- `SettingKind.Choice`: one of `options`, each shown as its own name.
+- `SettingKind.Button`: a button that says `action` and calls `onPress`, for something a player does rather than sets, such as replaying the tutorial.
+
+Every row takes the following, each optional:
+
+- `description`: what the row does, in a sentence or two. The panel shows it beside the rows, or under a tapped row on a narrow screen.
+- `tab`: the tab it shows on, such as `SettingsTab.Accessibility` for a subtitles switch. The Game tab unless it says otherwise.
+- `section`: a heading the row stands under within its tab. Rows that name the same section stand together, in the order the first of them mounted, after the rows that name none. On one of the engine's tabs, a game's rows follow the engine's.
+- `cost`: what the row costs to turn up, as `{ gpu: CostLevel.High }`, shown beside its description as Call of Duty marks each option's impact.
+- `image`: the address of an image the panel shows beside the description, such as what each option looks like.
+- `defaultValue`, on a slider, a switch or a choice: the value the tab's Reset and Reset all hand back to `onChange`. A row with none keeps its value on a reset, and a tab whose rows have none shows no Reset.
+
+```tsx
+import { useState } from "react";
+import {
+    CostLevel,
+    SettingKind,
+    SettingRow,
+    SettingsTab,
+} from "@spawnite/engine";
+
+export function GrassSetting() {
+    const [grass, setGrass] = useState("Near");
+
+    return (
+        <SettingRow
+            kind={SettingKind.Choice}
+            tab={SettingsTab.Video}
+            section="Effects"
+            label="Grass"
+            description="How much grass draws near you."
+            cost={{ gpu: CostLevel.Medium }}
+            options={["Off", "Near", "Far"]}
+            value={grass}
+            defaultValue="Near"
+            onChange={setGrass}
+        />
+    );
+}
+```
+
+Epic's Lyra sample builds its settings screen from the same parts: a value with a default and a reset, a collection that groups settings under a heading, an action that is a button, and an edit condition that hides a setting where it cannot apply. Lyra registers each setting as an object in a registry; here a row is an element the game mounts, so a row that applies only in one scene is mounted in that scene, and unmounting it hides it.
+
+## Reading a setting
+
+`useSettings` is a zustand hook over the shared settings. A component reads one setting with a selector, and code outside React reads them all with `useSettings.getState()`:
+
+```tsx
+import { useSettings } from "@spawnite/engine";
+
+const inverted = useSettings((settings) => settings.invertLook);
+```
+
+A game's own sounds follow the volumes through `followVolume`, which sets a Web Audio gain from the master volume and one channel's volume, each through the decibel curve above, now and on every change. `convertVolumeToGain` turns one slider position into its gain.
+
+```ts
+import { followVolume, VolumeChannel } from "@spawnite/engine";
+
+const effects = context.createGain();
+followVolume(effects, { channel: VolumeChannel.Effects });
+```
+
+The engine's own `<Sound>` takes a `channel` prop: effects unless it names music, interface or voice. A sound the player hears from a menu or the HUD, such as a click or a card turning, plays on `VolumeChannel.Interface`.
+
+## Where the settings live
+
+Some settings are the player's own: her ears, her microphone, her hands and her comfort are the same in every game. The rest are the game's: its mix and its camera. In the player app, the player's own settings are carried: she sets them once and every game on the device reads them. The game's settings stay with each game. The following table sorts every setting:
+
+| Setting                                                          | Kept                  | Why                                                                           |
+| ---------------------------------------------------------------- | --------------------- | ----------------------------------------------------------------------------- |
+| Master volume                                                    | Carried, across games | How loud her device plays, whatever the game.                                 |
+| Voice volume                                                     | Carried, across games | How loud other people are to her.                                             |
+| Voice mode, push-to-talk key, open mic's threshold               | Carried, across games | How her microphone sends.                                                     |
+| Microphone volume, noise suppression, automatic gain             | Carried, across games | Her microphone, the same device in every game.                                |
+| Microphone mute                                                  | Carried, across games | Whether she speaks at all.                                                    |
+| Camera sensitivity, invert vertical look, lock camera with Shift | Carried, across games | Her hands: a multiplier on each game's own speed.                             |
+| Reduced motion, screen shake                                     | Carried, across games | Her comfort, which no game should undo.                                       |
+| Fullscreen on Play, performance stats, frame rate cap            | Carried, across games | How she likes the screen, and her device's battery and heat.                  |
+| Show other players' names                                        | Carried, across games | Whether she wants names over heads, in every game that draws them.            |
+| Music volume, effects volume, interface volume                   | Per game              | Each game mixes its own sound.                                                |
+| Field of view                                                    | Per game              | Degrees suit one camera and not the next, and a game can narrow the range.    |
+| Graphics quality and its rows, grass sway                        | Per game              | One game's scene costs more to draw than another's.                           |
+| Keep a replay                                                    | Per game              | Only a development build keeps a replay, and none runs in the app.            |
+| A game's own rows                                                | Per game              | The game's.                                                                   |
+| Each other player's volume and mute                              | For the room only     | A player's key names them in one room, and each game knows her by another id. |
+
+A carried setting the player never touched stays at the game's default, so a game's `defaultVolumes` and `defaultVoiceMode` still set where she starts. Once she moves a carried setting, every game on the device reads her value, and a tab's Reset hands it back to each game's default. Roblox keeps its client settings the same way, on the device and across every experience.
+
+The app keeps the carried settings in its own storage on `spawnite.com` and hands them to the game's page over [the channel](https://wiki.spawnite.com/platform/trust-boundary/#what-a-game-and-the-app-say-to-each-other) as the page opens. The page sends each change back, and keeps only the game's settings in its own storage. A game open in another tab of the app takes the change too. The settings are per device, so a desktop and a laptop with different microphones each keep their own. An account that carries them across devices is a later step.
+
+The page keeps every setting in its own local storage under `spawnite.settings`, and her mute under `voice`, wherever no app carries them: on a game's dev server, under `spawnite play`, or in an app from before carried settings. Each published game runs at an origin of its own, as [the trust boundary](https://wiki.spawnite.com/platform/trust-boundary/#where-a-game-runs) sets it, and local storage belongs to one origin, so outside the app each game keeps its own. On a development machine each game's dev server has its own port, and so its own origin too.

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

@@ -0,0 +1,33 @@
+---
+title: Tap
+description: A thumb-sized action button that fires on the press.
+useCases:
+    - jump button on a phone
+    - attack button for touch
+    - mobile action button
+    - thumb sized button
+    - touch button for sprint
+    - interact button on mobile
+sidebar:
+    order: 10
+---
+
+`<Tap onTap>` is the action button beside the [Joystick](/engine/ui/joystick/): jump, attack, interact. It fires on the press, not on the release, because an action is timed against the world and a release lands late. `onRelease` runs once as the finger lifts, slides off or the browser takes the touch, for a control held down, such as a sprint; `<InputButtons />` draws one per binding that declares `touch`. At 72 pixels it is wider than [Button](/engine/ui/button/)'s 56, since a thumb finds it by feel.
+
+Its props are in [`Tap`](https://wiki.spawnite.com/reference/ui/tap/). It stands in the screen's bottom-right slot, beside the stick's corner, for a coarse pointer only; `slot` moves it.
+
+A keyboard or a screen reader activates it too, and fires it once.
+
+```tsx
+import { Hud, Icon, Tap } from "@spawnite/engine";
+
+export function JumpButton({ onJump }: { onJump: () => void }) {
+    return (
+        <Hud>
+            <Tap label="Jump" onTap={onJump}>
+                <Icon name="arrow-big-up" className="size-8" />
+            </Tap>
+        </Hud>
+    );
+}
+```

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

@@ -0,0 +1,56 @@
+---
+title: Text
+description: Words drawn straight onto the game, readable over any scene.
+useCases:
+    - text over the game
+    - hud text
+    - label above an enemy
+    - readable text on any background
+    - text with a colour from data
+    - tooltip on text
+    - score text
+sidebar:
+    order: 4
+---
+
+`<Text>` draws words over the world in white with a thin dark edge, so they read over a bright sky and over night ground alike.
+
+Its props are in [`Text`](https://wiki.spawnite.com/reference/ui/text/).
+
+`style` takes a colour or a place that comes from data, such as an item's rarity colour; a look that is the same every time is a class.
+
+`title` is what the browser shows in a tooltip while the pointer rests on the words, such as what a stat does, as Godot's `tooltip_text` is on every Control. A phone shows none, so a hint a player needs there belongs in the words themselves.
+
+```tsx
+import { Hud, Panel, Slot, Text } from "@spawnite/engine";
+
+export function Score({ coins }: { coins: number }) {
+    return (
+        <Hud>
+            <Panel slot={Slot.TopRight}>
+                <Text size="lg">Coins {coins}</Text>
+            </Panel>
+        </Hud>
+    );
+}
+```
+
+Over an entity, a Text goes in an [anchored Panel](/engine/ui/panel/#anchored), bare so the words stand on the world with no pane behind them:
+
+```tsx
+import { Anchor, Entity, Panel, PanelVariant, Text } from "@spawnite/engine";
+
+export function Signpost() {
+    return (
+        <Entity model="signpost">
+            <Panel anchor={Anchor.Above} variant={PanelVariant.Bare}>
+                <Text className="font-bold">To the well</Text>
+            </Panel>
+        </Entity>
+    );
+}
+```
+
+The game's canvas gives the same white and dark edge to everything drawn over the world, so a label with no colour of its own reads like a Text rather than in the page's black, as Godot's `Label3D` defaults to white with an outline. A pane over the world that should not carry the edge, such as a card with dark words, sets `[text-shadow:none]`.
+
+Nothing in Text animates: a number that changes every frame should not move as well. Pass `tabular` for a number that counts, so every digit draws the same width and the text beside it stays still. With a minimum width on the Text too, the pane around it keeps its size when the number gains a digit.

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

@@ -0,0 +1,119 @@
+---
+title: Theme
+description: The tokens a game sets to restyle every primitive at once.
+useCases:
+    - restyle all the ui
+    - change the menu colors
+    - dark or light theme
+    - change the accent color
+    - custom look for my ui
+    - shipped ui themes
+    - style a button's parts
+    - design tokens for my game
+sidebar:
+    order: 11
+---
+
+The primitives draw from a set of CSS variables, the theme tokens, in `@spawnite/ui`'s stylesheet. A game restyles them by setting the variables on `:root` in its own stylesheet, and every primitive that reads a token follows: the panes, the menus, the loading screen, a health bar, an accent [Button](/engine/ui/button/). A game sets a token once, not a colour on each element. A game that wants a look without choosing tokens imports one of [the shipped themes](#themes), and one that wants more than a token can give restyles [a primitive's parts](#parts).
+
+Unity's UI Toolkit and Godot both theme controls through named variables that every control reads, rather than a game restyling each control's inner parts. The engine matches them, and lists the variables here, because an agent reads this page where a person opens an inspector.
+
+Set a token in the game's `src/styles.css`, after the import of ui's stylesheet:
+
+```css
+@import "@spawnite/ui/styles.css";
+
+:root {
+    --color-menu-accent: var(--color-amber-300);
+    --color-menu-accent-ink: var(--color-neutral-950);
+    --font-display: "Bricolage Grotesque", var(--font-sans);
+}
+```
+
+Not in `@theme`: a game's stylesheet is not a Tailwind root, so an `@theme` block there reaches the browser unread. Each token is also a Tailwind colour, so `bg-menu-accent` and `text-danger` are classes a game's own elements can wear, and they follow the override too.
+
+## Themes
+
+Two themes ship in `@spawnite/ui/themes/`. Each is a stylesheet that sets every token on `:root`, so one import after ui's stylesheet restyles every primitive, and a token set after the import goes past the theme:
+
+| Theme | Look                                                                                     | Import                                              |
+| ----- | ---------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| Glass | The default: translucent white panes over the world, white ink, an emerald bar.          | none, or `@import "@spawnite/ui/themes/glass.css";` |
+| Slate | Opaque dark slabs with a hairline edge, pale ink, a green accent, no blur: Depthfield's. | `@import "@spawnite/ui/themes/slate.css";`          |
+
+`spawnite create --theme slate` writes the import into a new game's `src/styles.css`, and the MCP's `new_game` takes the same `theme`. In Storybook, the Theme toolbar switches every story between the two. Godot ships one default theme and a game loads its own `.tres`; Unity's UI Toolkit ships a default and a runtime theme file per project. The engine ships two, the glass over the world and the slab, because they differ in kind where a third would differ in colour, and a game's colours are its own tokens. Holdfast imports glass and sets every token after it in its `src/ember.css`, which [spawnite/examples](https://github.com/spawnite/examples) holds, the example of a theme carried into a game's own look.
+
+## The tokens
+
+Each token, what reads it, and its default:
+
+| Token                        | Read by                                                                                      | Default                  |
+| ---------------------------- | -------------------------------------------------------------------------------------------- | ------------------------ |
+| `--color-pane-surface`       | The glass of a Panel, a glass Button, a Tap and a Modal's pane                               | `rgb(255 255 255 / 12%)` |
+| `--color-pane-sheen`         | The top of the glass's sheen, a gradient down the pane                                       | `rgb(255 255 255 / 25%)` |
+| `--color-pane-sheen-end`     | The bottom of the sheen                                                                      | `rgb(255 255 255 / 5%)`  |
+| `--color-pane-edge`          | The glass's edge, its inset highlight and its border                                         | `rgb(255 255 255 / 90%)` |
+| `--color-pane-ink`           | Text on the glass, and the focus ring of a glass control                                     | white                    |
+| `--color-pane-shadow`        | The shadow under a pane                                                                      | `rgb(0 0 0 / 25%)`       |
+| `--radius-pane`              | The corner of a Panel and a Modal's pane, the `rounded-pane` class                           | `1.25rem`                |
+| `--radius-control`           | The corner of a Button, the `rounded-control` class                                          | `1.25rem`                |
+| `--blur-pane`                | How far the world blurs behind the glass, the `backdrop-blur-pane` class; `0px` for a slab   | `16px`                   |
+| `--color-menu-surface`       | The pane of the Escape menu, the performance overlay, a pane Button and `menuPane`           | `rgb(12 14 20 / 88%)`    |
+| `--color-menu-raised`        | A control at rest in a menu                                                                  | `rgb(255 255 255 / 7%)`  |
+| `--color-menu-edge`          | The hairline edge of a menu pane and a pane Button                                           | `rgb(255 255 255 / 14%)` |
+| `--color-menu-muted`         | Secondary text in a menu, the muted microphone                                               | `rgb(255 255 255 / 58%)` |
+| `--color-menu-accent`        | What is on, chosen or focused in a menu; the fill of an accent Button; a menu slider's track | white                    |
+| `--color-menu-accent-ink`    | Text on the accent                                                                           | `neutral-950`            |
+| `--color-menu-ink`           | The text a NumberField, a TextField or a Select holds                                        | white                    |
+| `--radius-field`             | The corner of a NumberField, a TextField or a Select                                         | `0.375rem`               |
+| `--text-field`               | The size of the text a NumberField, a TextField or a Select holds                            | `15px`                   |
+| `--color-health-fill`        | A Bar's fill, unless the Bar names a `color`                                                 | `emerald-400`            |
+| `--color-health-track`       | A Bar's track                                                                                | `emerald-950`            |
+| `--color-health-loss`        | The piece a blow just took, flashed before it drains                                         | white                    |
+| `--color-danger`             | A readout past a limit, `palette.dangerText`                                                 | `red-400`                |
+| `--color-loading-background` | The loading screen's field, a LoadingRing's, the Made with notice's                          | `neutral-950`            |
+| `--color-loading-label`      | The loading screen's muted words                                                             | `neutral-400`            |
+| `--color-loading-indicator`  | The loading screen's marks                                                                   | `neutral-200`            |
+| `--color-loading-bar`        | The loading bar's fill                                                                       | `neutral-200`            |
+| `--color-loading-track`      | The loading bar's track                                                                      | `rgb(255 255 255 / 14%)` |
+| `--color-loading-text`       | The loading screen's text                                                                    | `neutral-100`            |
+| `--color-stick-ring`         | The Joystick's ring                                                                          | `rgb(255 255 255 / 70%)` |
+| `--color-stick-knob`         | The Joystick's knob                                                                          | `rgb(255 255 255 / 90%)` |
+| `--color-reading-good`       | A performance reading within budget                                                          | `emerald-400`            |
+| `--color-reading-warn`       | A reading near the budget                                                                    | `amber-400`              |
+| `--color-reading-bad`        | A reading past it                                                                            | `red-400`                |
+| `--color-voice-speaking`     | The microphone's level while the room hears the player                                       | `emerald-400`            |
+| `--color-voice-muted`        | The slash across a muted microphone                                                          | `red-500`                |
+| `--font-display`             | Titles and big numbers: a Heading, a LevelBanner, the `font-display` class                   | `var(--font-sans)`       |
+
+A Tailwind name in the Default column, such as `emerald-400`, is that colour from Tailwind's palette, `var(--color-emerald-400)`.
+
+A game's own elements take a token through the class that names it, `border-pane-edge` or `text-menu-accent`, rather than a palette class such as `text-amber-200`, so one change in `styles.css` restyles the HUD and the menus together.
+
+## Parts
+
+A token restyles every primitive at once. For one primitive that should look different from the rest, each primitive with more than one visible part takes `classNames`, a map from a part's name to the classes it wears, beside the `className` that goes on its root. Each part's classes merge over the primitive's own, so `classNames={{ value: "text-amber-300" }}` recolours a Counter's number and leaves its icon. Mantine and CharacterUI name their parts the same way, and an agent that has styled either knows the shape.
+
+| Primitive                      | Parts                                            |
+| ------------------------------ | ------------------------------------------------ |
+| [Button](/engine/ui/button/)   | `root`, `icon`                                   |
+| [Counter](/engine/ui/counter/) | `root`, `icon`, `value`                          |
+| [Bar](/engine/ui/bar/)         | `root`, `track`, `fill`, `reserved`, `value`     |
+| [Modal](/engine/ui/modal/)     | `dialog`, `pane`, `title`, `overline`, `actions` |
+
+```tsx
+import { Counter } from "@spawnite/engine";
+
+export function Streak({ streak }: { streak: number }) {
+    return (
+        <Counter
+            icon="flame"
+            label="Streak"
+            value={streak}
+            classNames={{ icon: "text-menu-accent", value: "font-display" }}
+        />
+    );
+}
+```
+
+A Panel is one surface, so it takes `className` alone, and a Joystick and a Tap take the engine's tokens and a `className` on the control.

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

@@ -0,0 +1,68 @@
+---
+title: Window
+description: A bag, a character sheet or a shop the player moves, several open at once.
+useCases:
+    - inventory window
+    - character sheet
+    - shop window
+    - draggable window
+    - several windows open at once
+    - bag that the player moves
+    - window that remembers its position
+    - window on a phone
+sidebar:
+    order: 3
+---
+
+`<Window>` is a window over the game that keeps playing behind it, such as a bag, a character sheet or a shop. It opens at the place of the [slot](/engine/ui/panel/) the game names, over whatever Panel stands there, and the player drags it by its title bar to anywhere on the screen. The engine keeps where each window was left on this device, so it opens there next time.
+
+Its props are in [`WindowProps`](https://wiki.spawnite.com/reference/ui/windowprops/).
+
+```tsx
+import { useState } from "react";
+import { Button, Slot, Text, Window } from "@spawnite/engine";
+
+export function BagButton() {
+    const [open, setOpen] = useState(false);
+
+    return (
+        <>
+            <Button onPress={() => setOpen(!open)}>Bag</Button>
+            <Window
+                id="bag"
+                title="Bag"
+                open={open}
+                onClose={() => setOpen(false)}
+                slot={Slot.Left}
+                className="w-72"
+            >
+                <Text>Three red potions and a rusty key.</Text>
+            </Window>
+        </>
+    );
+}
+```
+
+The window draws its title and a close button in a title bar, on the menus' solid pane, darker than a HUD Panel's glass, so its rows read over a bright scene with nothing dimmed behind it. Its children are only what it holds, and `className` restyles the pane. Import `Window` from the engine in every file that draws one: without the import, TypeScript reads the name as the browser's own `Window` type and reports that it cannot be used as a JSX component.
+
+## Moving and keeping
+
+The player drags a window by its title bar. On release, the engine keeps its place under the window's `id`, in the browser's storage under the game's name, beside the camera and the quality level. A layout belongs to the screen it was made on, so a phone and a laptop each keep their own. A window stays wholly on the screen: a drag past an edge stops at it, and when the browser window shrinks, a window moves back in, as World of Warcraft keeps its frames on screen. A window larger than the screen keeps its top left corner on it.
+
+`slot` is the creator's starting place, `Slot.Center` by default: against the slot's edges, 12 pixels in, or centred on the axis the slot centres. A window stands free of the slot grid, so every open window stands in one order, front to back. `movable={false}` keeps a window in its slot, for one whose place is part of the game's layout.
+
+The engine's settings show a Window layout row on the Interface tab once the player has moved a window. Its Reset puts every window back in its slot. A game hides the row with `<HideSetting setting="windowLayout" />`.
+
+## Several at once
+
+Several windows open at once. A press anywhere on a window brings it to the front, and Escape closes the window in front, then the one behind it, before it opens the engine's menu, as World of Warcraft's Escape does.
+
+## On a phone
+
+On a touch screen, a window shows alone in the middle of the screen over a dimmed backdrop, because a phone's screen fits one. Opening a second window closes the first through its `onClose`, and a press on the dimmed backdrop closes the window. While something is dragged out of the window, such as a potion toward the hotbar, the window fades and lets the pointer through, so the target beneath shows.
+
+## What other engines do
+
+Godot's `Window` node is the closest: an embedded window that the player moves by its title bar. Roblox puts a `UIDragDetector` on a Frame. Unity's UGUI and Unreal's UMG have no window the player moves, so each game writes its own drag handler. None of them keeps the place for the player. World of Warcraft and Final Fantasy XIV let the player move every window and keep the layout, and the engine does the same per device.
+
+Cost per frame: none. A moving window renders once for each pointer move.

package/dist/wmIDrLkF.js

@@ -0,0 +1 @@
+import{Ds as e,L as t,M as n,co as r,qi as i}from"./-MLBVTaO.js";import{Ht as a,fn as o,or as s}from"./V70ADx0g.js";import{n as c}from"./BrfUaL46.js";import{isLinkDirect as l}from"@spawnite/schema";var u=/\[([^\]=]+)(?:=([^\]]*))?\]/y;function d(e){throw c(/* @__PURE__ */ Error(`"${e}" is no selector: write [trait] or [trait.field=value], one group or several, as [monster.kind=colossus]`),`SP0225`,void 0)}function f(e){try{return JSON.stringify(JSON.parse(e))}catch{return JSON.stringify(e)}}function p(e){let t=e.trim(),n=[];for(u.lastIndex=0;u.lastIndex<t.length;){let r=u.exec(t);r||d(e);let i=r[1].trim().split(`.`);i.some(e=>e===``)&&d(e),n.push({path:i,...r[2]!==void 0&&{value:f(r[2].trim())}})}return n.length===0&&d(e),n}function m(e,t){if(t.length===0)return e;if(o(e))for(let n=t.length;n>0;n--){let r=t.slice(0,n).join(`.`);if(!Object.hasOwn(e,r))continue;let i=m(e[r],t.slice(n));if(i!==void 0)return i}}function h(e,t){let n=p(t);return Object.keys(e).filter(t=>n.every(({path:n,value:r})=>{let i=m(e[t],n);return i===void 0?!1:r===void 0||JSON.stringify(i)===r}))}function g(e){return e.trimStart().startsWith(`[`)}function _(e,t){let r=g(t)?h(n(e).entities,t):a(e,t)?[t]:[];if(r.length===0)throw c(/* @__PURE__ */ Error(`No entity answers to "${t}": give its dump key, such as 17, or a selector of what it is, such as [monster.kind=colossus].`),`SP0200`,void 0);return r}function v(e,t,n){let i=n(e),a=i&&r(i);if(a){let t=a.path.reduceRight((e,t)=>e===void 0?t:{[t]:e},void 0);throw c(/* @__PURE__ */ Error(`"${e}" is the tag of the ${a.machine} machine's state ${a.path.join(`.`)}: set the machine's state instead, as ${JSON.stringify({[a.machine]:{state:t}})}.`),`SP0519`,void 0)}if(o(t))for(let[r,i]of Object.entries(t))v(`${e}.${r}`,i,n)}function y(n,r,o,l=t){let u=r.map(e=>{let t=a(n,e);if(!t)throw c(/* @__PURE__ */ Error(`No entity answers to "${e}" in the world: give a dump key spawnite play dump lists, or a selector of what it is, such as [monster.kind=colossus].`),`SP0202`,void 0);return t}),d=Object.entries(o).map(([e,t])=>{let n=l(e);if(!n)throw c(/* @__PURE__ */ Error(`No trait registered as "${e}": name it as spawnite play dump files it, such as transform, or, in a room, as its module exports it, such as SiegeState.`),`SP0203`,void 0);return v(e,t,l),{trait:n,value:t}});for(let t of u){for(let{trait:e,value:n}of d)i(t,e,n,{partial:!0});`transform`in o&&t.has(s)&&e(n,t)}}function b({latencyMilliseconds:e,jitterMilliseconds:t},n){let r=e/2;if(t===0)return r;let i=Math.sqrt(-2*Math.log(Math.max(n(),1e-12)))*Math.cos(2*Math.PI*n());return Math.max(0,r+i*t)}function x({readConditions:e,random:t=Math.random,start:n}){let r=-1/0;return{readArrival:i=>{let a=e(),o=Math.max(r,i+b(a,t)),{stall:s}=a;if(s){let e=s.everySeconds*1e3,t=o-n,r=t%e;t>=e&&r<s.milliseconds&&(o+=s.milliseconds-r)}return r=o,o}}}function S({readConditions:e,random:t,now:n=()=>performance.now()}){let r=x({readConditions:e,random:t,start:n()}),i=[],a,o=!1,s=()=>{a=void 0;let e=n();for(;i.length>0&&i[0].arrival<=e;)i.shift()?.deliver();i.length>0&&c()},c=()=>{a=setTimeout(s,Math.max(0,i[0].arrival-n()))};return{hold:t=>{if(!o){if(i.length===0&&l(e())){t();return}i.push({arrival:r.readArrival(n()),deliver:t}),a===void 0&&c()}},close:()=>{o=!0,clearTimeout(a),a=void 0,i.length=0}}}export{h as a,g as i,_ as n,y as r,S as t};

package/dist/yhuZzG90.js

@@ -0,0 +1 @@
+import{$l as e,Ad as t,Dd as n,Hc as r,Tl as i,Vc as a,eu as o,kd as s,nu as c,ql as l,wl as u}from"./-MLBVTaO.js";import{J as d,tr as f}from"./V70ADx0g.js";import{Quaternion as p}from"three";import{trait as m}from"koota";var h=/*#__PURE__*/ m(()=>({rotation:new p,pitch:0,strafing:!1,easing:!1})),g=new p;function _(p,{input:m,frameSeconds:_}){let v=r(p),y=v?.get(f)?.object;if(!v||!y||!a(v))return;let b=!v.has(h);b&&v.add(h);let x=v.get(h);if(!x)return;b&&x.rotation.copy(y.quaternion);let S=d(p);x.strafing=l(S,m,e.strafe)&&!v.get(c)?.active;let C=(v.get(u)??i).turnRate*_;if(x.strafing){s(x.rotation,t(l(S,m,e.heading),g),C),x.pitch=o(l(S,m,e.pitch)),x.easing=!0,y.quaternion.copy(x.rotation);return}if(x.pitch=0,x.easing){s(x.rotation,y.quaternion,C),x.easing=n(x.rotation,y.quaternion)>0,y.quaternion.copy(x.rotation);return}x.rotation.copy(y.quaternion)}export{_ as n,h as t};