@seriousgaming/sdk-tools 0.0.0-stage → 1.0.0-alpha.1

package/dist/docs/guides/settings.md

@@ -0,0 +1,458 @@
+# Settings
+
+Settings are a game's read-only parameters: a price, a difficulty, a round length, a menu, an answer key. This guide covers declaring them, reading them from logic and surfaces, overriding them per scenario and per session, and setting them from the CLI.
+
+Not to be confused with [global settings](./global-settings.md), the file in your home directory that holds API keys for every project.
+
+## Overview
+
+A settings resource is a schema and nothing else. It lives at `settings/<identifier>/settings.sdk.json`, and a package may hold any number of them, as it does capabilities.
+
+- **Every property declares a default.** The default is the value the game plays with unless a scenario or the session overrides it
+- **Read-only.** No logic, surface or endpoint writes a setting. Values change only through the override layers, and only before play starts
+- **Declared by identifier.** A resource lists the settings it reads in `settings`, exactly as `reads` names capabilities, and receives exactly those
+- **Fixed when play starts.** Settings are resolved when a session is created on the platform, or once the configuration step completes on the dev server, and do not change during play
+
+Settings replace the per-resource `configurationSchema` of earlier versions. If you are upgrading, see [step 2 of the upgrading guide](./upgrading.md#step-2-move-configuration-into-settings-resources).
+
+## Declaring settings
+
+Create a settings resource with the CLI. The JSON names the identifier, which becomes the directory name:
+
+```bash
+pnpm run sdk new settings '{
+  "definition": {
+    "identifier": "demand",
+    "settingsSchema": {
+      "type": "object",
+      "properties": {
+        "BaseDemand": {
+          "type": "number",
+          "description": "Base demand per tick",
+          "default": 100,
+          "minimum": 0
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}'
+```
+
+Run `pnpm run sdk new settings` with no JSON to be prompted for each property instead. Either way it writes `settings/demand/settings.sdk.json`, where the directory names the resource and the file carries no identifier:
+
+```json
+{
+    "definition": {
+        "settingsSchema": {
+            "type": "object",
+            "properties": {
+                "BaseDemand": {
+                    "type": "number",
+                    "description": "Base demand per tick",
+                    "default": 100,
+                    "minimum": 0
+                }
+            },
+            "additionalProperties": false
+        }
+    }
+}
+```
+
+`settingsSchema` is a full JSON Schema Draft 7 object. Two rules are stricter than for a capability's `variablesSchema`:
+
+- Every property needs a `default`. `new settings`, `update settings` and `sdk build` all refuse a property without one
+- Every default must fit its own schema, at any depth. `sdk build` refuses a string default on a number property, a default outside its range or `enum`, and an object default missing a key its own `required` lists, naming the settings resource and the path. The generated `Settings` type comes from the schema, so the compiler cannot catch a default that disagrees with it
+- A top-level `required` is refused, because every property always has a value. For a value that may be absent, use `"type": ["string", "null"]` with `"default": null`
+
+A `required` inside an object-valued property is allowed. It holds the property's `default` to its keys, never a scenario or a setup change: those are partial at every depth, so a scenario or a setup UI may set one key of the object and leave the rest to the layer beneath. An array is the exception: it replaces the one beneath whole, so each item an override supplies must be complete.
+
+### Describe every setting
+
+A settings schema is read by more than the build. A hosted runtime's generic settings form, a [scenario editor](./scenario-editor.md), and an AI agent authoring a scenario for your released game all work from it, and an agent can edit a game with no editor UI at all if the schema says what each value means. Give every property:
+
+- A `title` and a `description` saying what the value is and what changing it does
+- Its units, in the description or title ('in pounds', 'per tick', 'as a fraction of revenue')
+- A range, with `minimum` and `maximum`, wherever one exists
+- An `enum` where the choices are closed
+
+A `title` on a value is safe to write: the generated `types.ts` ignores it, so any wording works, 'Settings' and 'Context' included. Only a `title` on an object names a type there.
+
+```json
+"DemandPriceModifier": {
+    "type": "number",
+    "title": "Price sensitivity",
+    "description": "Units of demand lost for each pound added to the price",
+    "minimum": 0,
+    "maximum": 5000,
+    "default": 500
+}
+```
+
+### Lock a setting
+
+Some values are part of the game's design rather than something to tune: a constant the scoring depends on, or a rule every edition shares. Mark the property `readOnly` and only your default applies:
+
+```json
+"LowProductionThreshold": {
+    "type": "integer",
+    "title": "Low production threshold",
+    "description": "Units per round below which the price rises. Fixed by the game",
+    "default": 80,
+    "readOnly": true
+}
+```
+
+- **Nothing can change a locked value.** The build refuses a scenario that sets it, with `SETTINGS_LOCKED` pointing at the value, even when it sets the same value as your default. A setup screen or scenario editor that changes it is refused as `denied`, with a message naming the setting (`"engine.LowProductionThreshold" is read-only`), and none of that write applies
+- **Sending it back unchanged is fine.** An editor that spreads the settings it was given sends the locked value back as it was, and only what changed is applied, so spreading is still safe
+- **Locking an object locks everything in it.** `readOnly` on an object-valued property fixes every key inside it, at any depth
+- **Saving a scenario leaves locked values out.** The dev console's Save writes every other setting and drops the locked ones, so the scenario still builds
+- **Editors are not sent the schema.** A setup screen or scenario editor receives the values, not the schema, so show a locked field as read-only yourself, as the factory example's scenario editor does
+- **Adding a lock is a scenario-format change.** A custom scenario saved before the lock may hold a value for it, so bump `scenarioFormat` when you lock a setting a released version left open (see [Scenario format: when to bump it](./scenarios.md#scenario-format-when-to-bump-it))
+
+### How to divide settings
+
+Split settings by who reads them rather than keeping one per resource. A package may hold one `engine` settings resource read only by the engine, or several named by topic (`pricing`, `documents`, `answers`) that several resources share. The starter game does both: its `menu` settings, the prices and the stall's capacity, are read by the engine, every surface, a hook and a validator, while each item's usual demand sits in an `engine` resource only the engine reads. Several resources may declare the same settings resource, and each receives the same values, so a surface never needs a copy of a value the engine already has.
+
+## Reading settings
+
+List the settings a resource reads in its bundle's `settings` array. Every resource that runs logic or renders a surface may do so: the engine, `ui`, `session`, `waiting_room`, `presentation`, `tick_controller`, hooks, validators, and endpoints.
+
+```json
+{
+    "definition": {
+        "reads": ["price"],
+        "writes": ["sales"],
+        "settings": ["demand"]
+    },
+    "logic": {
+        "directory": ".",
+        "entrypoint": "logic.ts"
+    },
+    "rootDirectory": "."
+}
+```
+
+Add it by hand, or with `pnpm run sdk update engine --patch '[{"op":"add","path":"/definition/settings","value":["demand"]}]'`. `new engine`, `new ui` and the other interactive `new` commands ask which settings the resource reads. The build fails on an identifier the package does not declare.
+
+Then run `pnpm run generate`. The resource's generated `types.ts` gains a `Settings` type keyed by settings identifier, and its `defaults.ts` a `defaultSettings` holding the defaults, for use in tests.
+
+### In logic
+
+The engine, hooks, validators, the tick controller and endpoints receive `settings` beside `context`, keyed by settings identifier:
+
+```typescript
+import type { RunFunction } from '@seriousgaming/sdk';
+import type { Context, Settings } from './types';
+
+export const Run: RunFunction<Context, Settings> = async ({ context, settings }) => {
+    const { BaseDemand } = settings.demand;
+    return {
+        capabilities: {
+            ...context,
+            sales: { ...context.sales, Sales: BaseDemand - context.price.Price * 2 },
+        },
+    };
+};
+```
+
+A hook reads `settings` the same way (`({ context, settings, participant })`), a validator's `UpdateData` and `RequestTick` receive it beside `actor`, and an endpoint's `Handle` receives it beside `request` and `caller`. A resource that declares no settings receives `{}`.
+
+### In a surface
+
+A game UI, session UI and waiting room UI read `settings` from their data hook:
+
+```tsx
+import { useUserInterfaceData } from '@seriousgaming/sdk/ui';
+import type { Context, Settings } from '../types';
+
+function PricePanel() {
+    const { data, settings } = useUserInterfaceData<Context, Settings>();
+    const { MinPrice, MaxPrice } = settings.ui;
+    // ...
+}
+```
+
+A session UI uses `useSessionUserInterfaceData<SessionData, Settings>()`. The host delivers a surface's settings once on load, in the `setSettings` message, rather than with every context write.
+
+In component tests, pass them to `renderUserInterface` or `renderSessionUserInterface`, keyed the same way:
+
+```tsx
+renderUserInterface(<App />, {
+    data: { price: { Price: 5 } },
+    settings: { ui: { MinPrice: 1, MaxPrice: 500 } },
+});
+```
+
+In unit tests of logic, spread the generated defaults and override only what the case is about:
+
+```typescript
+import { defaultContext, defaultSettings } from './defaults';
+
+const settings: Settings = {
+    ...defaultSettings,
+    demand: { ...defaultSettings.demand, BaseDemand: 500 },
+};
+const { capabilities } = await Run({ context: defaultContext, settings, meta, callbacks });
+```
+
+### Reading settings rather than copying them
+
+Before settings resources, a surface could not see the engine's settings, so games copied it into a capability at `Init`. That copy is per team, stored in every snapshot and re-sent on every write, and it goes stale if the configuration changes. Declare the settings resource on the surface instead, and delete the copy.
+
+Keep a value in a capability only when it changes during play, or when it is computed from settings and several readers need the result.
+
+## The game settings
+
+Every game has one built-in settings resource, `game`, holding the game-level settings: how many ticks (rounds) it plays, how many teams a session may hold, how many participants a team is meant for, what the teams are called to begin with, and whether the waiting room opens with the session. It is a settings resource like any other, with two differences: the SDK owns its schema, and the game sets its values in `seriousgaming.sdk.json` rather than in `settings/game/`.
+
+| Setting                                             | The game's value, in `seriousgaming.sdk.json`       | What it does                                                                    |
+| --------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `maxTicks`                                          | `maxTicks`, or `null` for no fixed limit            | The game is complete once this many ticks have run                              |
+| `teams.min`, `teams.max`                            | `teams.min` and `teams.max`, or `null` for no bound | The fewest teams play can start with, and the most a session can hold           |
+| `teams.perTeam.minParticipants`, `.maxParticipants` | `teams.perTeam`, or `null`                          | Guidance on team size shown to the facilitator, never a limit on joining        |
+| `teams.defaultNames`                                | `teams.defaultNames`, or `[]`                       | The names teams start with, by team index. A facilitator or the team can rename |
+| `waitingRoom.openOnStart`                           | `waitingRoom.openOnStart`, or `false`               | Whether a new session starts with participants held in the waiting room         |
+
+`teams.mode` stays in the manifest and is not a setting: a game is independent or shared-state, and nothing can change that.
+
+Override the game settings as you would any other, under `game`:
+
+- **A scenario** sets them in its `settings`, for example `"settings": { "game": { "maxTicks": 6 } }` for a six-round edition
+- **Setup** sets them for one session when it lists `game` in `configures`. A setup screen asking 'how many rounds today?' writes `updateSettings({ game: { ...settings.game, maxTicks: rounds } })`
+- **`sdk configure`** sets them on the dev server: `pnpm run sdk configure '{"game":{"maxTicks":6}}'`
+- **Any resource can read them** by listing `game` in its `settings`, and its generated `types.ts` types them
+
+Two rules are particular to these settings:
+
+- **`waitingRoom.openOnStart` is set by the game or a scenario, never by setup.** It takes effect as the session is created, before setup runs, so a setup value would do nothing, and is refused
+- **Play cannot start outside the team bounds.** Setup can change `teams.min` and `teams.max` after the teams were created, so play is refused while the team count is outside them. Add or remove teams, or change the setting, and start again
+
+A settings resource of your own may not be called `game`, and is refused with a message saying what to change.
+
+### Narrow or lock the game settings
+
+You own your own settings' schemas, but the SDK owns this one, so you narrow it in `seriousgaming.sdk.json` instead, with `gameSettingsConstraints`. It follows the shape of the `game` settings, and each entry takes only `minimum`, `maximum`, `enum` and `readOnly`:
+
+```json
+{
+    "maxTicks": 8,
+    "teams": { "mode": "independent", "min": 2, "max": 6 },
+    "gameSettingsConstraints": {
+        "maxTicks": { "minimum": 4, "maximum": 10 },
+        "teams": { "max": { "readOnly": true } }
+    }
+}
+```
+
+This game plays four to ten rounds, eight unless a scenario or setup chooses otherwise, and its six-team ceiling is fixed. The build merges the constraints into the `game` settings schema it emits, so a scenario, setup and `sdk configure` are held to them exactly as they are to your own settings' `minimum`, `maximum` and `readOnly`.
+
+- **A constraint can only narrow.** The build refuses, with `GAME_CONSTRAINT_INVALID`, a `minimum` below the SDK's own (every count starts at 1), a `minimum` above its `maximum`, a bound on a value that is not a number, and an `enum` value the setting could never hold. An unknown setting or keyword is refused like any other manifest typo
+- **Your own values must meet them.** A `maxTicks` of 12 with a `maximum` of 10 is refused with `GAME_CONSTRAINT_VIOLATED`, pointing at `maxTicks`
+- **A bound rules out 'no limit'.** With a `minimum` or `maximum`, `null` is no longer allowed, so set the value in the manifest. The generated `types.ts` types it as a number
+- **Adding or tightening a constraint is a scenario-format change**, as adding a lock is
+
+A game is single-team only when it declares `teams.max: 1` and locks it:
+
+```json
+{
+    "teams": { "mode": "independent", "max": 1 },
+    "gameSettingsConstraints": { "teams": { "max": { "readOnly": true } } }
+}
+```
+
+A `teams.max` of 1 that is not locked could be raised by a scenario or setup, so the build treats it as multi-team, as it treats an omitted `max`. That matters for an independent game whose engine writes a shared capability: the build allows it only in a single-team game, and its message says to lock `teams.max` when the value is already 1.
+
+## Keeping a value off participant screens
+
+A resource receives only the settings it declares, so the way to keep a value from participants is to put it in a settings resource that no participant surface declares. An answer key, a hidden target or a scoring rubric goes in its own resource, for example `settings/answers/`, listed only in the engine's `settings`:
+
+```json
+{
+    "definition": {
+        "reads": ["submission"],
+        "writes": ["score"],
+        "settings": ["rules", "answers"]
+    }
+}
+```
+
+The game UI lists `"settings": ["rules"]` and never receives `answers`, not even in its browser's memory. An endpoint that marks a submission can declare `answers` too, since it runs on the server.
+
+## Overriding settings
+
+This is the one place the resolution order is described; other pages link here.
+
+A settings resource's values resolve through three layers, each overriding the one before:
+
+1. **Defaults**, the `default` of each property in its `settingsSchema`
+2. **The active scenario**, from the scenario's `settings`, under the settings identifier. With no scenario chosen, the one marked `default` is active, and with none marked, this layer is empty
+3. **The session**, from the game's setup screen on the platform, or `sdk configure` on the dev server, under the settings identifier
+
+```
+settings defaults → scenario overrides → session overrides (wins)
+```
+
+- **Every layer is partial.** It names only the properties it changes, and every property it leaves out falls through to the layer beneath
+- **Layers merge key by key.** A property a layer names replaces the value beneath it, and within an object-valued setting each key it names replaces that key alone, at any depth, so `{ "game": { "teams": { "max": 4 } } }` keeps the other team settings. An array is a single value, replaced whole
+- **There is no game-level layer.** To change a value for every session, edit its default
+- **Resolution happens before play starts.** The values are fixed for the session, and `Init` already receives them resolved
+- **A resource receives only what it declares.** An override under `engine` reaches every resource that lists `engine` in its `settings`, and no other
+
+A surface shown outside a session, such as a presentation with no session running, reads the first two layers only.
+
+### In a scenario
+
+```json
+{
+    "definition": {
+        "locales": {
+            "en": { "name": "Hard Mode" }
+        },
+        "settings": {
+            "demand": { "BaseDemand": 5000 },
+            "session": { "NoticeboardLabel": "Crisis bulletin" }
+        }
+    },
+    "rootDirectory": "."
+}
+```
+
+See [Scenarios](./scenarios.md) for the rest of a scenario. Because hooks and validators read settings resources too, a scenario can now configure them, which it could not before.
+
+### In setup or the scenario editor
+
+The `setup` and `scenario_editor` slots each list the settings they edit in `configures`, and are seeded with the resolved values of exactly those, keyed by settings identifier:
+
+```json
+{
+    "definition": {
+        "configures": ["engine", "ui"]
+    },
+    "rootDirectory": ".",
+    "ui": {
+        "entrypoint": "index.html"
+    }
+}
+```
+
+What setup changes lands in the session layer; what the scenario editor produces is saved as a scenario. See [Building a setup screen](./setup.md) and [Building a scenario editor](./scenario-editor.md).
+
+### From the CLI
+
+`sdk configure` sets the session layer on the dev server, keyed by settings identifier. The keys below are for a game whose engine reads a settings resource named `engine`, with `BaseDemand` and `CostPerUnit` properties: use your own.
+
+```bash
+cat > config.json <<EOF
+{
+  "engine": {
+    "BaseDemand": 15000,
+    "CostPerUnit": 2
+  }
+}
+EOF
+
+pnpm run sdk configure -f config.json
+pnpm run sdk tick
+```
+
+Or inline:
+
+```bash
+pnpm run sdk configure '{"engine":{"BaseDemand":15000}}'
+```
+
+Each call replaces the previous session overrides rather than adding to them, and restarts the session on the new values, because settings are fixed once play starts. Every property it does not name keeps its default or scenario value.
+
+Options:
+
+- `-f, --file [PATH]`: load the overrides from a JSON file
+- `-w, --working-dir [PATH]`: the package directory (default: the current directory)
+- `-j, --json`: print the result as one JSON document (see [JSON output](../cli-reference.md#json-output))
+
+## Validation
+
+Every override source is validated against the `settingsSchema` of the settings resource it names, scenario overrides and session overrides alike. Neither has to name every property, but both are refused for:
+
+- A key naming no settings resource the package declares
+- A property the schema does not declare, such as a misspelling
+- A value of the wrong type, or outside a `minimum`, `maximum` or `enum`
+- A value the schema locks with `readOnly` (see [Lock a setting](#lock-a-setting))
+
+```
+Error: Settings validation failed:
+Settings "engine": /BaseDemand must be number
+```
+
+```
+Error: Settings validation failed:
+Unknown settings "nope": expected one of engine, session, ui
+```
+
+| Error                                                     | Cause                                                                                        | Fix                                                                  |
+| --------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `must be number`                                          | A number was quoted                                                                          | Write `"BaseDemand": 200`, not `"BaseDemand": "200"`                 |
+| `must be <= X` or `must be >= X`                          | The value is outside the schema's range                                                      | Bring it within range                                                |
+| `must NOT have additional properties`                     | The property is not declared in the `settingsSchema`                                         | Check the property name in `settings/<identifier>/settings.sdk.json` |
+| `Unknown settings "x"`                                    | The override is keyed by something that is not a settings identifier, often an old slot name | Key it by the settings resource's directory name                     |
+| `reads settings "x", which this package does not declare` | A resource's `settings` names a missing resource                                             | Create it with `new settings`, or remove it from `settings`          |
+| `declares no default`                                     | A `settingsSchema` property has no `default`                                                 | Add one                                                              |
+| `is read-only`                                            | The override sets a value the game locks                                                     | Remove it from the override                                          |
+
+At `init` or any other CLI load, an invalid override fails the command. In a running dev server, an edited scenario that no longer validates is rejected, the last good values keep running, and the failure is shown as a dismissible error.
+
+## Where the dev server keeps overrides
+
+```
+.seriousgaming-sdk/
+├── configuration.json          # the session overrides (sparse)
+└── configuration-scenario      # the scenario they were saved under
+```
+
+`configuration.json` holds only what `configure` or the setup screen set, keyed by settings identifier. Defaults and the active scenario's values are resolved beneath it each time rather than baked in, and overrides saved under a different scenario are not reused.
+
+The file is yours. If a settings schema changes so that a saved override no longer validates, `init` names the offending key rather than overwriting it:
+
+```
+Session settings are invalid or incompatible with current schemas:
+Settings "engine": data must NOT have additional properties (unexpected property: "Incrementt")
+
+It is authored content, so correct it in place:
+  .seriousgaming-sdk/configuration.json
+Deleting the file starts again from the schema defaults.
+```
+
+Correct the typo, or delete the file and start again from the defaults:
+
+```bash
+rm .seriousgaming-sdk/configuration.json
+pnpm run sdk init
+```
+
+`sdk play`, `sdk scenario` and `sdk reconfigure` report the resolved values under `settings`.
+
+## Settings and patches
+
+Settings and JSON patches do different jobs:
+
+| Aspect     | Settings                                 | Patch                                 |
+| ---------- | ---------------------------------------- | ------------------------------------- |
+| Purpose    | Parameters the game runs on              | Simulate a participant's decisions    |
+| Applied    | Before play starts, fixed thereafter     | Before one tick                       |
+| Written by | Defaults, scenarios, the session layer   | The CLI, a surface's `setData`        |
+| Use case   | Difficulty, prices, content, answer keys | Prices chosen, workers hired, answers |
+
+```bash
+pnpm run sdk configure '{"engine":{"BaseDemand":15000}}'
+pnpm run sdk tick --patch '[{"op":"replace","path":"/price/Price","value":7}]'
+```
+
+## Related
+
+- [Create settings](../recipes/create-settings.md): the task, step by step
+- [Building a setup screen](./setup.md): the form that edits settings at session creation
+- [Building a scenario editor](./scenario-editor.md): the screen that authors lasting scenarios
+- [Scenarios](./scenarios.md): variants of a game that override settings
+- [Drive a game from the CLI](../cli-simulation-testing.md): configure, tick, patch, and read a session from the terminal
+- [Shaping games](./games.md): the rest of `seriousgaming.sdk.json`

package/dist/docs/guides/setup.md

@@ -0,0 +1,193 @@
+# Building a setup screen
+
+The `setup` slot holds the small form a facilitator fills in when they create a session. What it writes applies to that session only. This guide covers creating one, building its form, and how it behaves in the dev server.
+
+## What you'll learn
+
+- What the setup slot is for, and how it differs from the scenario editor
+- How to create a setup screen and choose the settings it edits
+- How to read and write settings with `useSettingsEditor`
+- How to start play from your own control with `requestPlay`
+
+## What setup is
+
+A game holds at most one setup screen, at `setup/`. It is a slot, like `session` or `waiting_room`, so it carries no name of its own: the slot is its identifier.
+
+| Aspect           | Setup                                   | Scenario editor                         |
+| ---------------- | --------------------------------------- | --------------------------------------- |
+| **When shown**   | When a session is created               | At any time, with no session            |
+| **What it does** | A short form for this session           | Authoring a lasting scenario            |
+| **Output**       | Session overrides for this session only | A saved scenario                        |
+| **Starts play**  | Yes, with `requestPlay` or host Play    | No                                      |
+| **Guide**        | This page                               | [Scenario editor](./scenario-editor.md) |
+
+A game with a `setup` slot opens at the **configuration step**: no team has a context yet, participants who arrive early wait, and play begins when the facilitator presses Play. A game without one starts at tick 0. Settings are fixed once play starts, so what setup writes reaches the engine and every surface that declares those settings from the first tick.
+
+Keep it small. Setup is part of somebody creating a session on the day, often in front of a room. Put the full authoring flow in the [scenario editor](./scenario-editor.md).
+
+## Creating a setup screen
+
+```bash
+pnpm run sdk new setup '{
+  "definition": {
+    "configures": ["engine"]
+  },
+  "rootDirectory": ".",
+  "ui": { "entrypoint": "index.html" }
+}'
+```
+
+`configures` names the [settings resources](./settings.md) the screen edits, by identifier: here the one at `settings/engine/`. The screen receives the resolved values of exactly those settings and can change nothing else: an `updateSettings` call naming any other settings resource is refused, and none of it is applied. The build fails if you name a settings resource the package does not declare.
+
+```
+setup/
+├── setup.sdk.json
+├── index.html
+├── types.ts        # generated
+├── defaults.ts     # generated
+└── src/
+    ├── main.tsx
+    ├── App.tsx
+    ├── i18n.ts
+    └── theme.ts
+```
+
+`src/main.tsx` wraps the app in `SettingsEditorWrapper`, the wrapper both settings editor slots share.
+
+## Building the form
+
+`useSettingsEditor()` returns three things:
+
+- `settings`: the resolved values of the settings this screen configures, keyed by settings identifier
+- `updateSettings(update)`: merges an update and sends the host only what changed. It returns a promise that rejects with a `MutationError` when the host refuses the write
+- `configures`: the identifiers this screen was sent
+
+Spreading `settings` into an update is safe: an unchanged value is never stored as a facilitator override, so a scenario chosen later still applies to it.
+
+```tsx
+import { useSettingsEditor } from '@seriousgaming/sdk/ui';
+import { Stack, TextField } from '@mui/material';
+import type { Settings } from '../types';
+
+function SetupForm() {
+    const { settings, updateSettings } = useSettingsEditor<Settings>();
+
+    return (
+        <Stack spacing={2}>
+            <TextField
+                label="Base demand"
+                type="number"
+                value={settings.engine.BaseDemand}
+                onChange={(e) =>
+                    void updateSettings({
+                        engine: { ...settings.engine, BaseDemand: Number(e.target.value) },
+                    })
+                }
+            />
+        </Stack>
+    );
+}
+```
+
+The generated `Settings` in `types.ts` has one entry per settings resource in `configures`, and `defaultSettings` in `defaults.ts` holds each one's defaults, which is the fixture to start a test from.
+
+### Setting the number of rounds
+
+The number of ticks and the team bounds are the built-in `game` settings, which a setup screen edits like any other once it lists `game` in `configures`:
+
+```json
+{ "definition": { "configures": ["game", "engine"] } }
+```
+
+```tsx
+<TextField
+    label="Rounds"
+    type="number"
+    value={settings.game.maxTicks ?? ''}
+    onChange={(e) =>
+        void updateSettings({ game: { ...settings.game, maxTicks: Number(e.target.value) } })
+    }
+/>
+```
+
+Two of the game settings behave differently here. `waitingRoom.openOnStart` takes effect before setup runs, so writing it is refused. And play cannot start while the team count is outside the `teams.min` and `teams.max` setup chose: the host's Play control and `requestPlay` are both refused until the facilitator adds or removes teams, or changes the setting. See [The game settings](./settings.md#the-game-settings).
+
+A write is also refused, as `denied` and with none of it applied, when it changes a setting the game locks with `readOnly` or sets a value outside its schema's range, the ranges a game sets on its own `game` settings with `gameSettingsConstraints` included. The screen is sent the values, not the schemas, so show a locked field as read-only and keep inputs within range yourself. Sending a locked value back unchanged, as a screen that spreads `settings` does, is not a change and is accepted. See [Lock a setting](./settings.md#lock-a-setting).
+
+## Starting play from your own control
+
+`useSettingsEditorCallbacks()` gives the screen `requestPlay`, which leaves the configuration step exactly as the host's Play control does:
+
+```tsx
+import { useSettingsEditorCallbacks } from '@seriousgaming/sdk/ui';
+import { Button } from '@mui/material';
+
+function StartButton() {
+    const { requestPlay } = useSettingsEditorCallbacks();
+    return (
+        <Button variant="contained" onClick={() => requestPlay()}>
+            Start game
+        </Button>
+    );
+}
+```
+
+The host always renders its own Play control on the configuration step, and a game cannot hide it. `requestPlay` adds a second way out rather than replacing it, so a bug in your control cannot strand a facilitator. `requestPlay` means something only in setup: the host ignores it from the scenario editor. See [Use requestPlay in a setup screen](../recipes/use-request-play.md).
+
+## Other hooks
+
+- `useSettingsEditorLocale()`: the current locale, for `src/i18n.ts`
+- `useSettingsEditorTheme()`: the host's theme, so colours follow its light and dark scheme
+- `useSettingsEditorThemePreference()`: the facilitator's theme preference; set it with `setThemePreference` from the callbacks
+- `useSettingsEditorCallbacks()`: also `uploadBlob`, `getAssetUrl`, `readAsset`, and the `endpoints` the bundle declares
+
+An endpoint called from setup sees `caller.role` as `'facilitator'`.
+
+## Rendering inside the host
+
+Setup is embedded in the host's page, not a page of its own:
+
+- **Leave the ground to the host.** Do not paint a page background. MUI's `CssBaseline` paints the body, so override it with `<GlobalStyles styles={{ body: { backgroundColor: 'transparent' } }} />`
+- **Prefer full-screen dialogs.** A centred modal inside an iframe is centred within the frame
+- **Do not reproduce host chrome.** The language picker, the theme control, and the Play action live outside your iframe
+
+The [session UI guide](./session.md#rendering-inside-the-host) covers the same ground in more detail.
+
+## Dev server behaviour
+
+`pnpm run sdk dev` opens a game with a setup slot at its configuration step, on `/setup`. Fill in the form and press Play (or your own control). Once play starts, `/setup` shows that the step has closed; **Reconfigure** in the dev drawer returns the session to it and every team to tick 0. Overrides persist in `.seriousgaming-sdk/` between runs, and `pnpm run sdk configure` sets them from the command line.
+
+## Managing the slot
+
+```bash
+pnpm run sdk update setup '{
+  "definition": { "configures": ["engine", "ui"] },
+  "rootDirectory": ".",
+  "ui": { "entrypoint": "index.html" }
+}'
+pnpm run sdk delete setup
+```
+
+Deleting the slot removes the configuration step: the game then starts at tick 0.
+
+## Testing
+
+`renderSettingsEditor` from `@seriousgaming/sdk/ui/testing` renders a component inside every settings editor provider:
+
+```tsx
+import { renderSettingsEditor } from '@seriousgaming/sdk/ui/testing';
+import { defaultSettings } from '../defaults';
+
+renderSettingsEditor(<SetupForm />, {
+    settings: defaultSettings,
+});
+```
+
+See [Test a user interface](../recipes/test-user-interface.md).
+
+## See also
+
+- [Scenario editor](./scenario-editor.md): authoring lasting scenarios
+- [Settings](./settings.md): declaring, reading, and overriding settings
+- [Scenarios](./scenarios.md)
+- [Create a setup screen](../recipes/create-setup.md)