@seriousgaming/sdk-tools 1.3.0 → 1.5.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/cli.js +4055 -2646
- package/dist/client.js +807 -172
- package/dist/core/session-host.d.ts +4 -2
- package/dist/core/settings-locks.d.ts +27 -2
- package/dist/dev/console/assets/{index-DEV8N0na.js → index-BVF8exas.js} +22 -22
- package/dist/dev/console/index.html +1 -1
- package/dist/dev/public-origins.d.ts +61 -0
- package/dist/dev/routes.d.ts +4 -0
- package/dist/dev/shell.d.ts +32 -4
- package/dist/dev/view/batch.d.ts +7 -1
- package/dist/docs/ai-agents.md +5 -0
- package/dist/docs/api/index.md +1 -1
- package/dist/docs/api/sdk-tools-client.md +1 -0
- package/dist/docs/api/sdk.md +79 -2
- package/dist/docs/changelog-0.x.md +2 -2
- package/dist/docs/changelog.md +62 -4
- package/dist/docs/cli-and-dev-server.md +58 -0
- package/dist/docs/cli-error-codes.md +39 -36
- package/dist/docs/cli-reference.md +68 -21
- package/dist/docs/concepts/terminology.md +1 -1
- package/dist/docs/environment-variables.md +10 -5
- package/dist/docs/guides/ai-facilitation.md +2 -0
- package/dist/docs/guides/capabilities.md +4 -0
- package/dist/docs/guides/designing-a-game.md +2 -0
- package/dist/docs/guides/designing-screens.md +133 -0
- package/dist/docs/guides/endpoints.md +4 -2
- package/dist/docs/guides/engine-testing.md +6 -2
- package/dist/docs/guides/engine.md +2 -0
- package/dist/docs/guides/file-handling.md +116 -22
- 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 +5 -3
- 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 +3 -1
- package/dist/docs/guides/scenarios.md +15 -3
- 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 +64 -2
- package/dist/docs/guides/setup.md +3 -1
- package/dist/docs/guides/speech-generation.md +2 -0
- package/dist/docs/guides/starter-game.md +61 -21
- package/dist/docs/guides/testing.md +2 -0
- 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 +64 -4
- package/dist/docs/guides/waiting-room.md +1 -1
- package/dist/docs/index.md +2 -1
- package/dist/docs/page-index.md +145 -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/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/upload-and-display-files.md +7 -7
- package/dist/docs/recipes/use-request-tick.md +2 -2
- package/dist/docs/recipes/validate-scenarios.md +4 -1
- package/dist/execution/config-resolver.d.ts +4 -1
- package/dist/execution/endpoint-runner.d.ts +6 -0
- package/dist/execution/logic-calls.d.ts +7 -2
- package/dist/execution/scenario-gates.d.ts +21 -1
- package/dist/guide/settings.d.ts +1 -1
- package/dist/host.js +64 -2
- package/dist/runtime/manifest-version.d.ts +1 -1
- package/dist/runtime.js +7 -2
- package/dist/storage/asset-resolver.d.ts +24 -1
- package/dist/storage/blob-store.d.ts +7 -0
- 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/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/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 +42 -8
- 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/local-refs.d.ts +40 -0
- package/dist/utils/schema-members.d.ts +19 -0
- package/package.json +11 -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,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`
|
|
@@ -0,0 +1,263 @@
|
|
|
1
|
+
# Styling and building user interfaces
|
|
2
|
+
|
|
3
|
+
How a game UI handles language, theme, and screen size, and how to customise the Vite build that serves and bundles it.
|
|
4
|
+
|
|
5
|
+
It is part of [Building user interfaces](./ui.md), which covers creating the surface and reading and writing context.
|
|
6
|
+
|
|
7
|
+
**Keywords:** i18n, internationalisation, theme, styling, dark mode, Material-UI, MUI, contrastText, mobile, viewport, dvh, Vite, vite.config.ts
|
|
8
|
+
|
|
9
|
+
## Using internationalisation
|
|
10
|
+
|
|
11
|
+
The wrapper sets `lang` and `dir` on the document root from the locale (`dir="rtl"` for Arabic, Hebrew, Persian, Urdu and any other right-to-left script) and keeps them in step when the facilitator changes language, so a surface does not set them itself. It also sets the root's `color-scheme` to the theme's mode, so scrollbars and native form controls follow a dark theme without MUI.
|
|
12
|
+
|
|
13
|
+
Use React i18next for multi-language support:
|
|
14
|
+
|
|
15
|
+
```typescript
|
|
16
|
+
import { useTranslation } from 'react-i18next';
|
|
17
|
+
import { useUserInterfaceLocale } from '@seriousgaming/sdk/ui';
|
|
18
|
+
|
|
19
|
+
function Dashboard() {
|
|
20
|
+
const { t } = useTranslation();
|
|
21
|
+
const { locale } = useUserInterfaceLocale();
|
|
22
|
+
|
|
23
|
+
return (
|
|
24
|
+
<div>
|
|
25
|
+
<h1>{t('dashboard.title')}</h1>
|
|
26
|
+
<p>{t('dashboard.welcome')}</p>
|
|
27
|
+
<p>Current language: {locale}</p>
|
|
28
|
+
</div>
|
|
29
|
+
);
|
|
30
|
+
}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Update your `src/i18n.ts`:
|
|
34
|
+
|
|
35
|
+
```typescript
|
|
36
|
+
import i18n from 'i18next';
|
|
37
|
+
import { initReactI18next } from 'react-i18next';
|
|
38
|
+
|
|
39
|
+
const resources = {
|
|
40
|
+
en: {
|
|
41
|
+
translation: {
|
|
42
|
+
'dashboard.title': 'Dashboard',
|
|
43
|
+
'dashboard.welcome': 'Welcome',
|
|
44
|
+
'inventory.label': 'Stock Level',
|
|
45
|
+
'revenue.label': 'Revenue',
|
|
46
|
+
},
|
|
47
|
+
},
|
|
48
|
+
es: {
|
|
49
|
+
translation: {
|
|
50
|
+
'dashboard.title': 'Panel de Control',
|
|
51
|
+
'dashboard.welcome': 'Bienvenido',
|
|
52
|
+
'inventory.label': 'Nivel de Stock',
|
|
53
|
+
'revenue.label': 'Ingresos',
|
|
54
|
+
},
|
|
55
|
+
},
|
|
56
|
+
};
|
|
57
|
+
|
|
58
|
+
i18n.use(initReactI18next).init({
|
|
59
|
+
resources,
|
|
60
|
+
lng: 'en',
|
|
61
|
+
interpolation: { escapeValue: false },
|
|
62
|
+
});
|
|
63
|
+
|
|
64
|
+
export default i18n;
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Theming and styling
|
|
68
|
+
|
|
69
|
+
Serious Gaming provides a theming system that allows your user interfaces to adapt to the host environment's look and feel. This is handled through the `@seriousgaming/sdk` package.
|
|
70
|
+
|
|
71
|
+
### Accessing theme information
|
|
72
|
+
|
|
73
|
+
You can access the current theme information within your components using the `useUserInterfaceTheme` hook.
|
|
74
|
+
|
|
75
|
+
```typescript
|
|
76
|
+
import { useUserInterfaceTheme } from '@seriousgaming/sdk/ui';
|
|
77
|
+
|
|
78
|
+
function MyComponent() {
|
|
79
|
+
const theme = useUserInterfaceTheme();
|
|
80
|
+
// theme.mode will be 'light' or 'dark'
|
|
81
|
+
// theme.light and theme.dark will contain color palettes
|
|
82
|
+
|
|
83
|
+
return (
|
|
84
|
+
<div style={% raw %}{{{% endraw %} background: theme.mode === 'light' ? theme.light.primary : theme.dark.primary {% raw %}}}{% endraw %}>
|
|
85
|
+
My Component
|
|
86
|
+
</div>
|
|
87
|
+
);
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### Theme object structure
|
|
92
|
+
|
|
93
|
+
The `theme` object returned by `useUserInterfaceTheme` has the following structure:
|
|
94
|
+
|
|
95
|
+
```typescript
|
|
96
|
+
type UserInterfaceTheme = {
|
|
97
|
+
mode: 'dark' | 'light';
|
|
98
|
+
dark: UserInterfaceModeColors;
|
|
99
|
+
light: UserInterfaceModeColors;
|
|
100
|
+
};
|
|
101
|
+
|
|
102
|
+
type UserInterfaceModeColors = {
|
|
103
|
+
primary: string;
|
|
104
|
+
secondary: string;
|
|
105
|
+
success: string;
|
|
106
|
+
error: string;
|
|
107
|
+
warning: string;
|
|
108
|
+
info: string;
|
|
109
|
+
contrastText: {
|
|
110
|
+
primary: string;
|
|
111
|
+
secondary: string;
|
|
112
|
+
success: string;
|
|
113
|
+
error: string;
|
|
114
|
+
warning: string;
|
|
115
|
+
info: string;
|
|
116
|
+
};
|
|
117
|
+
};
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
- `mode`: Indicates whether the current theme is `'light'` or `'dark'`
|
|
121
|
+
- `light`: An object containing the colour palette for the light theme
|
|
122
|
+
- `dark`: An object containing the colour palette for the dark theme
|
|
123
|
+
- `contrastText`: The text colour to draw on each palette colour, an opaque `#rrggbb` the host guarantees meets WCAG AA (4.5:1) against it. Use it rather than computing your own: the theme's author may have chosen one, and the host keeps it when it passes
|
|
124
|
+
|
|
125
|
+
```tsx
|
|
126
|
+
const colors = theme.mode === 'light' ? theme.light : theme.dark;
|
|
127
|
+
|
|
128
|
+
<span style={% raw %}{{{% endraw %} background: colors.primary, color: colors.contrastText.primary {% raw %}}}{% endraw %}>Live</span>
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Passing `contrastText` through to Material-UI, as the template's `theme.ts` does (below), means every contained button and chip already uses it.
|
|
132
|
+
|
|
133
|
+
### Reading the host's theme preference
|
|
134
|
+
|
|
135
|
+
`useUserInterfaceTheme` gives you the resolved palette, but `theme.mode` only tells you the colours to paint right now. It cannot tell you whether the host is following the operating system or has been pinned to a specific scheme. When you need that distinction, read the host's preference with the `useUserInterfaceThemePreference()` hook. It returns `'light'`, `'dark'`, or `'system'` and re-renders when the preference changes, exactly like `useUserInterfaceTheme()`:
|
|
136
|
+
|
|
137
|
+
```typescript
|
|
138
|
+
import { useUserInterfaceThemePreference } from '@seriousgaming/sdk/ui';
|
|
139
|
+
|
|
140
|
+
function ThemePreferenceBadge() {
|
|
141
|
+
const preference = useUserInterfaceThemePreference();
|
|
142
|
+
return <span>Following: {preference}</span>;
|
|
143
|
+
}
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Each UI surface has its own hook: `useUserInterfaceThemePreference`, `useSessionUserInterfaceThemePreference`, and `useSettingsEditorThemePreference`.
|
|
147
|
+
|
|
148
|
+
A UI can also change the preference with the `setThemePreference` callback. The host applies it, persists it, and broadcasts the change back, so every other UI (and every theme-preference hook) sees it:
|
|
149
|
+
|
|
150
|
+
```typescript
|
|
151
|
+
import { useUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
|
|
152
|
+
|
|
153
|
+
function ThemeSwitcher() {
|
|
154
|
+
const callbacks = useUserInterfaceCallbacks();
|
|
155
|
+
return (
|
|
156
|
+
<>
|
|
157
|
+
<button onClick={() => callbacks.setThemePreference('light')}>Light</button>
|
|
158
|
+
<button onClick={() => callbacks.setThemePreference('dark')}>Dark</button>
|
|
159
|
+
<button onClick={() => callbacks.setThemePreference('system')}>System</button>
|
|
160
|
+
</>
|
|
161
|
+
);
|
|
162
|
+
}
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
`setThemePreference` is available on every UI surface but the presentation (game, waiting room, session, setup and scenario editor). No `uses` declaration is needed, because theme preference is not gated.
|
|
166
|
+
|
|
167
|
+
### Integrating with Material-UI
|
|
168
|
+
|
|
169
|
+
The default user interface template uses [Material-UI](https://mui.com/) for its component library. `createSurfaceTheme` turns the host's theme into MUI theme options: every colour role with its `contrastText`, the page, surface and text colours when the host sends them, and the host brand's fonts. Pass it to `createTheme` first, with your own shape and component overrides after it:
|
|
170
|
+
|
|
171
|
+
```typescript
|
|
172
|
+
// src/theme.ts
|
|
173
|
+
import { createTheme } from '@mui/material/styles';
|
|
174
|
+
import { createSurfaceTheme, useUserInterfaceTheme } from '@seriousgaming/sdk/ui';
|
|
175
|
+
import { useMemo } from 'react';
|
|
176
|
+
|
|
177
|
+
export const useAppTheme = () => {
|
|
178
|
+
const theme = useUserInterfaceTheme();
|
|
179
|
+
return useMemo(
|
|
180
|
+
() =>
|
|
181
|
+
createTheme(createSurfaceTheme(theme, { fonts: { body: 'Work Sans Variable' } }), {
|
|
182
|
+
shape: { borderRadius: 10 },
|
|
183
|
+
}),
|
|
184
|
+
[theme]
|
|
185
|
+
);
|
|
186
|
+
};
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
`fonts.body` is the font your game bundles, used whenever the host's brand names none. By using `useMemo`, you ensure that the theme object is only recreated when the theme context from Serious Gaming changes, which is important for performance.
|
|
190
|
+
|
|
191
|
+
For the host's logo and name, its fonts, and how to preview a game in someone else's brand, see [Theming and branding](./theming-and-branding.md).
|
|
192
|
+
|
|
193
|
+
## Sizing to the viewport on mobile
|
|
194
|
+
|
|
195
|
+
The host sizes your UI's iframe to the visible viewport, so size your UI to fill its container rather than the browser viewport: prefer `height: 100%` (down through `html`, `body`, and the root element) with flex or grid layouts over viewport units.
|
|
196
|
+
|
|
197
|
+
If you do reach for viewport units, use `dvh` with a `vh` fallback. On iOS WebKit `100vh` resolves to the tall (URL-bar-collapsed) viewport even while the bar is showing, so a `100vh` element runs off the bottom of the screen; `100dvh` tracks the live visible viewport:
|
|
198
|
+
|
|
199
|
+
```css
|
|
200
|
+
min-height: 100vh; /* fallback for older browsers */
|
|
201
|
+
min-height: 100dvh; /* tracks the live viewport on iOS */
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
In MUI `sx`, where you cannot repeat a key, express the fallback with `@supports`:
|
|
205
|
+
|
|
206
|
+
```ts
|
|
207
|
+
sx={{ minHeight: '100vh', '@supports (height: 100dvh)': { minHeight: '100dvh' } }}
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
Embedded in the host this rarely bites, because an iframe has no collapsing browser chrome and `vh` resolves to the iframe's own height. The `dvh` form keeps your UI correct if it is ever opened standalone in a mobile browser, and the scaffold templates already follow it.
|
|
211
|
+
|
|
212
|
+
## Customising Vite (dev and build)
|
|
213
|
+
|
|
214
|
+
When the SDK starts Vite for your UI (whether for the dev server or a production build), you can customise Vite's behaviour by creating a `vite.config.ts` file. The SDK loads it and merges it with its own inline config.
|
|
215
|
+
|
|
216
|
+
### Where to put `vite.config.ts`
|
|
217
|
+
|
|
218
|
+
**Put it at the project root** (alongside `seriousgaming.sdk.json`). This is the recommended location: one file applies to every UI in the package, and the same file is used by both `sdk dev` and `sdk build`.
|
|
219
|
+
|
|
220
|
+
```
|
|
221
|
+
my-package/
|
|
222
|
+
├── seriousgaming.sdk.json
|
|
223
|
+
├── vite.config.ts ← recommended location
|
|
224
|
+
├── ui/
|
|
225
|
+
│ ├── index.html
|
|
226
|
+
│ └── src/
|
|
227
|
+
└── session/
|
|
228
|
+
└── ...
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
### Per-UI overrides
|
|
232
|
+
|
|
233
|
+
You can also drop a `vite.config.ts` inside an individual `ui/` directory. The SDK loads it in addition to the project-root config and the per-UI file's values override the root's on conflicts. This is useful when one UI needs a specific alias or plugin that would break the others, but in practice the root config is almost always enough, and per-UI files multiply maintenance.
|
|
234
|
+
|
|
235
|
+
**Don't keep both a root config and a per-UI config for the same UI unless you really mean to.** If the SDK finds both while building a given UI it prints a warning and asks you to consolidate. Merging still happens so the build doesn't break, but the warning is telling you that the intent is unclear.
|
|
236
|
+
|
|
237
|
+
### What merges and what doesn't
|
|
238
|
+
|
|
239
|
+
The merge order is:
|
|
240
|
+
|
|
241
|
+
```
|
|
242
|
+
project-root vite.config.ts → ui/vite.config.ts → SDK inline config
|
|
243
|
+
(baseline) (overrides root) (SDK owns these)
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
**Additive options merge cleanly.** `resolve.dedupe`, `resolve.alias`, `optimizeDeps.include`, `esbuild`, extra `plugins`, and similar fields are not set (or only partially set) by the SDK, so your entries are combined with the SDK's.
|
|
247
|
+
|
|
248
|
+
**The SDK wins on structural fields.** `root`, `base`, `build.outDir`, `build.rollupOptions.input`, and the dev-server `server.middlewareMode`/`appType`/`hmr` settings are owned by the SDK and cannot be overridden: trying to set them in `vite.config.ts` has no effect.
|
|
249
|
+
|
|
250
|
+
A common use case is preventing duplicate package instances when using third-party React libraries:
|
|
251
|
+
|
|
252
|
+
```typescript
|
|
253
|
+
// vite.config.ts (project root)
|
|
254
|
+
import { defineConfig } from 'vite';
|
|
255
|
+
|
|
256
|
+
export default defineConfig({
|
|
257
|
+
resolve: {
|
|
258
|
+
dedupe: ['react', 'react-dom'],
|
|
259
|
+
},
|
|
260
|
+
});
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
See [Fix duplicate package errors in a UI](../recipes/fix-duplicate-packages.md) for a full explanation of when and why this is needed.
|