@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
|
@@ -0,0 +1,328 @@
|
|
|
1
|
+
# Files and LLMs in user interfaces
|
|
2
|
+
|
|
3
|
+
How a game UI links to static assets, uploads and shows files, reads an asset's contents, and reaches an LLM through an endpoint to build a chat.
|
|
4
|
+
|
|
5
|
+
It is part of [Building user interfaces](./ui.md), which covers creating the surface and reading and writing context.
|
|
6
|
+
|
|
7
|
+
**Keywords:** static assets, assetUrl, file upload, uploadFile, blob, read asset, LLM, generateText, chat UI, callEndpoint, EndpointError, markdown
|
|
8
|
+
|
|
9
|
+
## Linking to static assets
|
|
10
|
+
|
|
11
|
+
User interfaces run inside an iframe served at a nested path (e.g.,
|
|
12
|
+
`/user-interfaces/ui/`). Because of this, **absolute URLs
|
|
13
|
+
like `/my-file.pdf` will not resolve to your assets**: they escape the iframe
|
|
14
|
+
and hit the shell app's origin instead.
|
|
15
|
+
|
|
16
|
+
Always use **relative paths** when linking to files in your UI's directory:
|
|
17
|
+
|
|
18
|
+
```typescript
|
|
19
|
+
// Wrong: escapes the iframe, loads the shell app's index.html
|
|
20
|
+
window.open('/Briefing.pdf');
|
|
21
|
+
|
|
22
|
+
// Correct: resolves relative to your UI's index.html
|
|
23
|
+
window.open('./Briefing.pdf');
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
This applies to any reference from your UI code to static files: `<a href>`,
|
|
27
|
+
`<img src>`, `<embed src>`, `window.open()`, `fetch()`, etc. The same rule
|
|
28
|
+
holds in both the dev server and production builds.
|
|
29
|
+
|
|
30
|
+
In production your UI also runs under a strict content security policy: every
|
|
31
|
+
asset must be bundled into your build (no external CDNs, no Google Fonts, no
|
|
32
|
+
blob-URL workers), and outbound network calls go through an engine, an endpoint,
|
|
33
|
+
or a host capability. The dev server mirrors this policy, so violations
|
|
34
|
+
surface locally. See [Production security constraints](./production-constraints.md)
|
|
35
|
+
for the full policy and the do's and don'ts.
|
|
36
|
+
|
|
37
|
+
**Where to put static files:** Place them in your UI's directory alongside
|
|
38
|
+
`index.html` (or in a subdirectory). For the default scaffold structure, that
|
|
39
|
+
means inside `ui/`:
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
ui/
|
|
43
|
+
├── index.html
|
|
44
|
+
├── Briefing.pdf ← ./Briefing.pdf
|
|
45
|
+
├── public/
|
|
46
|
+
│ └── logo.png ← ./public/logo.png
|
|
47
|
+
└── src/
|
|
48
|
+
└── App.tsx
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## File uploads
|
|
52
|
+
|
|
53
|
+
User interfaces can upload files (PDFs, images, CSV, etc.) using the `uploadBlob` callback and display them using `getAssetUrl`. Uploaded files and scenario-bundled files share a single asset reference scheme (see [Asset references](../guides/file-handling.md#asset-references) for the full picture).
|
|
54
|
+
|
|
55
|
+
### Uploading a file
|
|
56
|
+
|
|
57
|
+
```typescript
|
|
58
|
+
import { useUserInterfaceCallbacks, useUserInterfaceData } from '@seriousgaming/sdk/ui';
|
|
59
|
+
import type { Context, Settings } from '../types';
|
|
60
|
+
|
|
61
|
+
function DocumentUpload() {
|
|
62
|
+
const callbacks = useUserInterfaceCallbacks();
|
|
63
|
+
const { setData } = useUserInterfaceData<Context, Settings>();
|
|
64
|
+
const [isUploading, setIsUploading] = useState(false);
|
|
65
|
+
|
|
66
|
+
const handleUpload = async (e: React.ChangeEvent<HTMLInputElement>) => {
|
|
67
|
+
const file = e.target.files?.[0];
|
|
68
|
+
if (!file || !callbacks.uploadBlob) return;
|
|
69
|
+
|
|
70
|
+
try {
|
|
71
|
+
setIsUploading(true);
|
|
72
|
+
const reference = await callbacks.uploadBlob(file);
|
|
73
|
+
setData({ 'upload': { DocumentRef: reference } });
|
|
74
|
+
} finally {
|
|
75
|
+
setIsUploading(false);
|
|
76
|
+
e.target.value = '';
|
|
77
|
+
}
|
|
78
|
+
};
|
|
79
|
+
|
|
80
|
+
return (
|
|
81
|
+
<input type="file" accept=".pdf,.csv,.txt" onChange={handleUpload} disabled={isUploading} />
|
|
82
|
+
);
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
The capability holding the reference must be listed in the UI's `writes`. The maximum file size is **20 MB**.
|
|
87
|
+
|
|
88
|
+
### Displaying a file
|
|
89
|
+
|
|
90
|
+
Use `useAssetUrl` to get a URL suitable for `<img>`, `<embed>`, or `<video>`. It resolves uploaded blobs and scenario-bundled assets alike, and returns `undefined` for an absent reference, so there is nothing to guard:
|
|
91
|
+
|
|
92
|
+
```typescript
|
|
93
|
+
import { useAssetUrl } from '@seriousgaming/sdk/ui';
|
|
94
|
+
|
|
95
|
+
function DocumentViewer() {
|
|
96
|
+
const { data } = useUserInterfaceData<Context, Settings>();
|
|
97
|
+
const src = useAssetUrl(data.upload?.DocumentRef);
|
|
98
|
+
if (!src) return null;
|
|
99
|
+
|
|
100
|
+
return (
|
|
101
|
+
<embed
|
|
102
|
+
src={src}
|
|
103
|
+
type="application/pdf"
|
|
104
|
+
style={{ width: '100%', height: '500px', border: 'none' }}
|
|
105
|
+
/>
|
|
106
|
+
);
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
The capability holding the reference must be listed in the UI's `reads`. `useAssetUrl` works on every surface; the `getAssetUrl` callback does the same job outside a component.
|
|
111
|
+
|
|
112
|
+
For the full reference, including engine access via `readAsset`, blob scopes, CLI upload, and supported file types, see [File handling](./file-handling.md).
|
|
113
|
+
|
|
114
|
+
## Reading an asset's contents
|
|
115
|
+
|
|
116
|
+
To render what is in a file rather than link to it, such as a briefing, a JSON table of scenario prose, or a CSV, use `useAsset`. It fetches the asset, reads the body `as` `'json'`, `'text'` or `'blob'`, and returns `{ data, error, loading }`:
|
|
117
|
+
|
|
118
|
+
```tsx
|
|
119
|
+
import { useAsset } from '@seriousgaming/sdk/ui';
|
|
120
|
+
|
|
121
|
+
function Briefing() {
|
|
122
|
+
const { data, error, loading } = useAsset('shared:briefing/briefing.md', { as: 'text' });
|
|
123
|
+
if (loading) return <Spinner />;
|
|
124
|
+
if (error) return <Alert>{error.message}</Alert>;
|
|
125
|
+
return <Markdown>{data}</Markdown>;
|
|
126
|
+
}
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
It prefers a copy in the surface's locale, held in a directory named for the locale just before the file name, and falls back to the reference as given. In `fr-CA`, `shared:briefing/briefing.md` tries `shared:briefing/fr-CA/briefing.md`, then `shared:briefing/fr/briefing.md`, then `shared:briefing/briefing.md` (a locale with a script, such as `zh-Hant-TW`, tries `zh-Hant` before `zh`):
|
|
130
|
+
|
|
131
|
+
```
|
|
132
|
+
shared-assets/
|
|
133
|
+
briefing/
|
|
134
|
+
briefing.md ← the untranslated text, and the fallback
|
|
135
|
+
fr/briefing.md
|
|
136
|
+
ar/briefing.md
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Pass `locale` to look in a different one, or `locale: false` to read the reference alone. A `blob:` reference is always read as given. The hook refetches when the reference or the locale changes, so it follows a mid-session language switch, and an answer to a reference that has since changed is discarded. For JSON, give the type: `useAsset<Briefing>(reference, { as: 'json' })`.
|
|
140
|
+
|
|
141
|
+
## Using LLMs in user interfaces
|
|
142
|
+
|
|
143
|
+
User interfaces cannot call `generateText` (or `extractText` or `generateSpeech`) directly. A UI reaches these services through an [endpoint](./endpoints.md): the endpoint wraps the callback and runs server-side, and the UI invokes it through `callbacks.endpoints['<endpoint-id>']`. This keeps credential-holding calls off the untrusted iframe. To create one, follow [Create an endpoint](../recipes/create-endpoint.md). See [Call an endpoint from a UI](../recipes/call-endpoint-from-ui.md) and the [LLM integration guide](llm-integration.md) for the full pattern.
|
|
144
|
+
|
|
145
|
+
### The endpoint
|
|
146
|
+
|
|
147
|
+
The endpoint bundle declares `"uses": ["generateText"]` and runs the LLM call:
|
|
148
|
+
|
|
149
|
+
```typescript
|
|
150
|
+
// endpoints/chat/logic/logic.ts
|
|
151
|
+
import { getText } from '@seriousgaming/sdk';
|
|
152
|
+
import type { Handler } from '../types';
|
|
153
|
+
|
|
154
|
+
export const Handle: Handler = async ({ request, callbacks }) => {
|
|
155
|
+
const response = await callbacks.generateText({
|
|
156
|
+
messages: request.messages,
|
|
157
|
+
systemPrompt:
|
|
158
|
+
request.systemPrompt ?? 'You are a helpful business advisor. Provide concise guidance.',
|
|
159
|
+
});
|
|
160
|
+
return { reply: getText(response) };
|
|
161
|
+
};
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
The UI bundle declares the endpoint in its `endpoints` array. A UI bundle has no `uses` field, and the build refuses one.
|
|
165
|
+
|
|
166
|
+
```json
|
|
167
|
+
{
|
|
168
|
+
"definition": {
|
|
169
|
+
"endpoints": ["chat"]
|
|
170
|
+
},
|
|
171
|
+
"rootDirectory": ".",
|
|
172
|
+
"ui": { "entrypoint": "index.html" }
|
|
173
|
+
}
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
### Calling the endpoint from a component
|
|
177
|
+
|
|
178
|
+
Access `callbacks.endpoints` with the `useUserInterfaceCallbacks` hook. Persist the conversation in a capability so it survives across ticks:
|
|
179
|
+
|
|
180
|
+
```tsx
|
|
181
|
+
import { useState } from 'react';
|
|
182
|
+
import { useUserInterfaceCallbacks, useUserInterfaceData } from '@seriousgaming/sdk/ui';
|
|
183
|
+
import type { Context, Settings } from '../types';
|
|
184
|
+
import type { Callbacks } from '../types';
|
|
185
|
+
|
|
186
|
+
function ChatAssistant() {
|
|
187
|
+
const { data, setData } = useUserInterfaceData<Context, Settings>();
|
|
188
|
+
const callbacks = useUserInterfaceCallbacks() as Callbacks;
|
|
189
|
+
const [isLoading, setIsLoading] = useState(false);
|
|
190
|
+
|
|
191
|
+
const messages = data.chathistory.Messages;
|
|
192
|
+
|
|
193
|
+
const handleSendMessage = async (userMessage: string) => {
|
|
194
|
+
if (!userMessage.trim()) return;
|
|
195
|
+
setIsLoading(true);
|
|
196
|
+
try {
|
|
197
|
+
const newMessages = [...messages, { role: 'user' as const, content: userMessage }];
|
|
198
|
+
const { reply } = await callbacks.endpoints['chat']({
|
|
199
|
+
messages: newMessages,
|
|
200
|
+
});
|
|
201
|
+
await setData({
|
|
202
|
+
chathistory: {
|
|
203
|
+
Messages: [...newMessages, { role: 'assistant' as const, content: reply }],
|
|
204
|
+
},
|
|
205
|
+
});
|
|
206
|
+
} finally {
|
|
207
|
+
setIsLoading(false);
|
|
208
|
+
}
|
|
209
|
+
};
|
|
210
|
+
|
|
211
|
+
return (
|
|
212
|
+
<div>
|
|
213
|
+
{messages.map((msg, idx) => (
|
|
214
|
+
<div key={idx} className={msg.role}>
|
|
215
|
+
{msg.content}
|
|
216
|
+
</div>
|
|
217
|
+
))}
|
|
218
|
+
<input
|
|
219
|
+
type="text"
|
|
220
|
+
placeholder="Type your message..."
|
|
221
|
+
onKeyPress={(e) => {
|
|
222
|
+
if (e.key === 'Enter' && !isLoading) {
|
|
223
|
+
handleSendMessage(e.currentTarget.value);
|
|
224
|
+
e.currentTarget.value = '';
|
|
225
|
+
}
|
|
226
|
+
}}
|
|
227
|
+
disabled={isLoading}
|
|
228
|
+
/>
|
|
229
|
+
{isLoading && <p>Loading...</p>}
|
|
230
|
+
</div>
|
|
231
|
+
);
|
|
232
|
+
}
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
### Localising prompts
|
|
236
|
+
|
|
237
|
+
Translate the system prompt in the UI with i18n and pass it to the endpoint in the request. The endpoint forwards it to `generateText`:
|
|
238
|
+
|
|
239
|
+
```tsx
|
|
240
|
+
import { useTranslation } from 'react-i18next';
|
|
241
|
+
|
|
242
|
+
const { t } = useTranslation();
|
|
243
|
+
const { reply } = await callbacks.endpoints['chat']({
|
|
244
|
+
messages: newMessages,
|
|
245
|
+
systemPrompt: t('chatSystemPrompt'),
|
|
246
|
+
});
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
Update `src/i18n.ts`:
|
|
250
|
+
|
|
251
|
+
```typescript
|
|
252
|
+
const resources = {
|
|
253
|
+
en: {
|
|
254
|
+
translation: {
|
|
255
|
+
chatSystemPrompt: 'You are a helpful assistant for a business game.',
|
|
256
|
+
askForAdvice: 'Ask for advice...',
|
|
257
|
+
},
|
|
258
|
+
},
|
|
259
|
+
es: {
|
|
260
|
+
translation: {
|
|
261
|
+
chatSystemPrompt: 'Eres un asistente útil para un juego de simulación empresarial.',
|
|
262
|
+
askForAdvice: 'Pedir consejo...',
|
|
263
|
+
},
|
|
264
|
+
},
|
|
265
|
+
};
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
### Markdown rendering in chat
|
|
269
|
+
|
|
270
|
+
Render markdown replies with `react-markdown`:
|
|
271
|
+
|
|
272
|
+
```typescript
|
|
273
|
+
import { useUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
|
|
274
|
+
import ReactMarkdown from 'react-markdown';
|
|
275
|
+
import { Box, styled } from '@mui/material';
|
|
276
|
+
|
|
277
|
+
const StyledMarkdown = styled(Box)(({ theme }) => ({
|
|
278
|
+
'& code': {
|
|
279
|
+
backgroundColor: theme.palette.action.hover,
|
|
280
|
+
padding: '2px 6px',
|
|
281
|
+
borderRadius: '4px',
|
|
282
|
+
fontFamily: 'monospace'
|
|
283
|
+
},
|
|
284
|
+
'& pre': {
|
|
285
|
+
backgroundColor: theme.palette.action.hover,
|
|
286
|
+
padding: theme.spacing(1),
|
|
287
|
+
borderRadius: '4px',
|
|
288
|
+
overflow: 'auto'
|
|
289
|
+
}
|
|
290
|
+
}));
|
|
291
|
+
|
|
292
|
+
function ChatMessage({ content }: { content: string }) {
|
|
293
|
+
return (
|
|
294
|
+
<StyledMarkdown>
|
|
295
|
+
<ReactMarkdown>{content}</ReactMarkdown>
|
|
296
|
+
</StyledMarkdown>
|
|
297
|
+
);
|
|
298
|
+
}
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
### Error handling
|
|
302
|
+
|
|
303
|
+
A failed endpoint call rejects with an `EndpointError`, the endpoint counterpart of `MutationError`. `error.kind` (shorthand for `error.outcome.kind`) says why: the [`MutationOutcome` kinds](./ui-ticks.md#awaiting-state-changes), plus `invalid-request` (the request failed `requestSchema` and the handler never ran), `handler-error` (the handler threw or overran its time limit) and `invalid-response` (it returned something its declaration forbids). `error.applied` lists the endpoint's effects that had already landed, and `error.failedStep` names the one that failed, so you can tell a call that changed nothing from one that saved its write and then failed on an action:
|
|
304
|
+
|
|
305
|
+
```typescript
|
|
306
|
+
import { EndpointError } from '@seriousgaming/sdk/ui';
|
|
307
|
+
|
|
308
|
+
try {
|
|
309
|
+
const { reply } = await callbacks.endpoints['chat']({ messages });
|
|
310
|
+
setResponse(reply);
|
|
311
|
+
} catch (error) {
|
|
312
|
+
if (error instanceof EndpointError && error.kind === 'handler-error') {
|
|
313
|
+
setError(t('chatUnavailable'));
|
|
314
|
+
} else {
|
|
315
|
+
setError(error instanceof Error ? error.message : String(error));
|
|
316
|
+
}
|
|
317
|
+
}
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
An empty `applied` means nothing changed. As with a mutation, never retry an endpoint call automatically: a `conflict` means a person may try again. See [Call an endpoint from a UI](../recipes/call-endpoint-from-ui.md#steps) for every kind.
|
|
321
|
+
|
|
322
|
+
### Putting a chat UI together
|
|
323
|
+
|
|
324
|
+
The sections above are the parts of a complete chat surface. Beyond them, a chat that feels finished usually adds:
|
|
325
|
+
|
|
326
|
+
- Message history kept in the component's state, or in a capability when it must survive a reload, and sent with each call
|
|
327
|
+
- A loading state while the call is in flight, with the send button disabled
|
|
328
|
+
- Scrolling to the latest message when one arrives
|
|
@@ -0,0 +1,281 @@
|
|
|
1
|
+
# Participants and teams in user interfaces
|
|
2
|
+
|
|
3
|
+
How a game UI reads who is playing: the current participant, their team, observers and walkthroughs, and the controls that let a team join, name itself, and fix a participant's name.
|
|
4
|
+
|
|
5
|
+
It is part of [Building user interfaces](./ui.md), which covers creating the surface and reading and writing context.
|
|
6
|
+
|
|
7
|
+
**Keywords:** participants, useUserInterfaceParticipant, team members, presence, observers, walkthroughs, join link, team name, rename participant, renameSelf
|
|
8
|
+
|
|
9
|
+
## Accessing participant info
|
|
10
|
+
|
|
11
|
+
Use the `useUserInterfaceParticipant` hook to read the current participant's identity:
|
|
12
|
+
|
|
13
|
+
```typescript
|
|
14
|
+
import { useUserInterfaceParticipant } from '@seriousgaming/sdk/ui';
|
|
15
|
+
|
|
16
|
+
function Dashboard() {
|
|
17
|
+
const participant = useUserInterfaceParticipant();
|
|
18
|
+
|
|
19
|
+
// null when the surface is being observed rather than played (see 'Observers')
|
|
20
|
+
if (!participant) return <p>Observing this team</p>;
|
|
21
|
+
|
|
22
|
+
return (
|
|
23
|
+
<div>
|
|
24
|
+
<p>Hello, {participant.name}!</p> {/* e.g. "Participant 1" */}
|
|
25
|
+
<p>Participant #{participant.index}</p> {/* sequential index */}
|
|
26
|
+
<p>Team: {participant.teamId}</p> {/* e.g. "team-1" */}
|
|
27
|
+
</div>
|
|
28
|
+
);
|
|
29
|
+
}
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
| Field | Type | Description |
|
|
33
|
+
| -------- | -------- | ------------------------------------------------------ |
|
|
34
|
+
| `id` | `string` | Platform-assigned participant ID |
|
|
35
|
+
| `name` | `string` | Display name (e.g. `"Participant 1"`) |
|
|
36
|
+
| `index` | `number` | Zero-based join order within the team |
|
|
37
|
+
| `teamId` | `string` | The team this participant belongs to (e.g. `"team-1"`) |
|
|
38
|
+
|
|
39
|
+
For a participant the wrapper does not render children until the platform sends participant info, so all fields are guaranteed to be present. The one case where the hook returns `null` is an observer (see [Observers](#observers) below); guard for it. In the dev server, identity comes from a session cookie (so different browser sessions are different participants).
|
|
40
|
+
|
|
41
|
+
### Seeing the whole team
|
|
42
|
+
|
|
43
|
+
`useUserInterfaceParticipant()` returns the caller; `useUserInterfaceParticipants()` returns the full roster for the caller's team, including the caller's own entry. Each entry adds a `connected` flag to the identity fields:
|
|
44
|
+
|
|
45
|
+
```typescript
|
|
46
|
+
import { useUserInterfaceParticipants } from '@seriousgaming/sdk/ui';
|
|
47
|
+
|
|
48
|
+
function Roster() {
|
|
49
|
+
const participants = useUserInterfaceParticipants();
|
|
50
|
+
|
|
51
|
+
if (participants.length === 0) return <p>Waiting for teammates…</p>;
|
|
52
|
+
|
|
53
|
+
return (
|
|
54
|
+
<ul>
|
|
55
|
+
{participants.map((p) => (
|
|
56
|
+
<li key={p.id}>
|
|
57
|
+
{p.name} {p.connected ? '🟢' : '⚪'}
|
|
58
|
+
</li>
|
|
59
|
+
))}
|
|
60
|
+
</ul>
|
|
61
|
+
);
|
|
62
|
+
}
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
| Field | Type | Description |
|
|
66
|
+
| ----------- | --------- | ------------------------------------------------------ |
|
|
67
|
+
| `id` | `string` | Platform-assigned participant ID |
|
|
68
|
+
| `name` | `string` | Display name (e.g. `"Participant 1"`) |
|
|
69
|
+
| `index` | `number` | Zero-based join order within the team |
|
|
70
|
+
| `connected` | `boolean` | `true` while the participant has a live connection |
|
|
71
|
+
| `teamId` | `string` | The team this participant belongs to (e.g. `"team-1"`) |
|
|
72
|
+
|
|
73
|
+
### Participant presence lifecycle
|
|
74
|
+
|
|
75
|
+
The presence guarantees are firm, so design against them rather than defensively:
|
|
76
|
+
|
|
77
|
+
- **The caller is always present.** `useUserInterfaceParticipant()` never returns a partial value. The wrapper gates rendering on the participant message, so `id`, `name`, `index`, and `teamId` are populated before your first render
|
|
78
|
+
- **The roster may be empty on first render.** `useUserInterfaceParticipants()` is not gated, so it starts as `[]` and fills in reactively as the platform sends the list. Render an empty-roster state rather than assuming at least one entry
|
|
79
|
+
- **The caller is included in the roster.** Once populated, the list always contains the caller's own entry alongside every other participant on the team
|
|
80
|
+
- **A disconnect keeps the entry.** When a participant drops their connection their entry stays in the roster with `connected` flipped to `false`, so you can still show who was here. Participants do not leave: an entry lasts for the whole session, keeping its `id` and `index`
|
|
81
|
+
|
|
82
|
+
Because the caller is guaranteed and the roster fills in reactively, there is no separate loading flag to check: branch on `participants.length === 0` for the brief pre-population window, and on `connected` to distinguish live from dropped teammates.
|
|
83
|
+
|
|
84
|
+
**Under `sdk dev`**, a participant is connected while a page addressed to them is open, at `/team/N/player/M` with or without `?bare`. Several tabs on the same participant count once, and they stay connected until the last one closes. An observer page and the console's session surface are nobody's, so they connect nobody. To see a teammate drop out, open two participants' pages and close one.
|
|
85
|
+
|
|
86
|
+
### Seeing every team's participants
|
|
87
|
+
|
|
88
|
+
`useUserInterfaceParticipants()` covers your own team. In a shared-state game where teams deal with each other, a UI can also read the roster of every team through the `getAllTeamsParticipants()` callback, for a directory of who is on each competing team. Declare `crossTeamParticipants: true` in the UI bundle to authorise it (an undeclared UI receives an empty array), then call it and group the flat result by `teamId`:
|
|
89
|
+
|
|
90
|
+
```tsx
|
|
91
|
+
const { getAllTeamsParticipants } = useUserInterfaceCallbacks();
|
|
92
|
+
const everyone = await getAllTeamsParticipants(); // Participant[]
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Unlike the own-team hook, this is a point-in-time snapshot rather than a live subscription: call it again to refresh. See [Show all teams' participants in a UI](../recipes/show-all-teams-participants.md) for the full pattern.
|
|
96
|
+
|
|
97
|
+
### Observers
|
|
98
|
+
|
|
99
|
+
Your UI can be rendered for an **observer** as well as a participant. An observer is a facilitator watching one team's live game UI without joining as a team member, for seeing how a team is playing, troubleshooting, or running a debrief. An observer is not in the roster and has no participant identity, so `useUserInterfaceParticipant()` returns `null` in that mode.
|
|
100
|
+
|
|
101
|
+
Read the viewer role with `useUserInterfaceViewerRole()`:
|
|
102
|
+
|
|
103
|
+
```tsx
|
|
104
|
+
import { useUserInterfaceViewerRole, useUserInterfaceParticipant } from '@seriousgaming/sdk/ui';
|
|
105
|
+
|
|
106
|
+
function Decisions() {
|
|
107
|
+
const isObserver = useUserInterfaceViewerRole() === 'observer';
|
|
108
|
+
const participant = useUserInterfaceParticipant(); // null when observing
|
|
109
|
+
|
|
110
|
+
return (
|
|
111
|
+
<>
|
|
112
|
+
{isObserver && <Banner>Observing: you are watching this team, not playing</Banner>}
|
|
113
|
+
<PriceInput readOnly={isObserver} />
|
|
114
|
+
</>
|
|
115
|
+
);
|
|
116
|
+
}
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Most UIs need no changes: an observer sees the live game UI exactly as a participant does, and can still drive it. Any change an observer makes goes to the game's validators, as a participant's would, with `actor.role` set to `'observer'` so a validator can treat it differently (see [Validators](./validators.md)). Reach for `useUserInterfaceViewerRole()` only when you want to adapt: hide a participant-only control (anything keyed by participant id has no id to write under), reveal state you keep hidden during play, or present a deliberately read-only debrief view.
|
|
120
|
+
|
|
121
|
+
The two roles are the only ones your UI is ever told. A kind of viewer a later release adds reaches only a game that declares the feature that adds it in `requires`, and every other game is shown to that viewer as to an observer, so code that treats anything but `'participant'` as observing is always right.
|
|
122
|
+
|
|
123
|
+
One read does need attention. To find out **which team** your UI is rendering, use `useUserInterfaceOwnTeam()`, not `useUserInterfaceParticipant()?.teamId`:
|
|
124
|
+
|
|
125
|
+
```typescript
|
|
126
|
+
import { useUserInterfaceOwnTeam } from '@seriousgaming/sdk/ui';
|
|
127
|
+
|
|
128
|
+
const ownTeam = useUserInterfaceOwnTeam(); // { teamId, index, name }, populated when observing too
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
The participant route is the obvious one and it is `null` under observation, so anything derived from it (marking your row in a cross-team list, labelling a board, keying a write) works when played and breaks when observed. `useUserInterfaceOwnTeam()` comes from the host, which always knows which surface it mounted. Do not confuse it with the plural `useUserInterfaceTeams()`, which lists every team in the session without marking yours.
|
|
132
|
+
|
|
133
|
+
### Walkthroughs
|
|
134
|
+
|
|
135
|
+
Your UI can also be rendered in a **walkthrough**: a disposable second run of the game beside the session, for demonstrating it. One team, one participant, always from tick 0, touching nothing real. It is what a facilitator puts on a projector while talking a room through the game.
|
|
136
|
+
|
|
137
|
+
Read it with `useRunKind()`:
|
|
138
|
+
|
|
139
|
+
```tsx
|
|
140
|
+
import { useRunKind } from '@seriousgaming/sdk/ui';
|
|
141
|
+
|
|
142
|
+
function Leaderboard() {
|
|
143
|
+
const runKind = useRunKind();
|
|
144
|
+
const data = useUserInterfaceData();
|
|
145
|
+
|
|
146
|
+
// A walkthrough has one team, so the board has one row. Fill it in rather
|
|
147
|
+
// than showing a room an empty board they will never see again.
|
|
148
|
+
const rows = runKind === 'walkthrough' ? demonstrationRows : data.market.Standings;
|
|
149
|
+
|
|
150
|
+
return <Board rows={rows} />;
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
Most UIs need no changes, and one that ignores this renders exactly as it always has: every session reports `'session'`, and only the walkthrough beside it differs. Reach for it to fill in what a solo run genuinely lacks (rival teams, teammates in a presence list), or to hide something you would rather not spoil before play.
|
|
155
|
+
|
|
156
|
+
**The line to hold:** do not change how the game UI plays. The walkthrough exists to show the room this game, and one that behaves differently shows them a different one.
|
|
157
|
+
|
|
158
|
+
The value is the host's, it is the same one your engine reads as `meta.runKind`, and it does not change for the life of the run, so a decision taken here and one taken in logic cannot disagree.
|
|
159
|
+
|
|
160
|
+
A session UI gets two more pieces. `useSessionUserInterfaceWalkthroughLink()` returns where to open the walkthrough, or `null` until the host has said (every host offers one), and `callbacks.resetWalkthrough()` throws it away and starts it again at tick 0. Gate the control on the link, the way a guide button gates on `useSessionUserInterfaceHostOverlays()`:
|
|
161
|
+
|
|
162
|
+
```tsx
|
|
163
|
+
const walkthrough = useSessionUserInterfaceWalkthroughLink();
|
|
164
|
+
const { resetWalkthrough } = useSessionUserInterfaceCallbacks();
|
|
165
|
+
|
|
166
|
+
{
|
|
167
|
+
walkthrough && (
|
|
168
|
+
<>
|
|
169
|
+
<Button href={walkthrough.url} target="_blank" rel="noreferrer">
|
|
170
|
+
Walkthrough
|
|
171
|
+
</Button>
|
|
172
|
+
<Button onClick={() => void resetWalkthrough()}>Start it again</Button>
|
|
173
|
+
</>
|
|
174
|
+
);
|
|
175
|
+
}
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
## Showing how to join this team
|
|
179
|
+
|
|
180
|
+
Every game UI is told how to join the team it is rendering. Use it to put
|
|
181
|
+
a join code on the screen the participants are actually looking at, rather than having
|
|
182
|
+
the facilitator read a URL out.
|
|
183
|
+
|
|
184
|
+
```typescript
|
|
185
|
+
import { useUserInterfaceOwnTeamJoinLink } from '@seriousgaming/sdk/ui';
|
|
186
|
+
|
|
187
|
+
function JoinCode() {
|
|
188
|
+
const joinLink = useUserInterfaceOwnTeamJoinLink();
|
|
189
|
+
// `null` until the host delivers it, so render nothing for that first frame
|
|
190
|
+
if (!joinLink) return null;
|
|
191
|
+
return <QrCode value={joinLink.joinUrl} />;
|
|
192
|
+
}
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Points worth knowing:
|
|
196
|
+
|
|
197
|
+
- You always get your own team and only your own team. There is no list, and no
|
|
198
|
+
way to reach another team's link from a game UI
|
|
199
|
+
- Observers get it too, and that is the case the feature exists for. A tablet
|
|
200
|
+
parked on a table showing a team's game UI has no participant of its own, so
|
|
201
|
+
it is opened as an observer: exactly the screen a walk-up join code belongs on
|
|
202
|
+
- Encode `joinUrl` in a QR code, not any longer form you build yourself. The host
|
|
203
|
+
picks which form of the link to send, and it picks the short one because a
|
|
204
|
+
denser code is harder to scan across a table
|
|
205
|
+
- `fallbackJoinUrl` is there for one failure only, a network that blocks the
|
|
206
|
+
shortened link. Offer it on request (a 'link not working?' control), not beside
|
|
207
|
+
the main one with equal weight
|
|
208
|
+
- The session PIN never reaches a game UI. In a session that requires one,
|
|
209
|
+
the code on screen is not enough to join on its own, which is what bounds how
|
|
210
|
+
much a visible code gives away. An operator who wants a self-sufficient walk-up
|
|
211
|
+
code runs the session without a PIN
|
|
212
|
+
|
|
213
|
+
## Letting a team name itself
|
|
214
|
+
|
|
215
|
+
A game UI can rename the team it belongs to. The name it sets is the
|
|
216
|
+
team's real name everywhere, including the host's own chrome and print sheets, so
|
|
217
|
+
a game that offers this keeps no display name of its own alongside it.
|
|
218
|
+
|
|
219
|
+
```typescript
|
|
220
|
+
import { MutationError, useUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
|
|
221
|
+
|
|
222
|
+
const { renameOwnTeam } = useUserInterfaceCallbacks();
|
|
223
|
+
|
|
224
|
+
try {
|
|
225
|
+
await renameOwnTeam(draftName);
|
|
226
|
+
} catch (error) {
|
|
227
|
+
// A refusal is terminal: explain it rather than retrying
|
|
228
|
+
if (error instanceof MutationError) setRefused(true);
|
|
229
|
+
}
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
Points worth knowing:
|
|
233
|
+
|
|
234
|
+
- **It names no team.** The host works out which team the caller is on, so a
|
|
235
|
+
surface can only ever rename its own. There is no `teamId` argument to get
|
|
236
|
+
wrong
|
|
237
|
+
- **Available everywhere, with nothing to declare.** Game UIs and waiting room
|
|
238
|
+
UIs, participants and observers alike. A game that does not want its teams
|
|
239
|
+
renamed simply does not offer the control
|
|
240
|
+
- **Render the result, not the request.** A facilitator can rename the same team
|
|
241
|
+
from the session UI at the same moment. There is one name per team and the
|
|
242
|
+
last write wins, so read it back from `useUserInterfaceOwnTeam()` rather than trusting what
|
|
243
|
+
you just sent
|
|
244
|
+
- **The host owns the limits.** It trims the name, refuses a blank one, and
|
|
245
|
+
refuses one longer than its cap (60 characters on the reference platform). Each
|
|
246
|
+
arrives as a terminal `denied`, so surface it rather than looping
|
|
247
|
+
- **`teams.defaultNames` becomes a starting point**, not a fixed label, in any
|
|
248
|
+
game that offers this
|
|
249
|
+
|
|
250
|
+
## Letting a participant fix their own name
|
|
251
|
+
|
|
252
|
+
A participant who mistyped their name on joining can change it with `renameSelf`,
|
|
253
|
+
where the host lets them. Whose names are theirs to change is the host's call: a
|
|
254
|
+
guest who typed one usually may, and one whose name comes from a sign-in may not.
|
|
255
|
+
`useUserInterfaceCanRenameSelf()` gives the host's answer for the participant
|
|
256
|
+
using this surface:
|
|
257
|
+
|
|
258
|
+
```typescript
|
|
259
|
+
import {
|
|
260
|
+
useUserInterfaceCallbacks,
|
|
261
|
+
useUserInterfaceCanRenameSelf,
|
|
262
|
+
} from '@seriousgaming/sdk/ui';
|
|
263
|
+
|
|
264
|
+
const canRenameSelf = useUserInterfaceCanRenameSelf();
|
|
265
|
+
const { renameSelf } = useUserInterfaceCallbacks();
|
|
266
|
+
|
|
267
|
+
{canRenameSelf && (
|
|
268
|
+
<Button onClick={() => void renameSelf(draftName)}>Change my name</Button>
|
|
269
|
+
)}
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
- **Show the control only where `canRenameSelf` is `true`.** It is `false` for an
|
|
273
|
+
observer, for a participant whose name the host keeps, and on a host that
|
|
274
|
+
predates `renameSelf`, which may never answer the call
|
|
275
|
+
- **It names nobody.** The host works out who is asking, so a surface can only
|
|
276
|
+
rename its own participant
|
|
277
|
+
- **Render the result, not the request.** A facilitator can rename the same
|
|
278
|
+
participant at the same moment. Read the name back from
|
|
279
|
+
`useUserInterfaceParticipant()`
|
|
280
|
+
- **The host owns the limits**, as for a team name: it trims the name and refuses
|
|
281
|
+
a blank or over-long one as a terminal `denied`
|