@seriousgaming/sdk-tools 1.4.0 → 1.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/bundling/ui-bundler.d.ts +12 -0
- package/dist/cli-25RWY5BQ.js +41 -0
- package/dist/cli-272KBNJH.js +97 -0
- package/dist/cli-2BH7FX27.js +52 -0
- package/dist/cli-2GOFEW26.js +81 -0
- package/dist/cli-3E3MD5U4.js +21 -0
- package/dist/cli-3HE4AVZG.js +115 -0
- package/dist/cli-4AKVLEC4.js +1387 -0
- package/dist/cli-4BV45LBH.js +126 -0
- package/dist/cli-4LKXZQ2B.js +48 -0
- package/dist/cli-4UWFQNGF.js +54 -0
- package/dist/cli-4YB3ROVR.js +78 -0
- package/dist/cli-57RXC3HQ.js +36 -0
- package/dist/cli-5JEGTVTG.js +96 -0
- package/dist/cli-6AMT3BUO.js +97 -0
- package/dist/cli-6RRVEGFB.js +80 -0
- package/dist/cli-6WXLXJVX.js +36 -0
- package/dist/cli-7OGYADZ3.js +97 -0
- package/dist/cli-AK7OIPWY.js +229 -0
- package/dist/cli-B4TN6PJP.js +124 -0
- package/dist/cli-B6YHEKIJ.js +248 -0
- package/dist/cli-BPYMTOUL.js +89 -0
- package/dist/cli-BWX5E7TQ.js +23 -0
- package/dist/cli-BYJWFFCF.js +37 -0
- package/dist/cli-C3NVCKO6.js +43 -0
- package/dist/cli-C47GJATR.js +42 -0
- package/dist/cli-C5QOJJWX.js +46 -0
- package/dist/cli-C6TH5S7K.js +6417 -0
- package/dist/cli-DL2CVMRF.js +89 -0
- package/dist/cli-DMW2OQIJ.js +76 -0
- package/dist/cli-DZW3XD5F.js +143 -0
- package/dist/cli-E2NLWIFE.js +1331 -0
- package/dist/cli-E33CJRRQ.js +36 -0
- package/dist/cli-E6DJIMYD.js +142 -0
- package/dist/cli-EEFJKIGL.js +151 -0
- package/dist/cli-EVFS55WN.js +185 -0
- package/dist/cli-F2D4GGUA.js +549 -0
- package/dist/cli-FBTRTIZJ.js +226 -0
- package/dist/cli-FWFRKQNE.js +11 -0
- package/dist/cli-FYINNRML.js +760 -0
- package/dist/cli-G522CPRL.js +88 -0
- package/dist/cli-G6KELFSX.js +2847 -0
- package/dist/cli-G6UE5NL4.js +90 -0
- package/dist/cli-GBFM76BF.js +16 -0
- package/dist/cli-GDQ6ILJY.js +101 -0
- package/dist/cli-GFBGYFYD.js +50 -0
- package/dist/cli-GGPDQNM3.js +35 -0
- package/dist/cli-GTSGLN3Z.js +307 -0
- package/dist/cli-GUXKQMJ7.js +13641 -0
- package/dist/cli-GXD36NF2.js +60 -0
- package/dist/cli-HCRTYQQS.js +16 -0
- package/dist/cli-HYY64SUD.js +185 -0
- package/dist/cli-I355WTAF.js +463 -0
- package/dist/cli-IDKYF5XB.js +59 -0
- package/dist/cli-ILKCQNM6.js +8 -0
- package/dist/cli-IRZ5KB7D.js +36 -0
- package/dist/cli-IUS2YCD3.js +31 -0
- package/dist/cli-J4DKUUTK.js +138 -0
- package/dist/cli-JFU22EJ2.js +187 -0
- package/dist/cli-JMZLT65J.js +226 -0
- package/dist/cli-JZM7XTNV.js +89 -0
- package/dist/cli-K2B6WHKA.js +81 -0
- package/dist/cli-KL3756X6.js +126 -0
- package/dist/cli-KNOOKGYW.js +88 -0
- package/dist/cli-LFGRFIEO.js +226 -0
- package/dist/cli-LFM7GJHI.js +0 -0
- package/dist/cli-LMDJCHHD.js +304 -0
- package/dist/cli-LXYPE3L5.js +99 -0
- package/dist/cli-M6BCQRID.js +153 -0
- package/dist/cli-MBNMPVDC.js +367 -0
- package/dist/cli-MJUYJIEP.js +13 -0
- package/dist/cli-MMN4BPO4.js +145 -0
- package/dist/cli-MYJGMA6U.js +40 -0
- package/dist/cli-N6H6T2E2.js +616 -0
- package/dist/cli-O5KP4OVN.js +61 -0
- package/dist/cli-O6PWMJTZ.js +25 -0
- package/dist/cli-ORIG557O.js +141 -0
- package/dist/cli-PFFCNGHI.js +243 -0
- package/dist/cli-PNLYX6R6.js +131 -0
- package/dist/cli-PQBXVLEU.js +649 -0
- package/dist/cli-PTT5RGKO.js +62 -0
- package/dist/cli-Q2XJF5AS.js +127 -0
- package/dist/cli-QEVDDBNO.js +60 -0
- package/dist/cli-QEVE5HUM.js +167 -0
- package/dist/cli-QUIJCBYB.js +391 -0
- package/dist/cli-QUNIRH7A.js +57 -0
- package/dist/cli-QVASWX2A.js +187 -0
- package/dist/cli-QWQMPCL6.js +253 -0
- package/dist/cli-R4PCG5YX.js +131 -0
- package/dist/cli-RA673NGF.js +53 -0
- package/dist/cli-RN6IWTL2.js +36 -0
- package/dist/cli-ROT3DRKU.js +145 -0
- package/dist/cli-RZITKPJX.js +367 -0
- package/dist/cli-S5IVGDDD.js +32 -0
- package/dist/cli-S5QDONIQ.js +218 -0
- package/dist/cli-SIPDUBFL.js +36 -0
- package/dist/cli-SMFSZF2G.js +4009 -0
- package/dist/cli-SRHBXZCN.js +159 -0
- package/dist/cli-TCY5LJ7E.js +88 -0
- package/dist/cli-TDSQSCX4.js +131 -0
- package/dist/cli-TIDQ4WUE.js +257 -0
- package/dist/cli-TLLA6KAP.js +79 -0
- package/dist/cli-TPU4TUR6.js +132 -0
- package/dist/cli-U2UE7I7J.js +30 -0
- package/dist/cli-UELGBQG7.js +101 -0
- package/dist/cli-UHSZBKYO.js +97 -0
- package/dist/cli-UJ4UCL2Z.js +38 -0
- package/dist/cli-UKQYZYFK.js +31 -0
- package/dist/cli-UMFFURZ7.js +81 -0
- package/dist/cli-UNAJ2OTE.js +15 -0
- package/dist/cli-UNJ5X6BU.js +89 -0
- package/dist/cli-UTJU4IYG.js +117 -0
- package/dist/cli-V4GHRWOV.js +1837 -0
- package/dist/cli-VCI3CG36.js +73 -0
- package/dist/cli-VCKOC2EV.js +256 -0
- package/dist/cli-VL2P354N.js +46 -0
- package/dist/cli-WAE26SVW.js +72 -0
- package/dist/cli-WOGIAU2E.js +100 -0
- package/dist/cli-WU43JT4T.js +52 -0
- package/dist/cli-XCO2VQOH.js +122 -0
- package/dist/cli-XSVGKI3R.js +39 -0
- package/dist/cli-YOTGR3NB.js +82 -0
- package/dist/cli-YVVXUD2G.js +197 -0
- package/dist/cli-ZISJ36MM.js +89 -0
- package/dist/cli-ZTWOE3ZT.js +65 -0
- package/dist/cli-ZVSFYDPQ.js +205 -0
- package/dist/cli-ZWPYIXNI.js +68 -0
- package/dist/cli.js +171 -42385
- package/dist/client/build-surfaces.d.ts +33 -0
- package/dist/client/dev-server.d.ts +6 -0
- package/dist/client/index.d.ts +1 -0
- package/dist/client/playwright.d.ts +62 -0
- package/dist/client.js +339 -56
- package/dist/core/session.d.ts +15 -1
- package/dist/dev/console/assets/{index-BvB-LFQZ.js → index-CuMOOH9m.js} +21 -21
- package/dist/dev/console/index.html +1 -1
- package/dist/dev/public-origins.d.ts +61 -0
- package/dist/dev/shell.d.ts +51 -4
- package/dist/dev/surfaces.d.ts +7 -0
- package/dist/docs/ai-agents.md +5 -0
- package/dist/docs/api/index.md +14 -12
- package/dist/docs/api/sdk-tools-client.md +29 -0
- package/dist/docs/api/sdk-tools-playwright.md +104 -0
- package/dist/docs/changelog-0.x.md +2 -2
- package/dist/docs/changelog.md +56 -4
- package/dist/docs/cli-and-dev-server.md +79 -0
- package/dist/docs/cli-error-codes.md +39 -36
- package/dist/docs/cli-reference.md +93 -32
- package/dist/docs/environment-variables.md +16 -5
- package/dist/docs/guides/ai-facilitation.md +2 -0
- package/dist/docs/guides/capabilities.md +2 -0
- package/dist/docs/guides/designing-a-game.md +31 -4
- package/dist/docs/guides/designing-screens.md +133 -0
- package/dist/docs/guides/endpoints.md +2 -0
- package/dist/docs/guides/engine-testing.md +5 -1
- package/dist/docs/guides/engine.md +2 -0
- package/dist/docs/guides/file-handling.md +3 -1
- package/dist/docs/guides/games.md +3 -1
- package/dist/docs/guides/global-settings.md +2 -0
- package/dist/docs/guides/guide.md +2 -0
- package/dist/docs/guides/hooks.md +2 -0
- package/dist/docs/guides/index.md +9 -0
- package/dist/docs/guides/internationalization.md +2 -0
- package/dist/docs/guides/llm-integration.md +4 -2
- package/dist/docs/guides/multi-team-games.md +3 -1
- package/dist/docs/guides/patterns.md +2 -0
- package/dist/docs/guides/presentation.md +1 -1
- package/dist/docs/guides/production-constraints.md +2 -0
- package/dist/docs/guides/scenario-editor.md +2 -0
- package/dist/docs/guides/scenarios.md +6 -2
- package/dist/docs/guides/session-game-flow.md +365 -0
- package/dist/docs/guides/session-hooks.md +205 -0
- package/dist/docs/guides/session.md +27 -565
- package/dist/docs/guides/settings.md +2 -0
- package/dist/docs/guides/setup.md +3 -1
- package/dist/docs/guides/speech-generation.md +2 -0
- package/dist/docs/guides/starter-game.md +63 -23
- package/dist/docs/guides/testing.md +35 -18
- package/dist/docs/guides/tick-controller.md +3 -1
- package/dist/docs/guides/type-safety.md +2 -0
- package/dist/docs/guides/ui-files-and-llms.md +328 -0
- package/dist/docs/guides/ui-participants.md +281 -0
- package/dist/docs/guides/ui-styling.md +263 -0
- package/dist/docs/guides/ui-ticks.md +247 -0
- package/dist/docs/guides/ui.md +11 -1092
- package/dist/docs/guides/upgrading.md +2 -0
- package/dist/docs/guides/validators.md +2 -0
- package/dist/docs/guides/waiting-room.md +1 -1
- package/dist/docs/index.md +2 -1
- package/dist/docs/page-index.md +146 -0
- package/dist/docs/recipes/adapt-a-game-for-walkthroughs.md +1 -1
- package/dist/docs/recipes/adapt-ui-for-observers.md +1 -1
- package/dist/docs/recipes/create-presentation.md +11 -0
- package/dist/docs/recipes/create-scenario-editor.md +1 -0
- package/dist/docs/recipes/create-session-ui.md +2 -1
- package/dist/docs/recipes/create-setup.md +1 -0
- package/dist/docs/recipes/create-user-interface.md +1 -0
- package/dist/docs/recipes/create-waiting-room-ui.md +1 -0
- package/dist/docs/recipes/design-state-for-concurrent-writes.md +1 -1
- package/dist/docs/recipes/e2e-testing.md +19 -20
- package/dist/docs/recipes/fix-duplicate-packages.md +2 -2
- package/dist/docs/recipes/index.md +3 -0
- package/dist/docs/recipes/screenshot-a-surface.md +80 -0
- package/dist/docs/recipes/test-a-multi-role-game.md +1 -1
- package/dist/docs/recipes/use-request-tick.md +2 -2
- package/dist/execution/config-resolver.d.ts +4 -1
- package/dist/playwright.js +32232 -0
- package/dist/runtime/manifest-version.d.ts +1 -1
- package/dist/runtime.js +1 -1
- package/dist/templates/package/CLAUDE.md.template +14 -5
- package/dist/templates/package/DESIGN.md.liquid +39 -7
- package/dist/templates/package/README.md.liquid +1 -1
- package/dist/templates/package/claude/rules/workflow-create-user-interface.md +1 -1
- package/dist/templates/package/claude/rules/workflow-test-engine-or-ui.md +1 -1
- package/dist/templates/package/global-setup.ts.template +7 -18
- package/dist/templates/package/playwright.config.ts.liquid +8 -11
- package/dist/templates/package/pnpm-workspace.yaml.template +13 -0
- package/dist/templates/starter-game/capabilities/pacing/capability.sdk.json +18 -0
- package/dist/templates/starter-game/package.json +2 -0
- package/dist/templates/starter-game/playwright.config.ts +8 -11
- package/dist/templates/starter-game/presentation/defaults.ts +52 -0
- package/dist/templates/starter-game/presentation/index.html +20 -0
- package/dist/templates/starter-game/presentation/presentation.sdk.json +10 -0
- package/dist/templates/starter-game/presentation/src/App.tsx +55 -0
- package/dist/templates/starter-game/presentation/src/Band.tsx +40 -0
- package/dist/templates/starter-game/presentation/src/Slides.tsx +415 -0
- package/dist/templates/starter-game/presentation/src/WeatherIcon.tsx +21 -0
- package/dist/templates/starter-game/presentation/src/i18n.ts +88 -0
- package/dist/templates/starter-game/presentation/src/main.tsx +15 -0
- package/dist/templates/starter-game/presentation/src/stalls.test.ts +196 -0
- package/dist/templates/starter-game/presentation/src/stalls.ts +199 -0
- package/dist/templates/starter-game/presentation/types.ts +94 -0
- package/dist/templates/starter-game/seriousgaming.sdk.json +2 -1
- package/dist/templates/starter-game/session/defaults.ts +6 -0
- package/dist/templates/starter-game/session/index.html +1 -1
- package/dist/templates/starter-game/session/session.sdk.json +2 -2
- package/dist/templates/starter-game/session/src/App.test.tsx +436 -115
- package/dist/templates/starter-game/session/src/App.tsx +372 -222
- package/dist/templates/starter-game/session/src/JoinCodes.tsx +184 -0
- package/dist/templates/starter-game/session/src/ManagePanel.tsx +188 -0
- package/dist/templates/starter-game/session/src/Results.tsx +340 -0
- package/dist/templates/starter-game/session/src/SessionBar.tsx +179 -0
- package/dist/templates/starter-game/session/src/SessionPanels.tsx +105 -0
- package/dist/templates/starter-game/session/src/SidePanel.tsx +89 -0
- package/dist/templates/starter-game/session/src/StallCard.tsx +253 -0
- package/dist/templates/starter-game/session/src/TopBar.tsx +36 -0
- package/dist/templates/starter-game/session/src/i18n.ts +91 -24
- package/dist/templates/starter-game/session/src/status.ts +28 -0
- package/dist/templates/starter-game/session/types.ts +8 -2
- package/dist/templates/starter-game/shared/Awning.tsx +31 -0
- package/dist/templates/starter-game/shared/HostLogo.test.tsx +38 -0
- package/dist/templates/starter-game/shared/HostLogo.tsx +48 -0
- package/dist/templates/starter-game/shared/StallIcons.tsx +83 -0
- package/dist/templates/starter-game/shared/days.ts +11 -0
- package/dist/templates/starter-game/shared/format.test.ts +13 -0
- package/dist/templates/starter-game/{ui/src → shared}/format.ts +1 -1
- package/dist/templates/starter-game/testing/e2e/game.spec.ts +43 -9
- package/dist/templates/starter-game/testing/e2e/global-setup.ts +7 -18
- package/dist/templates/starter-game/ui/defaults.ts +3 -0
- package/dist/templates/starter-game/ui/src/App.test.tsx +197 -29
- package/dist/templates/starter-game/ui/src/App.tsx +176 -99
- package/dist/templates/starter-game/ui/src/DayBar.test.tsx +50 -7
- package/dist/templates/starter-game/ui/src/DayBar.tsx +96 -38
- package/dist/templates/starter-game/ui/src/DaysTable.tsx +69 -0
- package/dist/templates/starter-game/ui/src/FirstDay.tsx +37 -0
- package/dist/templates/starter-game/ui/src/Header.tsx +257 -0
- package/dist/templates/starter-game/ui/src/Lesson.tsx +63 -0
- package/dist/templates/starter-game/ui/src/MakeRow.tsx +98 -71
- package/dist/templates/starter-game/ui/src/Notices.tsx +59 -0
- package/dist/templates/starter-game/ui/src/PastDay.tsx +88 -0
- package/dist/templates/starter-game/ui/src/Section.tsx +26 -26
- package/dist/templates/starter-game/ui/src/ThemeToggle.tsx +25 -11
- package/dist/templates/starter-game/ui/src/TodayPanel.test.tsx +37 -33
- package/dist/templates/starter-game/ui/src/TodayPanel.tsx +66 -52
- package/dist/templates/starter-game/ui/src/WeatherCard.tsx +47 -0
- package/dist/templates/starter-game/ui/src/WeekOver.tsx +145 -0
- package/dist/templates/starter-game/ui/src/YesterdayPanel.tsx +65 -114
- package/dist/templates/starter-game/ui/src/days.ts +58 -0
- package/dist/templates/starter-game/ui/src/i18n.ts +86 -32
- package/dist/templates/starter-game/ui/src/test-helpers.ts +1 -0
- package/dist/templates/starter-game/ui/src/theme.ts +8 -8
- package/dist/templates/starter-game/ui/types.ts +6 -0
- package/dist/templates/starter-game/ui/ui.sdk.json +1 -1
- package/dist/templates/starter-game/validators/daylimit/defaults.ts +13 -0
- package/dist/templates/starter-game/validators/daylimit/logic/logic.test.ts +20 -0
- package/dist/templates/starter-game/validators/daylimit/logic/logic.ts +23 -0
- package/dist/templates/starter-game/validators/daylimit/types.ts +23 -0
- package/dist/templates/starter-game/validators/daylimit/validator.sdk.json +10 -0
- package/dist/templates/starter-game/waiting_room/src/App.test.tsx +83 -5
- package/dist/templates/starter-game/waiting_room/src/App.tsx +262 -119
- package/dist/templates/starter-game/waiting_room/src/i18n.ts +8 -4
- package/dist/utils/error-codes.d.ts +12 -0
- package/dist/utils/prompt.d.ts +5 -5
- package/dist/utils/resource-scan.d.ts +39 -0
- package/package.json +15 -4
- package/dist/templates/starter-game/session/src/Section.tsx +0 -37
- package/dist/templates/starter-game/session/src/TeamDoor.tsx +0 -96
- package/dist/templates/starter-game/session/src/format.ts +0 -8
- package/dist/templates/starter-game/ui/src/HistoryPanel.test.tsx +0 -74
- package/dist/templates/starter-game/ui/src/HistoryPanel.tsx +0 -120
- package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +0 -25
- package/dist/templates/starter-game/ui/src/HostLogo.tsx +0 -38
|
@@ -6,6 +6,11 @@ It is facilitator-only and works across all teams at once, for session-wide dash
|
|
|
6
6
|
|
|
7
7
|
**Keywords:** manage session, session UI, facilitator UI, session-level, cross-team, multi-team dashboard, facilitator controls, session dashboard, all teams, independent mode, shared-state mode
|
|
8
8
|
|
|
9
|
+
This page covers what a session UI is, creating it, reading and writing session data, and fitting it inside the host. The rest of the reference is split by topic:
|
|
10
|
+
|
|
11
|
+
- **[Running the game](./session-game-flow.md)**: ticks, the timer, host overlays, undo and reset, the waiting room, the language, the roster, and the participant list
|
|
12
|
+
- **[Hooks reference](./session-hooks.md)**: every session UI hook and the messages the host sends
|
|
13
|
+
|
|
9
14
|
## What are session UIs?
|
|
10
15
|
|
|
11
16
|
The session UI is the facilitator's whole-session screen. The host renders it full-bleed beneath a thin band of its own chrome, and it owns everything below that: teams, participants, and game controls. A game wires in at most one, and a package that ships none falls back to the host's own roster page.
|
|
@@ -85,7 +90,7 @@ and listing it in `session/session.sdk.json`:
|
|
|
85
90
|
```
|
|
86
91
|
|
|
87
92
|
The resolved values arrive as `settings` on
|
|
88
|
-
[`useSessionUserInterfaceData`](#usesessionuserinterfacedata), keyed by
|
|
93
|
+
[`useSessionUserInterfaceData`](./session-hooks.md#usesessionuserinterfacedata), keyed by
|
|
89
94
|
settings identifier (`settings.session.ShowJoinLinks`) and typed as the
|
|
90
95
|
generated `Settings` from the session UI's `types.ts`. The surface receives
|
|
91
96
|
exactly the settings it lists, so it can also read the engine's by listing
|
|
@@ -146,7 +151,7 @@ type SessionData = {
|
|
|
146
151
|
};
|
|
147
152
|
```
|
|
148
153
|
|
|
149
|
-
`timer` is the one [`TimerState`](../api/sdk-ui.md#timerstate) shape a game UI reads from `useUserInterfaceTimer()`, so a countdown is drawn as in [Displaying the tick timer](./ui.md#displaying-the-tick-timer).
|
|
154
|
+
`timer` is the one [`TimerState`](../api/sdk-ui.md#timerstate) shape a game UI reads from `useUserInterfaceTimer()`, so a countdown is drawn as in [Displaying the tick timer](./ui-ticks.md#displaying-the-tick-timer).
|
|
150
155
|
|
|
151
156
|
Three notes on that shape. Each `context` carries only the capabilities this session UI declared (see [Capabilities](./capabilities.md#a-declaration-is-what-gets-delivered)), so declare everything the screen renders. A `scope: 'shared'` capability arrives once, in `shared.context`, and never in a team's `context`: read it there rather than off whichever team comes first. And `revision` is how the wrapper tracks updates: on a large session the host sends one team's state (or the shared store) rather than every team's, and the wrapper merges each one into the `SessionData` you read, asking for a fresh snapshot if it notices one went missing. You never need to read it, and you can leave it out of hand-written test fixtures.
|
|
152
157
|
|
|
@@ -324,364 +329,6 @@ function ModeIndicator() {
|
|
|
324
329
|
|
|
325
330
|
In **shared-state** mode, calling `requestTick()` without a `teamId` advances all teams simultaneously. In **independent** mode, you can target individual teams or advance all teams at once: with no `teamId`, every team that can still move advances by one from its own round, so a team that is behind stays behind, and a team that is complete or at the round limit is skipped.
|
|
326
331
|
|
|
327
|
-
## Controlling game flow
|
|
328
|
-
|
|
329
|
-
Session UIs have full control over the game lifecycle via callbacks. Every game-flow callback accepts an optional `teamId`; when it is omitted the action applies to all teams.
|
|
330
|
-
|
|
331
|
-
Every game-flow callback except `pauseTimer` and `resumeTimer` returns a promise that resolves once the host has committed the change, and rejects with a `MutationError` when it will not. Await it when you want to report the outcome honestly; ignore it when you do not. Either way the resulting state arrives through the normal session data channel.
|
|
332
|
-
|
|
333
|
-
### Triggering ticks
|
|
334
|
-
|
|
335
|
-
```typescript
|
|
336
|
-
import { useSessionUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
|
|
337
|
-
import { useSessionUserInterfaceTeams } from '@seriousgaming/sdk/ui';
|
|
338
|
-
import { useSessionUserInterfaceTeamConfiguration } from '@seriousgaming/sdk/ui';
|
|
339
|
-
import { Button, Stack } from '@mui/material';
|
|
340
|
-
|
|
341
|
-
function TickControls() {
|
|
342
|
-
const { requestTick } = useSessionUserInterfaceCallbacks();
|
|
343
|
-
const teams = useSessionUserInterfaceTeams();
|
|
344
|
-
const { mode } = useSessionUserInterfaceTeamConfiguration();
|
|
345
|
-
|
|
346
|
-
return (
|
|
347
|
-
<Stack spacing={1}>
|
|
348
|
-
<Button onClick={() => requestTick()} variant="contained">
|
|
349
|
-
Advance All Teams
|
|
350
|
-
</Button>
|
|
351
|
-
{mode === 'independent' &&
|
|
352
|
-
teams.map((team) => (
|
|
353
|
-
<Button
|
|
354
|
-
key={team.teamId}
|
|
355
|
-
onClick={() => requestTick(team.teamId)}
|
|
356
|
-
variant="outlined"
|
|
357
|
-
>
|
|
358
|
-
Advance {team.name}
|
|
359
|
-
</Button>
|
|
360
|
-
))}
|
|
361
|
-
</Stack>
|
|
362
|
-
);
|
|
363
|
-
}
|
|
364
|
-
```
|
|
365
|
-
|
|
366
|
-
The session UI's `requestTick` control is how facilitators advance the game: there is no built-in next tick button. The scaffolded session UI wires a session-wide tick button out of the box; during development the console's dev drawer also has a developer-only **Tick** button.
|
|
367
|
-
|
|
368
|
-
### Pausing and resuming the timer
|
|
369
|
-
|
|
370
|
-
When a game uses a [tick controller](./tick-controller.md) with automatic ticking, facilitators can pause and resume per-team or globally:
|
|
371
|
-
|
|
372
|
-
```typescript
|
|
373
|
-
import { useSessionUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
|
|
374
|
-
import { Button, Stack } from '@mui/material';
|
|
375
|
-
|
|
376
|
-
function TimerControls({ teamId }: { teamId?: string }) {
|
|
377
|
-
const { pauseTimer, resumeTimer } = useSessionUserInterfaceCallbacks();
|
|
378
|
-
|
|
379
|
-
return (
|
|
380
|
-
<Stack direction="row" spacing={1}>
|
|
381
|
-
<Button onClick={() => pauseTimer(teamId)} variant="outlined" color="warning">
|
|
382
|
-
{teamId ? `Pause ${teamId}` : 'Pause All'}
|
|
383
|
-
</Button>
|
|
384
|
-
<Button onClick={() => resumeTimer(teamId)} variant="contained" color="success">
|
|
385
|
-
{teamId ? `Resume ${teamId}` : 'Resume All'}
|
|
386
|
-
</Button>
|
|
387
|
-
</Stack>
|
|
388
|
-
);
|
|
389
|
-
}
|
|
390
|
-
```
|
|
391
|
-
|
|
392
|
-
While paused, manual ticks via `requestTick` still work. Timer state for each team is available in `sessionData.teams[teamId].timer`.
|
|
393
|
-
|
|
394
|
-
### Extending a tick
|
|
395
|
-
|
|
396
|
-
Pausing is the wrong tool for 'give them two more minutes'. It stops the clock until someone remembers to start it again, and it does not move the deadline your countdown is drawn from. `extendTick` moves the deadline instead. It takes milliseconds:
|
|
397
|
-
|
|
398
|
-
```typescript
|
|
399
|
-
import { useSessionUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
|
|
400
|
-
import { Button, Stack } from '@mui/material';
|
|
401
|
-
|
|
402
|
-
function ExtendControls({ teamId }: { teamId?: string }) {
|
|
403
|
-
const { extendTick } = useSessionUserInterfaceCallbacks();
|
|
404
|
-
|
|
405
|
-
return (
|
|
406
|
-
<Stack direction="row" spacing={1}>
|
|
407
|
-
<Button onClick={() => void extendTick(120_000, teamId)}>+2 min</Button>
|
|
408
|
-
<Button onClick={() => void extendTick(-30_000, teamId)}>-30 sec</Button>
|
|
409
|
-
</Stack>
|
|
410
|
-
);
|
|
411
|
-
}
|
|
412
|
-
```
|
|
413
|
-
|
|
414
|
-
Three things worth knowing:
|
|
415
|
-
|
|
416
|
-
- **It moves one window, not the cadence.** The interval your tick controller returns for later ticks is untouched, so a session does not run permanently late because one tick ran long
|
|
417
|
-
- **A negative value pulls the deadline in**, clamped at now. It never fires a tick retroactively
|
|
418
|
-
- **Read the result back from `extendedMs`** on the team's timer rather than inferring it from a moved `nextTickAt`. A deadline that jumped is equally the signature of a freshly scheduled tick, so `extendedMs` is the only honest source for 'extended by 2m'
|
|
419
|
-
|
|
420
|
-
```typescript
|
|
421
|
-
const { extendedMs } = sessionData.teams[teamId].timer;
|
|
422
|
-
```
|
|
423
|
-
|
|
424
|
-
It rejects with a `MutationError` carrying `{ kind: 'denied' }` when there is no tick to move: automatic ticking is off, the game is complete, or the timer is paused. Resume first, then extend.
|
|
425
|
-
|
|
426
|
-
Deliberately, the [tick interval bounds](./tick-controller.md) do not apply. They bound the cadence a tick controller may schedule; a facilitator in the room already reaches outside both with an immediate `requestTick` and an indefinite `pauseTimer`.
|
|
427
|
-
|
|
428
|
-
### Opening host overlays
|
|
429
|
-
|
|
430
|
-
Some things a facilitator wants are drawn by the host rather than by your game: the [facilitator guide](./guide.md), a team's print sheet, your [presentation](./presentation.md). Your session UI owns the whole canvas, so without a way to ask, a facilitator has to leave it to reach them.
|
|
431
|
-
|
|
432
|
-
`openHostOverlay` asks. The host renders the overlay in its own chrome, over your session UI or in a window of its own, where you can neither restyle nor suppress it. Which is the host's choice: a deck usually gets a window, so the facilitator can put it on the projector and keep your session UI on their own screen:
|
|
433
|
-
|
|
434
|
-
```typescript
|
|
435
|
-
import {
|
|
436
|
-
useSessionUserInterfaceCallbacks,
|
|
437
|
-
useSessionUserInterfaceHostOverlays,
|
|
438
|
-
} from '@seriousgaming/sdk/ui';
|
|
439
|
-
import { Button, Stack } from '@mui/material';
|
|
440
|
-
|
|
441
|
-
function OverlayControls() {
|
|
442
|
-
const overlays = useSessionUserInterfaceHostOverlays();
|
|
443
|
-
const { openHostOverlay } = useSessionUserInterfaceCallbacks();
|
|
444
|
-
|
|
445
|
-
return (
|
|
446
|
-
<Stack direction="row" spacing={1}>
|
|
447
|
-
{overlays.includes('facilitator-guide') && (
|
|
448
|
-
<Button onClick={() => void openHostOverlay('facilitator-guide')}>Guide</Button>
|
|
449
|
-
)}
|
|
450
|
-
{overlays.includes('print-sheets') && (
|
|
451
|
-
<Button onClick={() => void openHostOverlay('print-sheets')}>Print sheets</Button>
|
|
452
|
-
)}
|
|
453
|
-
{overlays.includes('presentation') && (
|
|
454
|
-
<Button onClick={() => void openHostOverlay('presentation')}>Presentation</Button>
|
|
455
|
-
)}
|
|
456
|
-
</Stack>
|
|
457
|
-
);
|
|
458
|
-
}
|
|
459
|
-
```
|
|
460
|
-
|
|
461
|
-
**Always gate on `useSessionUserInterfaceHostOverlays()`.** Which overlays exist is the host's answer, not yours: a production host and the dev server do not offer the same set, and the guide is only available when the active game declares one. A button for an overlay the host does not have is a button that cannot work. The list is empty until the host answers, and it can change when the game is reloaded, for example when a guide is added or removed.
|
|
462
|
-
|
|
463
|
-
The second argument narrows the overlay:
|
|
464
|
-
|
|
465
|
-
| Overlay | Second argument | Omitted means |
|
|
466
|
-
| --------------------- | ------------------------------------------------ | --------------------------------- |
|
|
467
|
-
| `'facilitator-guide'` | None: a game holds one guide, and one is ignored | The game's guide |
|
|
468
|
-
| `'print-sheets'` | A team id | Every team |
|
|
469
|
-
| `'presentation'` | None: a game holds one deck, and one is ignored | The game's deck, for this session |
|
|
470
|
-
|
|
471
|
-
It rejects with a `MutationError` carrying `{ kind: 'denied' }` for an overlay the host does not offer and for a team id that is not in the session.
|
|
472
|
-
|
|
473
|
-
**The presentation needs `presentation-overlay` in `requires`.** A host offers `'presentation'` only to a game that ships a `presentation/` slot and lists the feature in `seriousgaming.sdk.json`:
|
|
474
|
-
|
|
475
|
-
```json
|
|
476
|
-
{
|
|
477
|
-
"requires": ["presentation-overlay"]
|
|
478
|
-
}
|
|
479
|
-
```
|
|
480
|
-
|
|
481
|
-
Listing it means a host that cannot open the deck this way refuses the game rather than running it without the button, so list it only if your session UI offers the control. The deck opens for the current session, on the slide the facilitator left it on.
|
|
482
|
-
|
|
483
|
-
**Prefer the host's print sheets to your own.** A host's sheet carries the brand of the organisation running the session, with its join details in the form the host chose, so offer `'print-sheets'` wherever the host does. Draw your own sheet only where it does not, from [`useSessionUserInterfaceTeamLinks`](#usesessionuserinterfaceteamlinks), and put the host's logo on it with `useBrandLogo()` (see [Theming and branding](./theming-and-branding.md)), so a white-label session never prints your game's identity, or nobody's.
|
|
484
|
-
|
|
485
|
-
### Undoing and resetting
|
|
486
|
-
|
|
487
|
-
Facilitators can revert the last tick or reset games, targeted at a specific team or all teams:
|
|
488
|
-
|
|
489
|
-
```typescript
|
|
490
|
-
import { useSessionUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
|
|
491
|
-
import { Button, Stack } from '@mui/material';
|
|
492
|
-
|
|
493
|
-
function GameControls() {
|
|
494
|
-
const { undoTick, resetGame } = useSessionUserInterfaceCallbacks();
|
|
495
|
-
|
|
496
|
-
return (
|
|
497
|
-
<Stack direction="row" spacing={1}>
|
|
498
|
-
<Button onClick={() => undoTick()} variant="outlined">
|
|
499
|
-
Undo All Teams
|
|
500
|
-
</Button>
|
|
501
|
-
<Button onClick={() => resetGame()} variant="outlined" color="error">
|
|
502
|
-
Reset All Teams
|
|
503
|
-
</Button>
|
|
504
|
-
</Stack>
|
|
505
|
-
);
|
|
506
|
-
}
|
|
507
|
-
```
|
|
508
|
-
|
|
509
|
-
- **`undoTick(teamId?)`** puts teams back on the board they were holding when the last tick was taken, decisions and all: it un-runs the engine rather than re-dealing the tick. When `teamId` is omitted, reverts all teams; naming one is independent mode only, since shared-state teams advance together. With no history to undo, the promise rejects with a `MutationError` whose `outcome.kind` is `denied`
|
|
510
|
-
- **`resetGame(teamId?)`** clears all context, deletes game-scoped blobs, and re-initialises from scratch. When `teamId` is omitted, resets all teams. Settings are preserved
|
|
511
|
-
|
|
512
|
-
Undo lets a team try a round again without penalty, which supports psychological safety: people experiment more freely when a mistake can be taken back.
|
|
513
|
-
|
|
514
|
-
### Opening and closing the waiting room
|
|
515
|
-
|
|
516
|
-
`setWaitingRoom` parks the session: every participant's game UI is replaced with the game's [waiting room UI](./waiting-room.md) until you close it again.
|
|
517
|
-
|
|
518
|
-
```typescript
|
|
519
|
-
const { setWaitingRoom } = useSessionUserInterfaceCallbacks();
|
|
520
|
-
|
|
521
|
-
<Button onClick={() => setWaitingRoom(true)} variant="outlined">
|
|
522
|
-
Open waiting room
|
|
523
|
-
</Button>
|
|
524
|
-
```
|
|
525
|
-
|
|
526
|
-
- **`setWaitingRoom(open)`** takes **no `teamId`**, unlike every other control above. The waiting room is one flag for the whole session, so there is no per-team variant to target
|
|
527
|
-
- Game state is untouched in both directions. Per-team context, the current tick, and timers all survive, which is the point: park a live session for a discussion and resume exactly where teams were
|
|
528
|
-
- It does not stop the clock. Automatic ticks keep firing while participants wait; halting play is the tick controller's decision, via `waitingRoomOpen`
|
|
529
|
-
- It resolves once the host confirms the change and rejects with a `MutationError` otherwise
|
|
530
|
-
|
|
531
|
-
The host provides its own toggle too, so building one is optional. Reach for this when you want the control to sit inside your own facilitator layout, or to pair it with a note you set on a shared capability at the same moment.
|
|
532
|
-
|
|
533
|
-
### Changing the language
|
|
534
|
-
|
|
535
|
-
`setLocale` changes the session's language: the locale every surface is sent, and your logic reads, from then on. It is the change the host's own language picker makes, for a session UI that owns the whole canvas:
|
|
536
|
-
|
|
537
|
-
```typescript
|
|
538
|
-
const meta = useSessionUserInterfaceMeta();
|
|
539
|
-
const { locale } = useSessionUserInterfaceLocale();
|
|
540
|
-
const { setLocale } = useSessionUserInterfaceCallbacks();
|
|
541
|
-
|
|
542
|
-
{meta.canSetLocale && (
|
|
543
|
-
<Select value={locale} onChange={(event) => void setLocale(event.target.value)}>
|
|
544
|
-
<MenuItem value="en">English</MenuItem>
|
|
545
|
-
<MenuItem value="it">Italiano</MenuItem>
|
|
546
|
-
</Select>
|
|
547
|
-
)}
|
|
548
|
-
```
|
|
549
|
-
|
|
550
|
-
- **Gate it on `meta.canSetLocale`.** A host that predates `setLocale` leaves it out, and may never answer the call, so a control shown there would hang
|
|
551
|
-
- **Offer only your `supportedLocales`.** Anything else is refused as `denied`, rather than swapped for the nearest language you do support
|
|
552
|
-
- **Render the locale you are sent**, not the one you asked for. The host's picker changes it too, and the last change wins
|
|
553
|
-
- It takes no `teamId`: the language is the session's
|
|
554
|
-
|
|
555
|
-
### Controlling the roster
|
|
556
|
-
|
|
557
|
-
The session UI owns the roster. Five callbacks create, rename and delete teams, and rename and move participants:
|
|
558
|
-
|
|
559
|
-
```typescript
|
|
560
|
-
const { createTeam, renameTeam, deleteTeam, renameParticipant, moveParticipant } =
|
|
561
|
-
useSessionUserInterfaceCallbacks();
|
|
562
|
-
|
|
563
|
-
await createTeam('Marketing'); // name is optional
|
|
564
|
-
await renameTeam('team-1', 'Sales');
|
|
565
|
-
await renameParticipant('participant-3', 'Sam');
|
|
566
|
-
await moveParticipant('participant-3', 'team-2');
|
|
567
|
-
await deleteTeam('team-3'); // independent mode, empty teams only
|
|
568
|
-
```
|
|
569
|
-
|
|
570
|
-
Each resolves on commit and rejects with a `MutationError`. Three refusals arrive as `{ kind: 'denied' }`: the team count is at the effective maximum, a team is being added to a shared-state session (whose team count is fixed at creation, though the dev server relaxes that before the first tick as an authoring convenience), or the session is read-only. **A denial is terminal**: unlike `conflict`, waiting and re-sending cannot change the outcome, so surface it rather than looping.
|
|
571
|
-
|
|
572
|
-
Creating or erasing a participant is deliberately not exposed.
|
|
573
|
-
|
|
574
|
-
#### Deleting a team
|
|
575
|
-
|
|
576
|
-
`deleteTeam(teamId)` removes a team from an **independent-mode** session. Every runtime supports it, unlike `createTeam`, which a runtime may refuse. It is refused with `{ kind: 'denied' }` when:
|
|
577
|
-
|
|
578
|
-
- The session is shared-state, at any point, before the first tick included. A shared-state engine initialised over the whole cohort, so its team count is fixed for the session
|
|
579
|
-
- The team still has participants, connected or not. A participant is never erased, so move every one out with `moveParticipant` first
|
|
580
|
-
- It is the last team in the session
|
|
581
|
-
- The session does not hold the team, or is read-only
|
|
582
|
-
|
|
583
|
-
A deleted team's index is left as a gap, and no other team's index or id changes. The next `createTeam` takes the lowest free index back, as a new team with the default name: nothing of the deleted team returns with it. Undo never brings a deleted team back, and no hook fires.
|
|
584
|
-
|
|
585
|
-
Offer the control only where it can succeed, so a facilitator is not shown a button the host will refuse:
|
|
586
|
-
|
|
587
|
-
```tsx
|
|
588
|
-
const { mode } = useSessionUserInterfaceTeamConfiguration();
|
|
589
|
-
const participants = useSessionUserInterfaceParticipants();
|
|
590
|
-
const { deleteTeam } = useSessionUserInterfaceCallbacks();
|
|
591
|
-
|
|
592
|
-
{
|
|
593
|
-
mode === 'independent' && (
|
|
594
|
-
<Button
|
|
595
|
-
disabled={teams.length <= 1 || participants.some((p) => p.teamId === team.teamId)}
|
|
596
|
-
onClick={() => void deleteTeam(team.teamId).catch(showDenial)}
|
|
597
|
-
>
|
|
598
|
-
Delete team
|
|
599
|
-
</Button>
|
|
600
|
-
);
|
|
601
|
-
}
|
|
602
|
-
```
|
|
603
|
-
|
|
604
|
-
The host enforces every rule itself, so the disabled state is a convenience, not a guard. In the dev server every team starts with a placeholder participant, so move it out first, or add the team with `pnpm run sdk team add --participants 0`.
|
|
605
|
-
|
|
606
|
-
`renameTeam` is not the only writer. A team's own participants can rename it from a game UI or waiting room UI, so a session UI should render the name from `setTeamList` rather than from its own optimistic state: there is one name per team, not one per writer, and the last write wins. A blank name and one past the host's cap (60 characters) are both refused as terminal denials, for either writer.
|
|
607
|
-
|
|
608
|
-
#### Moving a participant
|
|
609
|
-
|
|
610
|
-
A move has a consequence worth designing for, and one that is easy to confuse it with:
|
|
611
|
-
|
|
612
|
-
- The participant's **browser loses local component state**, because their game UI remounts against the destination team. Ordinary remount behaviour, and rarely worth warning anyone about
|
|
613
|
-
- Their **earlier writes stay with the source team**. Anything they wrote through `setData` is in that team's context and does not travel, so they arrive with none of their own state
|
|
614
|
-
|
|
615
|
-
A move does not reset either team. The source team's context, including every pending pre-tick decision in it, is untouched.
|
|
616
|
-
|
|
617
|
-
The second consequence is what a game handles, and the mechanism is the [`participantMove` hook](./hooks.md): seed the destination on `phase: 'arrival'` the way `participantJoin` seeds a new participant. There is no transfer channel: a hook returns one team's context, so the departure hook's return value is invisible to arrival. A shared-state game carries state across through the shared store; an independent-mode game re-derives it. Warning a facilitator is the fallback for the case where it genuinely cannot be re-derived, not the default: they cannot implement a hook mid-session, so the warning is only useful where you already know re-seeding is impossible.
|
|
618
|
-
|
|
619
|
-
## Working with participants
|
|
620
|
-
|
|
621
|
-
Session UIs can enumerate participants across all teams in the session. The hook uses the `Participant` type, which includes a `teamId` field for grouping participants by team.
|
|
622
|
-
|
|
623
|
-
### Reading the participant list
|
|
624
|
-
|
|
625
|
-
```typescript
|
|
626
|
-
import {
|
|
627
|
-
useSessionUserInterfaceParticipants,
|
|
628
|
-
type Participant,
|
|
629
|
-
} from '@seriousgaming/sdk/ui';
|
|
630
|
-
import { List, ListItem, ListItemText, Chip, Typography, Stack } from '@mui/material';
|
|
631
|
-
|
|
632
|
-
function AllParticipantsPanel() {
|
|
633
|
-
const participants = useSessionUserInterfaceParticipants();
|
|
634
|
-
|
|
635
|
-
// Group by team
|
|
636
|
-
const byTeam = participants.reduce<Record<string, Participant[]>>(
|
|
637
|
-
(acc, p) => {
|
|
638
|
-
(acc[p.teamId] ??= []).push(p);
|
|
639
|
-
return acc;
|
|
640
|
-
},
|
|
641
|
-
{}
|
|
642
|
-
);
|
|
643
|
-
|
|
644
|
-
return (
|
|
645
|
-
<>
|
|
646
|
-
{Object.entries(byTeam).map(([teamId, members]) => (
|
|
647
|
-
<div key={teamId}>
|
|
648
|
-
<Typography variant="h6">{teamId}</Typography>
|
|
649
|
-
<List>
|
|
650
|
-
{members.map((p) => (
|
|
651
|
-
<ListItem key={p.id}>
|
|
652
|
-
<ListItemText
|
|
653
|
-
primary={p.name}
|
|
654
|
-
/>
|
|
655
|
-
<Chip
|
|
656
|
-
size="small"
|
|
657
|
-
label={p.connected ? 'Online' : 'Offline'}
|
|
658
|
-
color={p.connected ? 'success' : 'default'}
|
|
659
|
-
/>
|
|
660
|
-
</ListItem>
|
|
661
|
-
))}
|
|
662
|
-
</List>
|
|
663
|
-
</div>
|
|
664
|
-
))}
|
|
665
|
-
</>
|
|
666
|
-
);
|
|
667
|
-
}
|
|
668
|
-
```
|
|
669
|
-
|
|
670
|
-
The hook updates reactively whenever:
|
|
671
|
-
|
|
672
|
-
- A new participant joins any team
|
|
673
|
-
- A participant disconnects (`connected` flips to `false`; the entry stays so you can see who was here)
|
|
674
|
-
|
|
675
|
-
`Participant` exposes:
|
|
676
|
-
|
|
677
|
-
| Field | Type | Notes |
|
|
678
|
-
| ----------- | --------- | ------------------------------------------------------- |
|
|
679
|
-
| `id` | `string` | Stable identifier; survives reconnects within a session |
|
|
680
|
-
| `name` | `string` | Display name (defaults to `Participant N`) |
|
|
681
|
-
| `index` | `number` | Zero-based join order within the team |
|
|
682
|
-
| `connected` | `boolean` | Whether the participant has a live platform connection |
|
|
683
|
-
| `teamId` | `string` | The team this participant belongs to (e.g. `"team-1"`) |
|
|
684
|
-
|
|
685
332
|
## Rendering inside the host
|
|
686
333
|
|
|
687
334
|
A session UI is not a standalone page. The host mounts it in an iframe under a thin band of its own chrome, and that changes several things a full-page layout takes for granted. None of it is enforced, and all of it is visible to a facilitator the moment it goes wrong.
|
|
@@ -706,12 +353,27 @@ const TRANSPARENT_BODY = { body: { backgroundColor: 'transparent' } };
|
|
|
706
353
|
|
|
707
354
|
Paint backgrounds on the things that are meant to look raised, like cards and panels, not on the page.
|
|
708
355
|
|
|
709
|
-
###
|
|
356
|
+
### Avoid dialogs with a backdrop
|
|
357
|
+
|
|
358
|
+
On the platform, your session UI sits in an iframe under the host's own bar. A modal dialog is centred in the frame rather than the screen, and its backdrop darkens only the frame. The host's bar above stays bright, so the page looks broken rather than paused. Reach for something that needs no backdrop:
|
|
710
359
|
|
|
711
|
-
A
|
|
360
|
+
- **A side panel for detail.** Managing one team, reading one team's notes: a panel that slides in from the edge over the content without dimming it. The rest of the screen stays where it was, which matters to a facilitator who is pointing at it
|
|
361
|
+
- **A confirmation beside the button that asked.** An 'are you sure?' anchored to the control, as a popover or a row that replaces the button, rather than a dialog in the middle of the screen
|
|
362
|
+
- **Full screen for what the room looks at.** Join codes or results on the projector cover the whole frame, so there is no edge for a backdrop to stop at
|
|
712
363
|
|
|
713
364
|
```tsx
|
|
714
|
-
|
|
365
|
+
// Detail: slides in from the right and dims nothing
|
|
366
|
+
<Drawer anchor="right" open={open} onClose={close} hideBackdrop>
|
|
367
|
+
…
|
|
368
|
+
</Drawer>
|
|
369
|
+
|
|
370
|
+
// Are you sure?: anchored to the button that asked
|
|
371
|
+
<Popover open={confirming} anchorEl={undoButton} onClose={cancel}>
|
|
372
|
+
…
|
|
373
|
+
</Popover>
|
|
374
|
+
|
|
375
|
+
// For the room: covers the whole frame
|
|
376
|
+
<Dialog open={showingCodes} onClose={close} fullScreen>
|
|
715
377
|
…
|
|
716
378
|
</Dialog>
|
|
717
379
|
```
|
|
@@ -722,7 +384,7 @@ The same applies to anything anchored to the viewport. A toast pinned to the top
|
|
|
722
384
|
|
|
723
385
|
The Game view / Platform view toggle, the language picker, the theme control, and the guide button all live in the chrome above your session UI. A second copy inside it looks like the same control and is not: yours cannot switch the host's view, and two language menus on one screen is a bug report waiting to happen.
|
|
724
386
|
|
|
725
|
-
When you want one of the host's own overlays, ask for it with [`openHostOverlay`](#opening-host-overlays) rather than rebuilding it.
|
|
387
|
+
When you want one of the host's own overlays, ask for it with [`openHostOverlay`](./session-game-flow.md#opening-host-overlays) rather than rebuilding it.
|
|
726
388
|
|
|
727
389
|
### Own your internal scroll
|
|
728
390
|
|
|
@@ -765,7 +427,7 @@ When you run `pnpm run sdk dev` for a game with session UIs:
|
|
|
765
427
|
|
|
766
428
|
1. Your session UI **is** the console. The dev server renders it full-bleed in its canvas, under a band of chrome, and opens on it by default whenever the package ships one
|
|
767
429
|
2. The chrome's **Game view / Platform view** toggle switches between your session UI and the dev server's own roster page, which is the fallback for a package that ships no session UI. It sits outside your iframe, so your session UI cannot suppress it
|
|
768
|
-
3. The chrome also carries the language picker, the theme control, the facilitator guide and print sheets, the scenario and setup entries, and undo / reset / reload. Do not rebuild these inside your session UI; to open the guide or a print sheet, use [`openHostOverlay`](#opening-host-overlays)
|
|
430
|
+
3. The chrome also carries the language picker, the theme control, the facilitator guide and print sheets, the scenario and setup entries, and undo / reset / reload. Do not rebuild these inside your session UI; to open the guide or a print sheet, use [`openHostOverlay`](./session-game-flow.md#opening-host-overlays)
|
|
769
431
|
4. The route `/session` also works directly, which is useful for iterating on the session UI alone. Opened that way there is no chrome above it, so a host overlay opens in a new tab rather than in a dialog
|
|
770
432
|
5. Any `setData` calls from the UI iframe are immediately forwarded to the dev server and reflected in the relevant team's game UI
|
|
771
433
|
|
|
@@ -795,206 +457,6 @@ pnpm run sdk delete session
|
|
|
795
457
|
|
|
796
458
|
`renderSessionUserInterface` from `@seriousgaming/sdk/ui/testing` renders a session UI with every provider it reads, seeded with `createMockTeamState` and `createMockSharedState`: see [Session UIs](./testing.md#session-uis) in the testing guide.
|
|
797
459
|
|
|
798
|
-
## Hooks reference
|
|
799
|
-
|
|
800
|
-
### useSessionUserInterfaceData
|
|
801
|
-
|
|
802
|
-
Read session-wide data and write per-team overrides:
|
|
803
|
-
|
|
804
|
-
```typescript
|
|
805
|
-
import { useSessionUserInterfaceData } from '@seriousgaming/sdk/ui';
|
|
806
|
-
|
|
807
|
-
const { sessionData, settings, setData } = useSessionUserInterfaceData();
|
|
808
|
-
// sessionData: SessionData, the shared store once (shared.context), and a teams map with each team's own context, tick, and timer
|
|
809
|
-
// setData(partial): writes shared capabilities session-wide
|
|
810
|
-
// settings: the settings resources this surface lists in `settings`, keyed by identifier (see Configuring the surface)
|
|
811
|
-
// setData(teamId, partial): merges partial context into the specified team's state
|
|
812
|
-
// Both forms take { deletes } last: setData(teamId, {}, { deletes: ['pinboard.Notes.p1'] })
|
|
813
|
-
```
|
|
814
|
-
|
|
815
|
-
### useSessionUserInterfaceTeams
|
|
816
|
-
|
|
817
|
-
Get the team list:
|
|
818
|
-
|
|
819
|
-
```typescript
|
|
820
|
-
import { useSessionUserInterfaceTeams } from '@seriousgaming/sdk/ui';
|
|
821
|
-
|
|
822
|
-
const teams = useSessionUserInterfaceTeams();
|
|
823
|
-
// TeamInfo[]: an array of { teamId, index, name }, sorted by index
|
|
824
|
-
```
|
|
825
|
-
|
|
826
|
-
### useSessionUserInterfaceTeamConfiguration
|
|
827
|
-
|
|
828
|
-
Get the interaction mode and the bounds the host will hold the session UI to:
|
|
829
|
-
|
|
830
|
-
```typescript
|
|
831
|
-
import { useSessionUserInterfaceTeamConfiguration } from '@seriousgaming/sdk/ui';
|
|
832
|
-
|
|
833
|
-
const { mode, min, max, perTeam } = useSessionUserInterfaceTeamConfiguration();
|
|
834
|
-
// mode: 'independent' | 'shared-state'
|
|
835
|
-
// max: the effective maximum team count, already resolved as the lower of the
|
|
836
|
-
// game's declared maximum and the platform's own ceiling
|
|
837
|
-
// min, perTeam: advisory guidance to display, not rules to block on
|
|
838
|
-
```
|
|
839
|
-
|
|
840
|
-
Every bound here is for rendering honest affordances. The host enforces all of them itself, so a surface that disables 'add team' at the maximum is being polite, not authoritative, and must still handle a denial.
|
|
841
|
-
|
|
842
|
-
### useSessionUserInterfaceMeta
|
|
843
|
-
|
|
844
|
-
Read the session itself:
|
|
845
|
-
|
|
846
|
-
```typescript
|
|
847
|
-
import { useSessionUserInterfaceMeta } from '@seriousgaming/sdk/ui';
|
|
848
|
-
|
|
849
|
-
const { sessionId, name, readOnly, waitingRoomOpen, joinPin, canSetLocale } =
|
|
850
|
-
useSessionUserInterfaceMeta();
|
|
851
|
-
```
|
|
852
|
-
|
|
853
|
-
`canSetLocale` is `true` where the host accepts [`setLocale`](#changing-the-language), and absent on a host that predates it.
|
|
854
|
-
|
|
855
|
-
`joinPin` is the code participants enter to join, or `null` when joining needs none. How joining is secured is up to the runtime, so it need not be a PIN and some runtimes never set it: render it as an opaque string, and hide the panel when it is `null`. `readOnly` marks a frozen session, so a surface can disable its own controls and explain why rather than offering affordances that will be denied. `waitingRoomOpen` is the current value of a flag the session UI can also write through `setWaitingRoom`; since the host usually renders its own waiting-room control too, read the result back rather than assuming your write won.
|
|
856
|
-
|
|
857
|
-
### useSessionUserInterfaceTeamLinks
|
|
858
|
-
|
|
859
|
-
Get each team's facilitator-only URLs, so a game draws its own QR codes, and its own join sheets where the host offers no `'print-sheets'` overlay (see [Opening host overlays](#opening-host-overlays)):
|
|
860
|
-
|
|
861
|
-
```typescript
|
|
862
|
-
import { useSessionUserInterfaceTeamLinks } from '@seriousgaming/sdk/ui';
|
|
863
|
-
|
|
864
|
-
const teamLinks = useSessionUserInterfaceTeamLinks();
|
|
865
|
-
// TeamLinks[]: each { teamId, joinUrl, fallbackJoinUrl?, observeUrl }
|
|
866
|
-
```
|
|
867
|
-
|
|
868
|
-
Encode `joinUrl` in a QR code: the host chose that form because a denser code is harder to scan across a room. Show `fallbackJoinUrl` on request rather than beside it, for the networks that block URL shorteners. `observeUrl` opens the team's game UI as an observer, with no participant identity and no presence.
|
|
869
|
-
|
|
870
|
-
### useSessionUserInterfaceHostOverlays
|
|
871
|
-
|
|
872
|
-
Find out which host overlays this host offers, before rendering a control for one:
|
|
873
|
-
|
|
874
|
-
```typescript
|
|
875
|
-
import { useSessionUserInterfaceHostOverlays } from '@seriousgaming/sdk/ui';
|
|
876
|
-
|
|
877
|
-
const overlays = useSessionUserInterfaceHostOverlays();
|
|
878
|
-
// HostOverlay[]: 'facilitator-guide' | 'print-sheets' | 'presentation'
|
|
879
|
-
```
|
|
880
|
-
|
|
881
|
-
Empty until the host answers, and empty is also the correct answer for a host that delegates none. It can change mid-session. See [Opening host overlays](#opening-host-overlays).
|
|
882
|
-
|
|
883
|
-
### useSessionUserInterfaceHookFailures
|
|
884
|
-
|
|
885
|
-
Report hook chains that threw, on the surface the facilitator is actually looking at:
|
|
886
|
-
|
|
887
|
-
```typescript
|
|
888
|
-
import { useSessionUserInterfaceHookFailures } from '@seriousgaming/sdk/ui';
|
|
889
|
-
|
|
890
|
-
const { failures, clearFailures } = useSessionUserInterfaceHookFailures();
|
|
891
|
-
// failures: { signal, teamId, message }[], kept until cleared
|
|
892
|
-
```
|
|
893
|
-
|
|
894
|
-
A hook failure is deliberately not a failed mutation: hooks fire after the change they react to is applied, so the mutation that triggered them has already settled. Reporting it as failed would invite retrying an action that worked.
|
|
895
|
-
|
|
896
|
-
### useSessionUserInterfaceLocale
|
|
897
|
-
|
|
898
|
-
Get the current locale:
|
|
899
|
-
|
|
900
|
-
```typescript
|
|
901
|
-
import { useSessionUserInterfaceLocale } from '@seriousgaming/sdk/ui';
|
|
902
|
-
|
|
903
|
-
const { locale } = useSessionUserInterfaceLocale();
|
|
904
|
-
```
|
|
905
|
-
|
|
906
|
-
### useSessionUserInterfaceTheme
|
|
907
|
-
|
|
908
|
-
Read the host's colour scheme and palettes (`{ mode, light, dark }`, the same shape as the game UI's theme). See [Using the theme](#using-the-theme) for turning it into an MUI theme:
|
|
909
|
-
|
|
910
|
-
```typescript
|
|
911
|
-
import { useSessionUserInterfaceTheme } from '@seriousgaming/sdk/ui';
|
|
912
|
-
|
|
913
|
-
function MyComponent() {
|
|
914
|
-
const theme = useSessionUserInterfaceTheme();
|
|
915
|
-
const colours = theme.mode === 'light' ? theme.light : theme.dark;
|
|
916
|
-
return <div style={{ color: colours.primary }}>Session Dashboard</div>;
|
|
917
|
-
}
|
|
918
|
-
```
|
|
919
|
-
|
|
920
|
-
### useSessionUserInterfaceParticipants
|
|
921
|
-
|
|
922
|
-
Reactive list of participants across all teams in the session:
|
|
923
|
-
|
|
924
|
-
```typescript
|
|
925
|
-
import { useSessionUserInterfaceParticipants } from '@seriousgaming/sdk/ui';
|
|
926
|
-
|
|
927
|
-
function Roster() {
|
|
928
|
-
const participants = useSessionUserInterfaceParticipants();
|
|
929
|
-
return <div>{participants.length} participants across all teams</div>;
|
|
930
|
-
}
|
|
931
|
-
```
|
|
932
|
-
|
|
933
|
-
Use this to enumerate participants for facilitator workflows like cross-team comparisons or session-wide reporting. See [Working with participants](#working-with-participants) above for the full field reference.
|
|
934
|
-
|
|
935
|
-
### useSessionUserInterfaceCallbacks
|
|
936
|
-
|
|
937
|
-
Session-level facilitator callbacks. This is a standalone interface (`SessionUserInterfaceCallbacks`): it does not extend `UserInterfaceCallbacks`. All game-flow callbacks accept an optional `teamId` parameter; omitting it targets all teams.
|
|
938
|
-
|
|
939
|
-
```typescript
|
|
940
|
-
import { useSessionUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
|
|
941
|
-
|
|
942
|
-
const { requestTick, pauseTimer, resumeTimer, undoTick, resetGame } =
|
|
943
|
-
useSessionUserInterfaceCallbacks();
|
|
944
|
-
```
|
|
945
|
-
|
|
946
|
-
| Callback | Signature | Description |
|
|
947
|
-
| -------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
948
|
-
| `requestTick` | `(teamId?: string) => Promise<void>` | Advance the game by one tick; omit `teamId` to advance all teams |
|
|
949
|
-
| `pauseTimer` | `(teamId?: string) => Promise<void>` | Pause automatic ticking; omit `teamId` to pause all teams |
|
|
950
|
-
| `resumeTimer` | `(teamId?: string) => Promise<void>` | Resume automatic ticking; omit `teamId` to resume all teams |
|
|
951
|
-
| `undoTick` | `(teamId?: string) => Promise<void>` | Un-run the last tick, keeping the tick's decisions; omit `teamId` to undo all teams. Naming one is independent mode only |
|
|
952
|
-
| `resetGame` | `(teamId?: string) => Promise<void>` | Re-initialise the game from scratch; omit `teamId` to reset all teams |
|
|
953
|
-
| `getPastState` | `(query) => Promise<PastStateEntry[]>` | Read committed past rounds; `teams` defaults to every team, or name one team by id |
|
|
954
|
-
| `extendTick` | `(byMs, teamId?) => Promise<void>` | Move the currently scheduled tick's deadline by `byMs` milliseconds; negative pulls it in |
|
|
955
|
-
| `openHostOverlay` | `(overlay, target?) => Promise<void>` | Ask the host to open the guide or a print sheet |
|
|
956
|
-
| `uploadBlob` | `(file: File) => Promise<string>` | Upload a file, returns a `blob:<id>` reference |
|
|
957
|
-
| `getAssetUrl` | `(reference: string) => string` | Resolve an `asset:`, `shared:`, or `blob:` reference to a URL |
|
|
958
|
-
| `readAsset` | `(reference: string) => Promise<{ data, mimeType, name }>` | Read bytes for an `asset:`, `shared:`, or `blob:` reference |
|
|
959
|
-
| `endpoints` | `Record<string, (request) => Promise<Response>>` | Call a declared endpoint by identifier |
|
|
960
|
-
| `setWaitingRoom` | `(open: boolean) => Promise<void>` | Open or close the session's waiting room; no `teamId` |
|
|
961
|
-
| `resetWalkthrough` | `() => Promise<void>` | Throw the walkthrough away and restart it at tick 0; rejects while the session has no walkthrough |
|
|
962
|
-
| `createTeam` | `(name?: string) => Promise<void>` | Add a team; the host assigns the index |
|
|
963
|
-
| `renameTeam` | `(teamId, name) => Promise<void>` | Rename a team |
|
|
964
|
-
| `renameParticipant` | `(participantId, name) => Promise<void>` | Rename a participant; the host resolves their team |
|
|
965
|
-
| `moveParticipant` | `(participantId, teamId) => Promise<void>` | Reassign a participant to another team |
|
|
966
|
-
| `deleteTeam` | `(teamId) => Promise<void>` | Delete an empty team; independent mode only, and never the last team |
|
|
967
|
-
| `setThemePreference` | `(preference: ThemePreference) => void` | Set the host's theme preference |
|
|
968
|
-
|
|
969
|
-
The promise-returning callbacks resolve and reject as described in [Controlling game flow](#controlling-game-flow). The wrapper supplies every callback, so none needs an optional-chaining guard.
|
|
970
|
-
|
|
971
|
-
To generate text, extract document text, or synthesise speech, declare an [endpoint](../recipes/create-endpoint.md) that wraps `generateText`, `extractText`, or `generateSpeech`, then call it through `callbacks.endpoints['…']`. These callbacks are not exposed to UI iframes. See [Call an endpoint from a UI](../recipes/call-endpoint-from-ui.md).
|
|
972
|
-
|
|
973
|
-
### Message protocol
|
|
974
|
-
|
|
975
|
-
The `SessionUserInterfaceWrapper` holds the fallback until every required message has arrived:
|
|
976
|
-
|
|
977
|
-
| Required message | Description |
|
|
978
|
-
| ---------------------- | ------------------------------------------------ |
|
|
979
|
-
| `setSessionData` | The shared store and all teams' state |
|
|
980
|
-
| `setSessionMeta` | Session identity and lifecycle state |
|
|
981
|
-
| `setSettings` | The settings this session UI declares, resolved |
|
|
982
|
-
| `setTheme` | Colour scheme and palettes |
|
|
983
|
-
| `setLocale` | Current locale string |
|
|
984
|
-
| `setAssetUrls` | Prefixes for resolving asset and blob references |
|
|
985
|
-
| `setTeamConfiguration` | Interaction mode and team bounds |
|
|
986
|
-
|
|
987
|
-
`setTeamConfiguration` gates first paint because its default cannot be rendered honestly: a surface painting before bounds arrive would hold a maximum of zero and disable the controls that read it.
|
|
988
|
-
|
|
989
|
-
Additional messages sent after initialisation:
|
|
990
|
-
|
|
991
|
-
| Additional message | Description |
|
|
992
|
-
| -------------------- | -------------------------------------------------------------------------------------------------------- |
|
|
993
|
-
| `setTeamList` | Updates the list of teams in the session (`TeamInfo[]`, each `{ teamId, index, name }`, sorted by index) |
|
|
994
|
-
| `setTeamLinks` | Updates each team's facilitator-only join and observe URLs |
|
|
995
|
-
| `setParticipantList` | Updates the participant roster across all teams |
|
|
996
|
-
| `hookFailed` | Reports a hook chain that threw |
|
|
997
|
-
|
|
998
460
|
## Examples
|
|
999
461
|
|
|
1000
462
|
The session UI follows the same file structure conventions as other UI resource types. The starter game's `session/` is a complete one: per-team status, join and observe links, a shared briefing, and the waiting room and guide toggles (see [A tour of the starter game](./starter-game.md#session)).
|