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

package/dist/docs/recipes/create-session-ui.md

@@ -0,0 +1,116 @@
+# Create a session UI
+
+Build the facilitator's screen: every team's state side by side, with controls to change values and run the session.
+
+**Keywords:** manage session, facilitator UI, facilitator dashboard, session overview, all teams, session user interface, admin UI, admin panel, facilitator panel, hidden from participants, facilitator-only, game master, instructor view, cross-team
+
+## Prerequisites
+
+- Capabilities to show and change (here `price`, `workers`, and `production`); see [Create a capability](create-capability.md)
+- `seriousgaming.sdk.json` in your working directory
+
+## Steps
+
+1. Declare what the session UI reads and writes. A game holds at most one, in the `session/` slot, and the starter game already fills it, so in a package made with `new package` update it:
+
+    ```bash
+    pnpm run sdk update session --patch '[
+      { "op": "replace", "path": "/definition/reads", "value": ["production"] },
+      { "op": "replace", "path": "/definition/writes", "value": ["price", "workers"] }
+    ]'
+    ```
+
+    In a package without one (made with `new package --empty`), create it:
+
+    ```bash
+    pnpm run sdk new session '{
+      "definition": {
+        "reads": ["production"],
+        "writes": ["price", "workers"]
+      },
+      "rootDirectory": ".",
+      "ui": { "entrypoint": "index.html" }
+    }'
+    ```
+
+    Either regenerates `session/types.ts`, which includes a ready-made `SessionData`.
+
+2. Write the overview in `session/src/App.tsx`. `setData` takes the team id first, so each change lands on the team whose card it came from:
+
+    ```tsx
+    import {
+        useSessionUserInterfaceCallbacks,
+        useSessionUserInterfaceData,
+        useSessionUserInterfaceTeams,
+    } from '@seriousgaming/sdk/ui';
+
+    import type { SessionData, Settings } from '../types';
+
+    export default function App() {
+        const { sessionData, setData } = useSessionUserInterfaceData<SessionData, Settings>();
+        const teams = useSessionUserInterfaceTeams();
+        const { requestTick } = useSessionUserInterfaceCallbacks();
+
+        return (
+            <main>
+                {teams.map(({ teamId, name }) => {
+                    const team = sessionData.teams[teamId];
+                    if (!team) return null;
+                    return (
+                        <section key={teamId}>
+                            <h2>{name}</h2>
+                            <p>Production: {team.context.production.Production}</p>
+                            <label>
+                                Price
+                                <input
+                                    type="number"
+                                    value={team.context.price.Price}
+                                    onChange={(e) =>
+                                        setData(teamId, {
+                                            price: { Price: Number(e.target.value) },
+                                        })
+                                    }
+                                />
+                            </label>
+                            <button onClick={() => requestTick(teamId)}>Tick</button>
+                        </section>
+                    );
+                })}
+            </main>
+        );
+    }
+    ```
+
+    A `scope: 'shared'` capability arrives once, in `sessionData.shared.context`, and is written with the one-argument `setData(update)`. See [Writing shared capabilities](../guides/multi-team-games.md#facilitator-writable-shared-capabilities) and the [session UI hooks reference](../guides/session.md#hooks-reference) for roster control, timers, undo, and reset.
+
+3. If you replaced the starter's session UI, delete its other components and tests under `session/src/`, which read capabilities this one no longer declares.
+
+4. Build:
+
+    ```bash
+    pnpm run build
+    ```
+
+## Verify
+
+```bash
+pnpm run sdk dev
+```
+
+The session UI is the console at http://localhost:3000. Change a price on one team's card, then open that team's participant view: it shows the new value.
+
+## Troubleshooting
+
+| Problem                                    | Solution                                                                                                                 |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| `new session` fails with `RESOURCE_EXISTS` | The slot is filled: use `update session` (step 1), or `pnpm run sdk delete session --yes` and then `new session`         |
+| The teams list is empty                    | The session has no teams yet; `useSessionUserInterfaceTeams` returns `[]` until it does                                  |
+| A field shows a stale value                | Use `value=` (controlled), not `defaultValue=`                                                                           |
+| A change lands on the wrong team           | Check the first argument to `setData` is that card's `teamId`                                                            |
+| A shared write is refused                  | The capability must be `scope: 'shared'` and in this UI's `writes`; a per-team capability uses `setData(teamId, update)` |
+
+## Related
+
+- [Session UI guide](../guides/session.md)
+- [Create a user interface](create-user-interface.md)
+- [Test a user interface](test-user-interface.md)

package/dist/docs/recipes/create-settings.md

@@ -0,0 +1,88 @@
+# Create settings
+
+Give a game a read-only parameter, such as a price, a difficulty, or an answer key, that its logic and screens read and that scenarios and facilitators can change before play starts.
+
+**Keywords:** create settings, new settings, settings resource, settingsSchema, game parameters, configuration, configurable value, scenario override, answer key, difficulty
+
+## Prerequisites
+
+- A package with `seriousgaming.sdk.json` in your working directory
+
+## Steps
+
+1. Create the settings resource. Every property needs a `default`, and the schema has no top-level `required`. Describe each property (`title`, `description` with units, `minimum` and `maximum`): editors and AI agents read the schema:
+
+    ```bash
+    pnpm run sdk new settings '{
+      "definition": {
+        "identifier": "demand",
+        "settingsSchema": {
+          "type": "object",
+          "properties": {
+            "BaseDemand": {
+              "type": "number",
+              "title": "Base demand",
+              "description": "Units customers would buy each tick at a price of zero",
+              "default": 100,
+              "minimum": 0,
+              "maximum": 10000
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    }'
+    ```
+
+2. List it on each resource that reads it. For the engine and the game UI:
+
+    ```bash
+    pnpm run sdk update engine --patch '[{ "op": "add", "path": "/definition/settings/-", "value": "demand" }]'
+    pnpm run sdk update ui --patch '[{ "op": "add", "path": "/definition/settings/-", "value": "demand" }]'
+    ```
+
+    Use `"path": "/definition/settings", "value": ["demand"]` for a resource that lists no settings yet. Each command regenerates that resource's `types.ts`.
+
+3. Read it in logic as `settings.demand`:
+
+    ```typescript
+    export const Run: RunFunction<Context, Settings> = async ({ context, settings }) => {
+        const Sales = Math.max(0, settings.demand.BaseDemand - context.price.Price * 2);
+        return { capabilities: { ...context, sales: { ...context.sales, Sales } } };
+    };
+    ```
+
+4. Read it in a screen from `useUserInterfaceData()`:
+
+    ```tsx
+    const { settings } = useUserInterfaceData<Context, Settings>();
+    return <p>Typical demand: {settings.demand.BaseDemand}</p>;
+    ```
+
+5. Optional: override it in a scenario, keyed by settings identifier (see [Create a scenario](create-scenario.md)). To change it for every session, edit its `default`.
+
+## Verify
+
+```bash
+pnpm run sdk configure '{"demand":{"BaseDemand":250}}'
+pnpm run sdk view --full
+```
+
+The resolved `settings.demand.BaseDemand` is `250`, and the next `pnpm run sdk tick` plays with it.
+
+## Troubleshooting
+
+| Problem                                                        | Solution                                                                                              |
+| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `Every settings property declares a default, and "X" does not` | Add a `default` to that property                                                                      |
+| `reads settings "demand", which this package does not declare` | The directory name and the `settings` entry differ                                                    |
+| `settings.demand` is undefined                                 | Add `demand` to that resource's `settings`                                                            |
+| `Unknown settings "engine"` from `configure` or a scenario     | Overrides are keyed by settings identifier, not by the resource that reads them                       |
+| A participant can see a value they should not                  | Move it to a settings resource only the engine or an endpoint lists                                   |
+| The value does not change mid-game                             | Expected: settings are fixed when play starts. Use a capability for anything that changes during play |
+
+## Related
+
+- [Settings guide](../guides/settings.md): declaring, reading, overriding, and validation
+- [Create a scenario](create-scenario.md)
+- [Create a setup screen](create-setup.md)

package/dist/docs/recipes/create-setup.md

@@ -0,0 +1,115 @@
+# Create a setup screen
+
+Give facilitators a short form at session creation that sets a few of your game's settings for that session only.
+
+**Keywords:** setup, setup screen, quick config, session setup, configuration step, configure session, settings form, requestPlay, configures
+
+## What you'll build
+
+A setup screen at `setup/` that edits the `engine` settings and starts play from its own button. A game with a `setup` slot opens at the configuration step: nothing runs until the facilitator presses Play. See the [setup guide](../guides/setup.md) for the full behaviour.
+
+## Prerequisites
+
+- A settings resource for the screen to edit; see [Create a settings resource](create-settings.md)
+- `seriousgaming.sdk.json` in your working directory
+
+## Steps
+
+### 1. Create the slot
+
+```bash
+pnpm run sdk new setup '{
+  "definition": {
+    "configures": ["engine"]
+  },
+  "rootDirectory": ".",
+  "ui": { "entrypoint": "index.html" }
+}'
+```
+
+This creates:
+
+```
+setup/
+├── setup.sdk.json
+├── defaults.ts
+├── index.html
+├── types.ts
+└── src/
+    ├── main.tsx
+    ├── App.tsx
+    ├── App.test.tsx
+    ├── i18n.ts
+    └── theme.ts
+```
+
+### 2. Build the form
+
+Open `setup/src/App.tsx`. Read and write the settings with `useSettingsEditor`, typed by the generated `Settings`:
+
+```tsx
+import { useSettingsEditor, useSettingsEditorCallbacks } from '@seriousgaming/sdk/ui';
+import { Button, Stack, TextField } from '@mui/material';
+import type { Settings } from '../types';
+
+function App() {
+    const { settings, updateSettings } = useSettingsEditor<Settings>();
+    const { requestPlay } = useSettingsEditorCallbacks();
+
+    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) },
+                    })
+                }
+            />
+            <Button variant="contained" onClick={() => requestPlay()}>
+                Start game
+            </Button>
+        </Stack>
+    );
+}
+
+export default App;
+```
+
+`updateSettings` sends only what changed, so spreading `settings` is safe.
+
+### 3. Run it
+
+```bash
+pnpm run sdk dev
+```
+
+The dev server opens on `/setup`.
+
+## Verify
+
+- [ ] The form shows each setting's resolved value
+- [ ] Changing a value and pressing Start (or the host's Play) starts the session with that value
+- [ ] `pnpm run sdk view` after play shows the engine acting on the new value
+
+## Troubleshooting
+
+**The build fails naming a settings resource**
+
+Every identifier in `configures` must be a settings resource the package declares under `settings/`.
+
+**`useSettingsEditor` throws**
+
+The hook must run inside `SettingsEditorWrapper`, which the scaffolded `src/main.tsx` provides.
+
+**The game starts at tick 0 with no form**
+
+The configuration step exists only when the package has a `setup/setup.sdk.json`. Check the slot directory and bundle name.
+
+## Related
+
+- [Create a scenario editor](create-scenario-editor.md)
+- [Use requestPlay in a setup screen](use-request-play.md)
+- [Create a settings resource](create-settings.md)

package/dist/docs/recipes/create-tick-controller.md

@@ -0,0 +1,65 @@
+# Create a tick controller
+
+Make ticks fire automatically, on an interval or a schedule your game's logic decides.
+
+**Keywords:** create tick controller, new tick controller, automatic ticks, timer, tick interval, auto tick, schedule ticks
+
+## Prerequisites
+
+- A capability the controller decides from (here `progress`, with a `Phase` string); see [Create a capability](create-capability.md)
+- `seriousgaming.sdk.json` in your working directory
+
+## Steps
+
+1. Create the tick controller. A game holds at most one, in the `tick_controller/` slot, which the starter game leaves empty:
+
+    ```bash
+    pnpm run sdk new tick_controller '{
+      "definition": { "reads": ["progress"] },
+      "logic": { "directory": ".", "entrypoint": "logic.ts" },
+      "rootDirectory": "."
+    }'
+    ```
+
+2. Write `GetTickController` in `tick_controller/logic.ts`. Return a cadence with `intervalTick`, which takes milliseconds and refuses anything outside 30 seconds to 7 days:
+
+    ```typescript
+    import { GetTickControllerFunction, intervalTick } from '@seriousgaming/sdk';
+
+    import type { Context, Settings } from './types';
+
+    export const GetTickController: GetTickControllerFunction<Context, Settings> = async ({
+        context,
+    }) => intervalTick(context.progress.Phase === 'early' ? 30_000 : 60_000);
+    ```
+
+    For fixed times of day, return `scheduledTick(nextDailyAt(...))`; for manual ticks only, `{ enabled: false }`. See the [cadence cookbook](../guides/tick-controller.md#cadence-cookbook).
+
+3. Build:
+
+    ```bash
+    pnpm run build
+    ```
+
+## Verify
+
+```bash
+pnpm run sdk timer
+```
+
+The timer reports `enabled: true` and the next tick. In the dev server, the drawer shows the countdown and ticks fire on their own. To test without waiting, see [Testing without waiting](../guides/tick-controller.md#testing-without-waiting).
+
+## Troubleshooting
+
+| Problem                                            | Solution                                                                                                                          |
+| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `new tick_controller` fails with `RESOURCE_EXISTS` | The game already has one: change it with `update tick_controller`                                                                 |
+| `intervalTick(60)` throws                          | `intervalMs` is in milliseconds, so `60` is below the floor. Write `60_000` for a minute                                          |
+| The timer never starts                             | Check the controller returns `enabled: true` (or an `intervalTick` result)                                                        |
+| `context.progress` is a type error                 | Add `progress` to the controller's `reads`                                                                                        |
+| Ticks keep firing in the waiting room              | Read `waitingRoomOpen` (see [Stopping the clock](../guides/tick-controller.md#stopping-the-clock-while-the-waiting-room-is-open)) |
+
+## Related
+
+- [Tick controller guide](../guides/tick-controller.md): the result, bounds, scheduling, pausing, and completion
+- [End a game when a condition is met](end-game-on-condition.md)

package/dist/docs/recipes/create-user-interface.md

@@ -0,0 +1,96 @@
+# Create a user interface
+
+Build the game UI: the screen each participant sees, showing the game's state and taking their decisions.
+
+**Keywords:** create user interface, new UI, display game state, user input, participant interface, participant UI, game UI
+
+## Prerequisites
+
+- Capabilities to show and write (here `pricing` and `sales`); see [Create a capability](create-capability.md)
+- An engine that fills them; see [Create an engine](create-engine.md)
+- `seriousgaming.sdk.json` in your working directory
+
+## Steps
+
+1. Declare what the UI reads and writes. A game holds one UI, in the `ui/` slot, and the starter game already fills it, so in a package made with `new package` update it:
+
+    ```bash
+    pnpm run sdk update ui --patch '[
+      { "op": "replace", "path": "/definition/reads", "value": ["sales"] },
+      { "op": "replace", "path": "/definition/writes", "value": ["pricing"] }
+    ]'
+    ```
+
+    In a package made with `new package --empty`, create the slot instead:
+
+    ```bash
+    pnpm run sdk new ui '{
+      "definition": {
+        "reads": ["sales"],
+        "writes": ["pricing"]
+      },
+      "ui": { "entrypoint": "index.html" },
+      "rootDirectory": "."
+    }'
+    ```
+
+    `data` carries the union of `reads` and `writes`, so `pricing` is readable too. Either command regenerates `ui/types.ts`.
+
+2. Write the component in `ui/src/App.tsx`. Read with `useUserInterfaceData`, and write only the fields that changed:
+
+    ```tsx
+    import { useUserInterfaceData } from '@seriousgaming/sdk/ui';
+
+    import type { Context, Settings } from '../types';
+
+    export default function App() {
+        const { data, setData } = useUserInterfaceData<Context, Settings>();
+
+        const raisePrice = () =>
+            setData({ pricing: { CurrentPrice: data.pricing.CurrentPrice + 10 } });
+
+        return (
+            <main>
+                <h1>Game dashboard</h1>
+                <p>Current price: {data.pricing.CurrentPrice}</p>
+                <button onClick={raisePrice}>Raise price by 10</button>
+                <p>Daily revenue: {data.sales.Revenue}</p>
+            </main>
+        );
+    }
+    ```
+
+    Never spread `data` (or a whole capability) back into `setData`: a write naming a capability outside `writes` is refused, and re-sending untouched fields overwrites a team-mate's concurrent write. See [Writing to context](../guides/ui.md#writing-to-context).
+
+3. If you replaced the starter game's UI, delete the starter's other components and their tests under `ui/src/`: they read capabilities this UI no longer declares, so they stop type-checking.
+
+4. Build:
+
+    ```bash
+    pnpm run build
+    ```
+
+## Verify
+
+```bash
+pnpm run sdk dev
+```
+
+Open a team's participant view. It shows the current price and revenue, and **Raise price by 10** changes the price in every view of that team.
+
+## Troubleshooting
+
+| Problem                                            | Solution                                                                                          |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `new ui` fails with `RESOURCE_EXISTS`              | The slot is filled: use `update ui` (step 1), or `pnpm run sdk delete ui --yes` and then `new ui` |
+| `data.pricing` is a type error                     | `pricing` is in neither `reads` nor `writes`; add it and let the command regenerate `types.ts`    |
+| The write is refused as `denied`                   | The write names a capability outside `writes`. Send only the capability you declared              |
+| A team-mate's change disappears when another saves | A write re-sends fields from a stale snapshot; send only the changed field                        |
+| Translations do not appear                         | See the [internationalisation guide](../guides/internationalization.md)                           |
+
+## Related
+
+- [User interfaces guide](../guides/ui.md): reading and writing state, ticks, participants, timers and theming
+- [Design state for concurrent writes](design-state-for-concurrent-writes.md)
+- [Use requestTick in a UI](use-request-tick.md)
+- [Test a user interface](test-user-interface.md)

package/dist/docs/recipes/create-validator.md

@@ -0,0 +1,67 @@
+# Create a validator
+
+Reject a participant's write that breaks the game's rules, before the runtime applies it.
+
+**Keywords:** create validator, new validator, mutation validation, gate update, reject decision, reject submission, RequestTick
+
+## Prerequisites
+
+- A capability participants write (here `decisions`, a map of boolean choices); see [Create a capability](create-capability.md)
+- `seriousgaming.sdk.json` in your working directory
+
+## Steps
+
+1. Create the validator, declaring what it reads:
+
+    ```bash
+    pnpm run sdk new validator '{
+      "definition": {
+        "identifier": "decisionlimit",
+        "reads": ["decisions"]
+      },
+      "logic": { "directory": "logic", "entrypoint": "logic.ts" },
+      "rootDirectory": "."
+    }'
+    ```
+
+    This writes `validators/decisionlimit/` with `validator.sdk.json`, `logic/logic.ts`, and a generated `types.ts`. The directory is the whole of the wiring.
+
+2. Write `UpdateData` in `validators/decisionlimit/logic/logic.ts`. Judge `next`, the context as it would be after the write, and either allow it or reject it with a message:
+
+    ```typescript
+    import type { ValidatorFunction } from '../types';
+
+    export const UpdateData: ValidatorFunction = async ({ next }) => {
+        const selected = Object.values(next.decisions).filter(Boolean).length;
+        return selected > 3 ? { ok: false, message: 'errors.max-three-decisions' } : { ok: true };
+    };
+    ```
+
+    A validator never changes state. To read who wrote it, narrow on `actor.role` (see [The actor](../guides/validators.md#the-actor)).
+
+3. Optional: gate a participant's request for the next tick by exporting `RequestTick` as well (see [Gating tick requests](../guides/validators.md#gating-tick-requests)).
+
+4. Build:
+
+    ```bash
+    pnpm run build
+    ```
+
+## Verify
+
+From a participant's screen, submit a fourth choice: the write is refused, and the UI receives the rejection through `useUserInterfaceValidationRejections` (and as a `validation-rejected` outcome where it awaits the write). In a test, `session.setData(0, ...)` answers `{ ok: false, outcome: { kind: 'validation-rejected' } }` (see [Injecting decisions](../guides/engine-testing.md#injecting-decisions)).
+
+## Troubleshooting
+
+| Problem                             | Solution                                                                                                                                                          |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The validator never runs            | Check `validators/<identifier>/validator.sdk.json` exists                                                                                                         |
+| It allows what it should reject     | Judge `next`, the proposed state, not `previous`                                                                                                                  |
+| A CLI patch passes despite the rule | Expected: the CLI, the engine, and endpoints are trusted and bypass validators (see [What bypasses validation](../guides/validators.md#what-bypasses-validation)) |
+| `next.decisions` is a type error    | Add `decisions` to the validator's `reads`                                                                                                                        |
+
+## Related
+
+- [Validators guide](../guides/validators.md): the actor, ordering, settings, and what bypasses validation
+- [Design state for concurrent writes](design-state-for-concurrent-writes.md): arbitrating contested slots
+- [Create a hook](create-hook.md)

package/dist/docs/recipes/create-waiting-room-ui.md

@@ -0,0 +1,109 @@
+# Create a waiting room UI
+
+Replace the host's stock holding screen with your own, so participants see your branding and your words while the facilitator has the waiting room open.
+
+**Keywords:** waiting room, holding screen, lobby, waiting to begin, session paused, park a session, break, waitingRoom
+
+## Prerequisites
+
+- A game; see [Shape your game](create-game.md)
+- Optionally, capabilities the room should show (here `briefing`)
+- `seriousgaming.sdk.json` in your working directory
+
+## Steps
+
+1. Declare what the room reads. A game holds at most one waiting room, in the `waiting_room/` slot, and the starter game already fills it, so in a package made with `new package` update it:
+
+    ```bash
+    pnpm run sdk update waiting_room --patch '[
+      { "op": "replace", "path": "/definition/reads", "value": ["briefing"] }
+    ]'
+    ```
+
+    In a package without one, create it:
+
+    ```bash
+    pnpm run sdk new waiting_room '{
+      "definition": { "reads": ["briefing"] },
+      "rootDirectory": ".",
+      "ui": { "entrypoint": "index.html" }
+    }'
+    ```
+
+2. Write the screen in `waiting_room/src/App.tsx`. It takes the same `useUserInterface*` hooks as the game UI. Branch on `completedTicks`, so a session parked mid-play does not say 'waiting to begin':
+
+    ```tsx
+    import {
+        useUserInterfaceData,
+        useUserInterfaceOwnTeam,
+        useUserInterfaceParticipants,
+    } from '@seriousgaming/sdk/ui';
+
+    import type { Context, Settings } from '../types';
+
+    export default function App() {
+        const { completedTicks } = useUserInterfaceData<Context, Settings>();
+        const ownTeam = useUserInterfaceOwnTeam();
+        const participants = useUserInterfaceParticipants();
+
+        return (
+            <main>
+                <h1>{completedTicks === 0 ? 'Waiting to begin' : 'Session paused'}</h1>
+                <p>You have joined {ownTeam?.name}. The facilitator will continue shortly.</p>
+                <ul>
+                    {participants.map((p) => (
+                        <li key={p.id}>
+                            {p.name} {p.connected ? '(here)' : ''}
+                        </li>
+                    ))}
+                </ul>
+            </main>
+        );
+    }
+    ```
+
+3. Optional: open the room when a session starts, so nobody lands in the game before the facilitator is ready (the starter game already does):
+
+    ```bash
+    pnpm run sdk update package --patch '[
+      { "op": "add", "path": "/waitingRoom", "value": { "openOnStart": true } }
+    ]'
+    ```
+
+4. Optional: stop automatic ticks while the room is open. Opening it does not pause them; read `waitingRoomOpen` in your tick controller:
+
+    ```typescript
+    export const GetTickController: GetTickControllerFunction<Context, Settings> = async ({
+        waitingRoomOpen,
+    }) => ({ enabled: !waitingRoomOpen, intervalMs: 60_000 });
+    ```
+
+5. Build:
+
+    ```bash
+    pnpm run build
+    ```
+
+## Verify
+
+```bash
+pnpm run sdk dev
+```
+
+Open http://localhost:3000, press the backtick key for the dev drawer, switch on **Waiting room**, and open a team's game UI. The room replaces the game UI at once, and switching it off brings the game back with no reload. Run a tick first to see the 'Session paused' wording.
+
+## Troubleshooting
+
+| Problem                                         | Solution                                                                                                  |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `new waiting_room` fails with `RESOURCE_EXISTS` | The slot is filled: use `update waiting_room` (step 1), or `pnpm run sdk delete waiting_room --yes` first |
+| The host's built-in panel shows instead         | The package has no `waiting_room/` slot                                                                   |
+| Ticks keep firing while the room is open        | Expected: read `waitingRoomOpen` in your tick controller (step 4)                                         |
+| `data` is empty                                 | Add the capability to the bundle's `reads`                                                                |
+| The roster is empty                             | Participants join per team; open a team's game UI rather than the console                                 |
+
+## Related
+
+- [Waiting room guide](../guides/waiting-room.md): held starts, join codes, roster, and layout
+- [Create a tick controller](create-tick-controller.md)
+- [Test a user interface](test-user-interface.md)