@seriousgaming/sdk-tools 1.0.0 → 1.2.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/README.md +4 -4
- package/dist/brands/awkward/brand.json +16 -0
- package/dist/brands/awkward/logo-on-light.svg +4 -0
- package/dist/brands/serious-gaming/brand.json +42 -0
- package/dist/brands/serious-gaming/fonts/OFL-sora.txt +93 -0
- package/dist/brands/serious-gaming/fonts/OFL-work-sans.txt +93 -0
- package/dist/brands/serious-gaming/fonts/sora-latin-400-normal.woff2 +0 -0
- package/dist/brands/serious-gaming/fonts/sora-latin-600-normal.woff2 +0 -0
- package/dist/brands/serious-gaming/fonts/sora-latin-700-normal.woff2 +0 -0
- package/dist/brands/serious-gaming/fonts/work-sans-latin-wght-normal.woff2 +0 -0
- package/dist/brands/serious-gaming/icon.svg +24 -0
- package/dist/brands/serious-gaming/loader-on-dark.svg +25 -0
- package/dist/brands/serious-gaming/loader-on-light.svg +25 -0
- package/dist/brands/serious-gaming/logo-on-dark.svg +38 -0
- package/dist/brands/serious-gaming/logo-on-light.svg +42 -0
- package/dist/cli.js +20161 -5495
- package/dist/client.js +15737 -1151
- package/dist/core/save-scenario.d.ts +25 -0
- package/dist/core/session-endpoints.d.ts +12 -13
- package/dist/core/session-host.d.ts +9 -1
- package/dist/core/session-writes.d.ts +2 -2
- package/dist/core/session.d.ts +9 -1
- package/dist/dev/brand-summary.d.ts +16 -0
- package/dist/dev/brands.d.ts +230 -0
- package/dist/dev/console/assets/icon-CRaj5uhr.svg +24 -0
- package/dist/dev/console/assets/index-BNLEVOQA.js +204 -0
- package/dist/dev/console/assets/index-q6-lvlN3.css +1 -0
- package/dist/dev/console/assets/sora-latin-400-normal-CRt88UEn.woff2 +0 -0
- package/dist/dev/console/assets/sora-latin-600-normal-Cdg4DaK0.woff2 +0 -0
- package/dist/dev/console/assets/sora-latin-700-normal-9waGdLWo.woff2 +0 -0
- package/dist/dev/console/assets/work-sans-latin-wght-normal-Bl-S9Xys.woff2 +0 -0
- package/dist/dev/console/index.html +3 -1
- package/dist/dev/routes.d.ts +9 -0
- package/dist/dev/shell.d.ts +14 -0
- package/dist/dev/view/batch.d.ts +0 -2
- package/dist/docs/ai-agents.md +75 -0
- package/dist/docs/api/deck.md +38 -0
- package/dist/docs/api/index.md +5 -5
- package/dist/docs/api/sdk-commands.md +1 -1
- package/dist/docs/api/sdk-e2e.md +1 -0
- package/dist/docs/api/sdk-projection.md +1 -0
- package/dist/docs/api/sdk-testing.md +52 -1
- package/dist/docs/api/sdk-tools-client.md +1 -0
- package/dist/docs/api/sdk-ui-testing.md +30 -4
- package/dist/docs/api/sdk-ui.md +185 -0
- package/dist/docs/api/sdk.md +70 -4
- package/dist/docs/changelog.md +85 -4
- package/dist/docs/cli-and-dev-server.md +2 -0
- package/dist/docs/cli-error-codes.md +65 -59
- package/dist/docs/cli-reference.md +84 -45
- package/dist/docs/concepts/index.md +74 -6
- package/dist/docs/concepts/terminology.md +17 -11
- package/dist/docs/getting-started.md +30 -11
- package/dist/docs/guides/ai-facilitation.md +5 -1
- package/dist/docs/guides/capabilities.md +3 -1
- package/dist/docs/guides/designing-a-game.md +85 -0
- package/dist/docs/guides/endpoints.md +57 -13
- package/dist/docs/guides/engine-testing.md +4 -13
- package/dist/docs/guides/engine.md +14 -2
- package/dist/docs/guides/file-handling.md +14 -10
- package/dist/docs/guides/games.md +2 -8
- package/dist/docs/guides/guide.md +98 -6
- package/dist/docs/guides/index.md +3 -4
- package/dist/docs/guides/internationalization.md +8 -14
- package/dist/docs/guides/llm-integration.md +19 -31
- package/dist/docs/guides/multi-team-games.md +9 -14
- package/dist/docs/guides/patterns.md +0 -6
- package/dist/docs/guides/presentation.md +6 -10
- package/dist/docs/guides/production-constraints.md +3 -10
- package/dist/docs/guides/scenario-editor.md +11 -11
- package/dist/docs/guides/scenarios.md +26 -14
- package/dist/docs/guides/session.md +32 -36
- package/dist/docs/guides/settings.md +28 -2
- package/dist/docs/guides/setup.md +2 -7
- package/dist/docs/guides/speech-generation.md +8 -17
- package/dist/docs/guides/starter-game.md +2 -1
- package/dist/docs/guides/testing.md +45 -43
- package/dist/docs/guides/theming-and-branding.md +208 -0
- package/dist/docs/guides/tick-controller.md +8 -4
- package/dist/docs/guides/type-safety.md +8 -6
- package/dist/docs/guides/ui.md +41 -62
- package/dist/docs/guides/upgrading.md +13 -3
- package/dist/docs/guides/validators.md +64 -3
- package/dist/docs/guides/waiting-room.md +3 -10
- package/dist/docs/index.md +40 -10
- package/dist/docs/recipes/adapt-ui-for-observers.md +1 -1
- package/dist/docs/recipes/call-endpoint-from-ui.md +2 -0
- package/dist/docs/recipes/create-capability.md +1 -1
- package/dist/docs/recipes/create-endpoint.md +7 -2
- package/dist/docs/recipes/create-engine.md +1 -1
- package/dist/docs/recipes/create-guide.md +4 -4
- package/dist/docs/recipes/create-hook.md +1 -1
- package/dist/docs/recipes/create-session-ui.md +1 -1
- package/dist/docs/recipes/create-settings.md +1 -1
- package/dist/docs/recipes/create-tick-controller.md +1 -1
- package/dist/docs/recipes/create-user-interface.md +1 -1
- package/dist/docs/recipes/create-validator.md +1 -1
- package/dist/docs/recipes/declare-api-uses.md +2 -2
- package/dist/docs/recipes/design-state-for-concurrent-writes.md +2 -2
- package/dist/docs/recipes/distribute-package.md +3 -3
- package/dist/docs/recipes/e2e-testing.md +11 -9
- package/dist/docs/recipes/index.md +6 -2
- package/dist/docs/recipes/make-a-guide-follow-the-scenario.md +89 -0
- package/dist/docs/recipes/make-an-endpoint-external.md +1 -1
- package/dist/docs/recipes/publish-a-package.md +1 -1
- package/dist/docs/recipes/remember-a-viewers-choice.md +1 -1
- package/dist/docs/recipes/review-a-past-day.md +4 -2
- package/dist/docs/recipes/share-assets-across-scenarios.md +3 -3
- package/dist/docs/recipes/share-logic-between-engine-and-ui.md +1 -1
- package/dist/docs/recipes/test-a-multi-role-game.md +1 -1
- package/dist/docs/recipes/test-user-interface.md +13 -2
- package/dist/docs/recipes/validate-scenarios.md +91 -0
- package/dist/docs/troubleshooting.md +44 -2
- package/dist/execution/blob-inputs.d.ts +7 -2
- package/dist/execution/config-resolver.d.ts +10 -0
- package/dist/execution/endpoint-runner.d.ts +8 -1
- package/dist/execution/executor-callbacks.d.ts +7 -0
- package/dist/execution/executor.d.ts +11 -0
- package/dist/execution/logic-calls.d.ts +8 -1
- package/dist/execution/scenario-gates.d.ts +34 -0
- package/dist/guide/effective-guide.d.ts +20 -0
- package/dist/guide/locale.d.ts +12 -0
- package/dist/guide/settings.d.ts +74 -0
- package/dist/guide/video-registry.d.ts +33 -1
- package/dist/host/host-channel.d.ts +11 -2
- package/dist/host/index.d.ts +9 -1
- package/dist/host/protocol.d.ts +49 -5
- package/dist/host/theme.d.ts +28 -2
- package/dist/host.js +11621 -15
- package/dist/runtime/index.d.ts +1 -1
- package/dist/runtime/manifest-version.d.ts +17 -0
- package/dist/runtime.js +12 -1
- package/dist/schema.json +32 -4
- package/dist/storage/blob-store.d.ts +3 -2
- package/dist/templates/endpoint/logic.test.ts.liquid +19 -1
- package/dist/templates/endpoint/logic.ts.liquid +18 -0
- package/dist/templates/hook/logic.test.ts.liquid +2 -2
- package/dist/templates/package/CLAUDE.md.template +5 -2
- package/dist/templates/package/README.md.liquid +2 -0
- package/dist/templates/package/claude/rules/workflow-create-endpoint.md +5 -4
- package/dist/templates/package/claude/rules/workflow-create-guide.md +9 -2
- package/dist/templates/presentation/src/App.tsx.liquid +5 -11
- package/dist/templates/session/src/App.test.tsx.liquid +2 -4
- package/dist/templates/session/src/theme.ts.liquid +26 -33
- package/dist/templates/settings-editor/src/theme.ts.liquid +13 -18
- package/dist/templates/starter-game/hooks/assignproducts/logic/logic.test.ts +2 -8
- package/dist/templates/starter-game/session/src/App.test.tsx +6 -10
- package/dist/templates/starter-game/session/src/theme.ts +26 -33
- package/dist/templates/starter-game/ui/src/App.tsx +2 -0
- package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +25 -0
- package/dist/templates/starter-game/ui/src/HostLogo.tsx +38 -0
- package/dist/templates/starter-game/ui/src/theme.ts +26 -33
- package/dist/templates/starter-game/validators/capacity/types.ts +2 -0
- package/dist/templates/starter-game/waiting_room/src/theme.ts +26 -33
- package/dist/templates/ui/src/App.test.tsx.liquid +7 -19
- package/dist/templates/ui/src/theme.ts.liquid +26 -33
- package/dist/templates/validator/logic.ts.liquid +4 -0
- package/dist/templates/waiting-room/src/App.test.tsx.liquid +17 -31
- package/dist/templates/waiting-room/src/theme.ts.liquid +26 -33
- package/dist/utils/error-codes.d.ts +15 -3
- package/dist/validation/ajv.d.ts +9 -5
- package/dist/validation/facilitator-guide-validator.d.ts +11 -1
- package/dist/validation/file-settings.d.ts +49 -0
- package/dist/validation/guide-settings-validator.d.ts +26 -0
- package/dist/validation/schema-validation.d.ts +12 -4
- package/package.json +6 -5
- package/dist/dev/console/assets/index-DgFglsnA.js +0 -204
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
# Theming and branding
|
|
2
|
+
|
|
3
|
+
Dress every surface of your game in the host's colours, logo and fonts, so a game run by a white-label host looks like that host's product.
|
|
4
|
+
|
|
5
|
+
**Keywords:** theme, branding, white-label, brand, logo, fonts, colours, dark mode, createSurfaceTheme, useBrand, useBrandLogo, useBrandIcon, icon, brandFromTheme, SurfaceLoading, loading screen, --brand, brand file
|
|
6
|
+
|
|
7
|
+
## What the host sends
|
|
8
|
+
|
|
9
|
+
Every surface receives a theme from the host, and receives it again whenever it changes. A theme has:
|
|
10
|
+
|
|
11
|
+
- **A mode**: `'light'` or `'dark'`, the scheme the surface should paint in now
|
|
12
|
+
- **Six colour roles for each mode**: `primary`, `secondary`, `success`, `error`, `warning` and `info`, each with a `contrastText` the host guarantees meets WCAG AA (4.5:1) against it
|
|
13
|
+
- **Page colours for each mode**: `background` (the page), `surface` (cards and panels) and `text`, with `text` readable on both
|
|
14
|
+
- **A brand**: always its `name`, and, where the brand has them, a `logo` and a square `icon` for each background (`onLight` and `onDark`), and the `fonts` its headings and body text are set in
|
|
15
|
+
|
|
16
|
+
A brand with no logo, icon or fonts is normal, and your game must look right with just a name. The SDK never invents a logo of its own: a white-label host never shows anybody else's.
|
|
17
|
+
|
|
18
|
+
A host that predates brands sends neither a brand nor page colours. The wrapper fills them in, with a brand whose name is empty and a plain white or near-black page, so your game never has to check for them.
|
|
19
|
+
|
|
20
|
+
Read the theme with your surface's hook: `useUserInterfaceTheme()` in a game or waiting room UI, `useSessionUserInterfaceTheme()` in a session UI, `useSettingsEditorTheme()` in a setup screen or scenario editor, and `usePresentation().theme` in a presentation.
|
|
21
|
+
|
|
22
|
+
## Apply the theme with createSurfaceTheme
|
|
23
|
+
|
|
24
|
+
`createSurfaceTheme` turns the host's theme into Material-UI theme options: every role with its `contrastText`, the page colours, and the brand's fonts. Pass it to `createTheme` first, then your own shape and component overrides:
|
|
25
|
+
|
|
26
|
+
```typescript
|
|
27
|
+
// ui/src/theme.ts
|
|
28
|
+
import { createTheme } from '@mui/material/styles';
|
|
29
|
+
import { createSurfaceTheme, useUserInterfaceTheme } from '@seriousgaming/sdk/ui';
|
|
30
|
+
import { useMemo } from 'react';
|
|
31
|
+
|
|
32
|
+
export const useAppTheme = () => {
|
|
33
|
+
const theme = useUserInterfaceTheme();
|
|
34
|
+
return useMemo(
|
|
35
|
+
() =>
|
|
36
|
+
createTheme(createSurfaceTheme(theme, { fonts: { body: 'Work Sans Variable' } }), {
|
|
37
|
+
shape: { borderRadius: 10 },
|
|
38
|
+
components: {
|
|
39
|
+
MuiButton: { styleOverrides: { root: { textTransform: 'none' } } },
|
|
40
|
+
},
|
|
41
|
+
}),
|
|
42
|
+
[theme]
|
|
43
|
+
);
|
|
44
|
+
};
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
`fonts.body` (and `fonts.heading`) name the fonts your game bundles itself, used whenever the host's brand names none. The family must be the one your font package registers: `@fontsource-variable/work-sans` registers `Work Sans Variable`, not `Work Sans`.
|
|
48
|
+
|
|
49
|
+
`createSurfaceTheme` returns plain data, so the SDK does not depend on Material-UI. A game built on another component library can read the same fields from the theme itself.
|
|
50
|
+
|
|
51
|
+
## Show the host's logo and name
|
|
52
|
+
|
|
53
|
+
`useBrandLogo()` picks the logo drawn for the mode the surface is painting in, falls back to the other one when the host sent only one, and returns `undefined` when the brand has no logo:
|
|
54
|
+
|
|
55
|
+
```tsx
|
|
56
|
+
import { useBrandLogo } from '@seriousgaming/sdk/ui';
|
|
57
|
+
|
|
58
|
+
export function HostLogo() {
|
|
59
|
+
const logo = useBrandLogo();
|
|
60
|
+
return logo ? <img src={logo.src} alt={logo.alt} height={28} /> : null;
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
`logo.drawnFor` says which background the artwork was made for. It differs from the current mode only when the host sent a single variant, which you can meet by drawing the logo on a panel of that colour.
|
|
65
|
+
|
|
66
|
+
`useBrandIcon()` does the same for the square mark, for a space too small for the logo, such as a compact header or a tab:
|
|
67
|
+
|
|
68
|
+
```tsx
|
|
69
|
+
import { useBrandIcon } from '@seriousgaming/sdk/ui';
|
|
70
|
+
|
|
71
|
+
export function HostIcon() {
|
|
72
|
+
const icon = useBrandIcon();
|
|
73
|
+
return icon ? <img src={icon.src} alt={icon.alt} width={24} height={24} /> : null;
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
A host built for an earlier version sends one icon for both backgrounds, and the hook returns it in either mode.
|
|
78
|
+
|
|
79
|
+
`useBrand()` returns the whole brand. Use its `name` in copy rather than naming a platform, allowing for the empty name a host that predates brands leaves:
|
|
80
|
+
|
|
81
|
+
```tsx
|
|
82
|
+
const { name } = useBrand();
|
|
83
|
+
const title = name ? t('welcomeTo', { name }) : t('welcome');
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
All three hooks work on every surface. Keep a scenario's own logo, such as a fictional company in the case study, as content in a setting or an asset. The host's brand is for the interface around the game.
|
|
87
|
+
|
|
88
|
+
## Fonts
|
|
89
|
+
|
|
90
|
+
When the host's brand names fonts, the wrapper loads them before your surface first paints, so the text does not visibly change font as they arrive. It waits at most 1.5 seconds; on a slow connection the surface paints in the fallback fonts and swaps when the brand's arrive. `createSurfaceTheme` puts the brand's body font on all text and its heading font on `h1` to `h6`.
|
|
91
|
+
|
|
92
|
+
Fonts have to come from the host, on the surface's own origin, because the content security policy a game runs under admits fonts from nowhere else. Bundle your own fallback font with the game, as the starter game does.
|
|
93
|
+
|
|
94
|
+
## Presentations
|
|
95
|
+
|
|
96
|
+
A slide deck takes the host's theme through the deck library's `brandFromTheme`, which maps the accents and their text colours, the page colours and the fonts onto a deck brand:
|
|
97
|
+
|
|
98
|
+
```tsx
|
|
99
|
+
import { brandFromTheme, Deck } from '@seriousgaming/deck';
|
|
100
|
+
import { usePresentation } from '@seriousgaming/sdk/ui';
|
|
101
|
+
import { useMemo } from 'react';
|
|
102
|
+
|
|
103
|
+
export default function App() {
|
|
104
|
+
const { theme, game } = usePresentation();
|
|
105
|
+
const brand = useMemo(() => brandFromTheme(theme), [theme]);
|
|
106
|
+
return (
|
|
107
|
+
<Deck brand={brand} title={game.name}>
|
|
108
|
+
{/* slides */}
|
|
109
|
+
</Deck>
|
|
110
|
+
);
|
|
111
|
+
}
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
It uses the light palette whatever mode the facilitator's screen is in, because slides are projected and a projector washes out a dark slide. Pass `{ mode: 'dark' }` to use the dark one. A deck given no brand uses the Serious Gaming colours and fonts.
|
|
115
|
+
|
|
116
|
+
## The loading screen
|
|
117
|
+
|
|
118
|
+
Until the host has sent everything a surface needs, and the brand's fonts have loaded, the wrapper shows its `fallback`. The default is `SurfaceLoading`: a small spinner in the browser's own light or dark scheme, with no text to translate. Pass your own to replace it:
|
|
119
|
+
|
|
120
|
+
```tsx
|
|
121
|
+
<UserInterfaceWrapper fallback={<MySplash />}>
|
|
122
|
+
<App />
|
|
123
|
+
</UserInterfaceWrapper>
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Once the host's theme has arrived, the default spinner paints in the theme's mode, its page colour and its primary colour, so a dark session does not flash white while the brand's fonts load. Before then it can only follow the browser's own scheme.
|
|
127
|
+
|
|
128
|
+
Most viewers never see the fallback. The wrapper tells the host when your surface's first paint is on screen, and a host that listens keeps its own branded loading screen over the frame until then. The dev server does, showing the picked brand's loading animation, or its logo over a spinner in its primary colour, so you see what a facilitator sees.
|
|
129
|
+
|
|
130
|
+
To look at either loading screen for longer than a moment, use the **Loading** menu in the dev drawer. **Hold the host's loading screen** keeps the dev server's cover over every surface. **Hold the game's loading screen** lifts the cover and sends each surface its theme and nothing else it waits for, so your fallback stays up in the host's colours. Switching reloads the surfaces, and the choice lasts for the browser tab only.
|
|
131
|
+
|
|
132
|
+
## Should a game honour the brand?
|
|
133
|
+
|
|
134
|
+
A game may ignore the host's brand and paint in its own identity: nothing checks. But a white-label host sends its brand because its clients expect to see it, so use `createSurfaceTheme` and show the logo unless your game has a strong reason not to.
|
|
135
|
+
|
|
136
|
+
## Preview your game in another brand
|
|
137
|
+
|
|
138
|
+
The dev server dresses every surface in a brand you pick from the **Brand** menu in the dev drawer, next to the colour scheme. Switching sends the new theme to every open surface without reloading it, which also shows whether your game follows a theme change. It offers:
|
|
139
|
+
|
|
140
|
+
- **Serious Gaming**, the default
|
|
141
|
+
- **Plain brand**: MUI's own colours, a plain page, and a brand that is a name and nothing else, the least a host sends
|
|
142
|
+
- **Awkward Test Brand**: a pale yellow primary, a very wide logo drawn only for light backgrounds, and no fonts or loader, to show up hard-coded colours and layouts that assume a short logo
|
|
143
|
+
|
|
144
|
+
To preview a client's brand, write a brand file and pass it to `sdk dev`:
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
pnpm run sdk dev --brand ../brands/acme/brand.json
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
The brand joins the menu and is selected. Repeat `--brand` for more than one; the first is selected. A brand file is JSON, with every file it names relative to it:
|
|
151
|
+
|
|
152
|
+
```json
|
|
153
|
+
{
|
|
154
|
+
"name": "Acme",
|
|
155
|
+
"light": {
|
|
156
|
+
"primary": "#21244F",
|
|
157
|
+
"secondary": "#17D1C7",
|
|
158
|
+
"background": "#FFFFFF",
|
|
159
|
+
"surface": "#F5F5F7",
|
|
160
|
+
"text": "#1B1F2A"
|
|
161
|
+
},
|
|
162
|
+
"dark": { "primary": "#8C8FE0", "secondary": "#17D1C7" },
|
|
163
|
+
"logo": { "onLight": "logo-on-light.svg", "onDark": "logo-on-dark.svg" },
|
|
164
|
+
"loader": { "onLight": "loader-on-light.svg", "onDark": "loader-on-dark.svg" },
|
|
165
|
+
"icon": "icon.svg",
|
|
166
|
+
"fonts": {
|
|
167
|
+
"body": {
|
|
168
|
+
"family": "Acme Sans",
|
|
169
|
+
"sources": [{ "url": "fonts/acme-sans.woff2", "weight": "100 900" }]
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
- `name` is required, and everything else is optional
|
|
176
|
+
- `icon` is one file for both backgrounds, or `{ "onLight": …, "onDark": … }` like `logo`
|
|
177
|
+
- `loader` is an animation for the dev server's own loading screen, as a host would show its own: an animated SVG, WebP or GIF. It is never sent to your game
|
|
178
|
+
- A colour role a mode leaves out keeps the Serious Gaming one. Page colours a mode leaves out are a plain page's, never another brand's
|
|
179
|
+
- The dev server works out every `contrastText`, and a `text` that is not readable on both `background` and `surface` is replaced with black or white, or the page with a plain one where neither reads
|
|
180
|
+
- Files are served from the dev server's asset origin, as a real host serves them. A path must stay inside the brand file's directory, and a remote URL is refused, because no game could load it. A `data:` URL is used as it is
|
|
181
|
+
- The file is read again whenever the page loads, so an edit shows on refresh
|
|
182
|
+
|
|
183
|
+
Keep brand files beside the games that use them, not inside a game package: a brand belongs to a host, and the host sends it.
|
|
184
|
+
|
|
185
|
+
## Testing
|
|
186
|
+
|
|
187
|
+
`createMockBrand()` from `@seriousgaming/sdk/ui/testing` gives a name, and a logo and an icon for each background, as `data:` URLs. Pass it in a mock theme to test a component that reads the brand:
|
|
188
|
+
|
|
189
|
+
```tsx
|
|
190
|
+
import {
|
|
191
|
+
createMockBrand,
|
|
192
|
+
createMockUserInterfaceTheme,
|
|
193
|
+
renderUserInterface,
|
|
194
|
+
} from '@seriousgaming/sdk/ui/testing';
|
|
195
|
+
|
|
196
|
+
renderUserInterface(<Header />, {
|
|
197
|
+
theme: createMockUserInterfaceTheme({ brand: createMockBrand({ name: 'Acme' }) }),
|
|
198
|
+
});
|
|
199
|
+
expect(screen.getByRole('img', { name: 'Acme' })).toBeInTheDocument();
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Test without a logo too: `createMockUserInterfaceTheme()` sends a brand that is only a name, the least a host sends.
|
|
203
|
+
|
|
204
|
+
## Related
|
|
205
|
+
|
|
206
|
+
- [Building user interfaces](./ui.md): the theme object and the theme preference
|
|
207
|
+
- [Building presentations](./presentation.md): the deck library
|
|
208
|
+
- [Production security constraints](./production-constraints.md): why fonts and images come from the surface's own origin
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
# Tick controllers
|
|
2
2
|
|
|
3
|
-
A tick controller makes ticks happen on their own, on a schedule your logic decides, and can say when the game is finished.
|
|
3
|
+
A tick controller makes ticks happen on their own, on a schedule your logic decides, and can say when the game is finished.
|
|
4
|
+
|
|
5
|
+
This guide explains the model, then is the reference for writing one.
|
|
4
6
|
|
|
5
7
|
## The model
|
|
6
8
|
|
|
@@ -27,6 +29,8 @@ Use a tick controller when:
|
|
|
27
29
|
|
|
28
30
|
You do not need one for a game where participants advance each tick themselves, and you do not need one just to end a game on a goal: the engine can do that alone.
|
|
29
31
|
|
|
32
|
+
Automatic or facilitator-led pacing is also a learning-design choice: a timer adds time pressure, while manual ticks leave the room time to discuss each decision.
|
|
33
|
+
|
|
30
34
|
## The result
|
|
31
35
|
|
|
32
36
|
`GetTickController` returns a [`TickControllerResult`](../api/sdk.md#tickcontrollerresult):
|
|
@@ -84,7 +88,7 @@ export const GetTickController: GetTickControllerFunction<Context, Settings> = a
|
|
|
84
88
|
|
|
85
89
|
### Interval bounds
|
|
86
90
|
|
|
87
|
-
The effective interval (the gap until the next automatic tick) is bounded: a minimum of 30 seconds and a maximum of
|
|
91
|
+
The effective interval (the gap until the next automatic tick) is bounded: a minimum of 30 seconds and a maximum of seven days. `intervalTick()` rejects anything outside that range, as well as fractional, zero, negative, `NaN`, and `Infinity` values, with a message that names the limit and points you back at the helper. A value written in seconds fails loudly: `intervalTick(60)` is 60 milliseconds, and is refused with 'Effective tick cadence of 60 ms (under a second) is below the 30-second minimum (30000 ms)'. The same bounds apply to `scheduledTick()` (see [Scheduling at fixed times](#scheduling-at-fixed-times)), measured against the real gap to `nextTickAt`. If a game needs to tick less often than once a week, set `enabled: false` and drive ticks by another means.
|
|
88
92
|
|
|
89
93
|
### Cadence cookbook
|
|
90
94
|
|
|
@@ -383,7 +387,7 @@ Each call has a time limit, like an engine call (see [Time limits](./engine.md#t
|
|
|
383
387
|
|
|
384
388
|
### Results outside the bounds
|
|
385
389
|
|
|
386
|
-
A result the helpers would refuse, such as a hand-written `intervalMs: 10_000`, is not honoured as it stands. The dev server clamps it to the nearest bound, 30 seconds or
|
|
390
|
+
A result the helpers would refuse, such as a hand-written `intervalMs: 10_000`, is not honoured as it stands. The dev server clamps it to the nearest bound, 30 seconds or seven days, and reports the clamp as an error so you see it, which is what a production runtime does too. Build your results with `intervalTick()` and `scheduledTick()` to catch this while you write the controller rather than while it runs.
|
|
387
391
|
|
|
388
392
|
A result holds only `enabled`, `intervalMs`, `nextTickAt` and `complete`, and `enabled` and `complete` are booleans. A result with any other key, or with `complete: 'no'`, is not clamped: the evaluation fails, the failure is reported naming the key, and the timer stops, as it does when the controller throws.
|
|
389
393
|
|
|
@@ -507,7 +511,7 @@ Put the timezone in the tick controller's settings to make it configurable per g
|
|
|
507
511
|
|
|
508
512
|
The `intervalMs` field is computed for you, so a UI drawing a progress bar has the window's full length to draw against.
|
|
509
513
|
|
|
510
|
-
`scheduledTick()` validates the effective cadence (the real gap to `nextTickAt`) against the same 30-second floor and
|
|
514
|
+
`scheduledTick()` validates the effective cadence (the real gap to `nextTickAt`) against the same 30-second floor and seven-day ceiling as `intervalTick()`. A schedule that would tick sooner than 30 seconds out, or further than seven days out, is rejected with a clear message rather than honoured. A `nextTickAt` already in the past is exempt: it fires one immediate catch-up tick (see [Missed ticks](#missed-ticks)).
|
|
511
515
|
|
|
512
516
|
### Missed ticks
|
|
513
517
|
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
# Type safety best practices
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The SDK generates TypeScript types from your schemas, so a misspelt variable fails when you build rather than in front of a room.
|
|
4
|
+
|
|
5
|
+
This guide covers the rules that keep that guarantee, and the shortcuts that quietly break it.
|
|
4
6
|
|
|
5
7
|
## Core principle
|
|
6
8
|
|
|
@@ -496,11 +498,11 @@ export interface Context {
|
|
|
496
498
|
|
|
497
499
|
Type safety in Serious Gaming:
|
|
498
500
|
|
|
499
|
-
1. **Catches mistakes at build time
|
|
500
|
-
2. **IDE assistance
|
|
501
|
-
3. **Self-documenting code
|
|
502
|
-
4. **Prevents silent failures
|
|
503
|
-
5. **Easier debugging
|
|
501
|
+
1. **Catches mistakes at build time**: not runtime
|
|
502
|
+
2. **IDE assistance**: autocomplete, rename refactoring
|
|
503
|
+
3. **Self-documenting code**: types are documentation
|
|
504
|
+
4. **Prevents silent failures**: schema enforces constraints
|
|
505
|
+
5. **Easier debugging**: stack traces point to real issues, not parsing errors
|
|
504
506
|
|
|
505
507
|
When you skip proper typing, you:
|
|
506
508
|
|
package/dist/docs/guides/ui.md
CHANGED
|
@@ -1,15 +1,8 @@
|
|
|
1
1
|
# Building user interfaces
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The game UI is what each participant sees and plays: where they read the situation, make decisions, and see what those decisions caused.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
- How to create a new user interface
|
|
8
|
-
- How to read game context and settings
|
|
9
|
-
- How to write to context and request a tick
|
|
10
|
-
- How to work with participants, teams, observers, and walkthroughs
|
|
11
|
-
- How to show the tick timer, localise, theme, and upload files
|
|
12
|
-
- How to reach an LLM from a UI, through an endpoint
|
|
5
|
+
This guide covers creating it, reading the game's state and settings, writing decisions back, and styling, testing, and building it.
|
|
13
6
|
|
|
14
7
|
## Creating a user interface
|
|
15
8
|
|
|
@@ -80,6 +73,7 @@ The `useUserInterfaceData` hook provides:
|
|
|
80
73
|
|
|
81
74
|
- **`data`**: The game context (read-only by default)
|
|
82
75
|
- **`settings`**: The settings resources this UI lists in `settings`, keyed by identifier (`settings.ui.RefreshRate`). Read-only, and fixed when play starts
|
|
76
|
+
- **`scenarioName`**: The name of the scenario the session is running, in the session's language, or `null` with none. For display only: show it, never branch on it, because a facilitator's own copy of a scenario has a name of its own (see [Showing the scenario](./engine.md#showing-the-scenario))
|
|
83
77
|
- **`completedTicks`**: The number of ticks this team has completed: `0` until the first tick commits, `N - 1` while round N is played. Use it to bound a review scrubber (see below)
|
|
84
78
|
- **`isRoundProcessing`**: Whether the host is running a tick right now (see below)
|
|
85
79
|
- **`setData`**: Function to update context (available only for capabilities in `writes`)
|
|
@@ -212,11 +206,11 @@ Because arrays replace wholesale, a shared array that participants read, modify,
|
|
|
212
206
|
|
|
213
207
|
Understanding when `setData` changes become visible is critical for designing your game loop correctly.
|
|
214
208
|
|
|
215
|
-
1. **Immediate in context**: When a UI calls `setData`, the change is merged into the game context right away. Other UIs reading the same capability will see the updated value immediately (via WebSocket sync in the dev server)
|
|
209
|
+
1. **Immediate in context**: When a UI calls `setData`, the change is merged into the game context right away. Other UIs reading the same capability will see the updated value immediately (via WebSocket sync in the dev server)
|
|
216
210
|
|
|
217
|
-
2. **Engines process on next tick**: Engine `Run` functions only execute when a tick advances. They see whatever context exists at that point, including any `setData` changes made since the last tick
|
|
211
|
+
2. **Engines process on next tick**: Engine `Run` functions only execute when a tick advances. They see whatever context exists at that point, including any `setData` changes made since the last tick
|
|
218
212
|
|
|
219
|
-
3. **Multiple `setData` calls accumulate**: If a participant changes Price to 50, then to 75 before the next tick, the engine will see 75. Only the final state matters
|
|
213
|
+
3. **Multiple `setData` calls accumulate**: If a participant changes Price to 50, then to 75 before the next tick, the engine will see 75. Only the final state matters
|
|
220
214
|
|
|
221
215
|
**Design implication**: Use `setData` for participant input within a tick (decisions, adjustments, form entries). Use tick advancement to trigger computation (the engine runs, state updates cascade). Don't try to run game logic inside `setData` handlers: that bypasses the tick mechanism and breaks the reactive spreadsheet model.
|
|
222
216
|
|
|
@@ -265,10 +259,10 @@ const handleStart = () => {
|
|
|
265
259
|
|
|
266
260
|
This works correctly: the `setData` change is merged into context immediately, and the tick that follows will see `Started: true` when the engine runs. However, there is a brief intermediate state that is worth understanding:
|
|
267
261
|
|
|
268
|
-
1. **`setData` merges immediately**: the local UI and all connected UIs see `Started: true` right away
|
|
269
|
-
2. **`requestTick` is asynchronous**: the tick message is sent to the host, which queues and executes the tick. This takes a few milliseconds
|
|
270
|
-
3. **Between steps 1 and 2**, UIs see the `setData` change but the engine has not yet run. If the engine computes derived values (e.g. a status message based on `Started`), the UI will briefly show the raw `setData` values without the engine-computed results
|
|
271
|
-
4. **After the tick completes**, the host broadcasts updated context to all UIs. This overwrites the intermediate state with the fully computed post-tick values
|
|
262
|
+
1. **`setData` merges immediately**: the local UI and all connected UIs see `Started: true` right away
|
|
263
|
+
2. **`requestTick` is asynchronous**: the tick message is sent to the host, which queues and executes the tick. This takes a few milliseconds
|
|
264
|
+
3. **Between steps 1 and 2**, UIs see the `setData` change but the engine has not yet run. If the engine computes derived values (e.g. a status message based on `Started`), the UI will briefly show the raw `setData` values without the engine-computed results
|
|
265
|
+
4. **After the tick completes**, the host broadcasts updated context to all UIs. This overwrites the intermediate state with the fully computed post-tick values
|
|
272
266
|
|
|
273
267
|
In most cases this intermediate state is invisible to the participant, because the tick completes in milliseconds. But if your UI derives display values from both `setData` fields and engine-computed fields, you may see a brief flicker. Two strategies to handle this:
|
|
274
268
|
|
|
@@ -656,8 +650,8 @@ This pattern is deliberate: by keeping the per-frame state inside one leaf compo
|
|
|
656
650
|
|
|
657
651
|
`nextTickAt` is an absolute timestamp in the **same clock-space as `Date.now()`**, so consumer code never needs to compute clock offsets: just subtract. The host is responsible for stamping it in a clock the consumer will recognise:
|
|
658
652
|
|
|
659
|
-
- For dev-server-hosted games (the default), the dev server, the console and your iframe all share `Date.now()`, so `nextTickAt` is correct as-is
|
|
660
|
-
- For cross-machine deployments, hosts rely on NTP-synced wall clocks. NTP keeps machines within tens of milliseconds of each other, well below the granularity of a second-level countdown
|
|
653
|
+
- For dev-server-hosted games (the default), the dev server, the console and your iframe all share `Date.now()`, so `nextTickAt` is correct as-is
|
|
654
|
+
- For cross-machine deployments, hosts rely on NTP-synced wall clocks. NTP keeps machines within tens of milliseconds of each other, well below the granularity of a second-level countdown
|
|
661
655
|
|
|
662
656
|
The wrapper does not attempt to re-translate `nextTickAt` on receipt. With only the value and the receiver's `Date.now()` it cannot distinguish 'the host's clock is N ms ahead of mine' from 'this message has been sitting around for N ms', and getting that wrong is exactly how a stored timer state replayed to a remounted iframe would drift. Trusting the timestamp verbatim is what makes the countdown stay accurate when the iframe is remounted.
|
|
663
657
|
|
|
@@ -996,10 +990,10 @@ type UserInterfaceModeColors = {
|
|
|
996
990
|
};
|
|
997
991
|
```
|
|
998
992
|
|
|
999
|
-
- `mode`: Indicates whether the current theme is `'light'` or `'dark'
|
|
1000
|
-
- `light`: An object containing the colour palette for the light theme
|
|
1001
|
-
- `dark`: An object containing the colour palette for the dark theme
|
|
1002
|
-
- `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
|
|
993
|
+
- `mode`: Indicates whether the current theme is `'light'` or `'dark'`
|
|
994
|
+
- `light`: An object containing the colour palette for the light theme
|
|
995
|
+
- `dark`: An object containing the colour palette for the dark theme
|
|
996
|
+
- `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
|
|
1003
997
|
|
|
1004
998
|
```tsx
|
|
1005
999
|
const colors = theme.mode === 'light' ? theme.light : theme.dark;
|
|
@@ -1041,48 +1035,33 @@ function ThemeSwitcher() {
|
|
|
1041
1035
|
}
|
|
1042
1036
|
```
|
|
1043
1037
|
|
|
1044
|
-
`setThemePreference` is available on every UI surface (game, waiting room, session,
|
|
1038
|
+
`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.
|
|
1045
1039
|
|
|
1046
1040
|
### Integrating with Material-UI
|
|
1047
1041
|
|
|
1048
|
-
The default user interface template uses [Material-UI](https://mui.com/) for its component library.
|
|
1049
|
-
|
|
1050
|
-
Here's how to create a dynamic theme in your `App.tsx`:
|
|
1042
|
+
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:
|
|
1051
1043
|
|
|
1052
1044
|
```typescript
|
|
1053
|
-
// src/
|
|
1054
|
-
import
|
|
1055
|
-
import {
|
|
1056
|
-
import {
|
|
1057
|
-
import MyComponent from './MyComponent';
|
|
1045
|
+
// src/theme.ts
|
|
1046
|
+
import { createTheme } from '@mui/material/styles';
|
|
1047
|
+
import { createSurfaceTheme, useUserInterfaceTheme } from '@seriousgaming/sdk/ui';
|
|
1048
|
+
import { useMemo } from 'react';
|
|
1058
1049
|
|
|
1059
|
-
|
|
1050
|
+
export const useAppTheme = () => {
|
|
1060
1051
|
const theme = useUserInterfaceTheme();
|
|
1061
|
-
|
|
1062
|
-
|
|
1063
|
-
|
|
1064
|
-
|
|
1065
|
-
|
|
1066
|
-
|
|
1067
|
-
primary: { main: themeColors.primary, contrastText: themeColors.contrastText.primary },
|
|
1068
|
-
secondary: { main: themeColors.secondary, contrastText: themeColors.contrastText.secondary },
|
|
1069
|
-
success: { main: themeColors.success, contrastText: themeColors.contrastText.success },
|
|
1070
|
-
error: { main: themeColors.error, contrastText: themeColors.contrastText.error },
|
|
1071
|
-
warning: { main: themeColors.warning, contrastText: themeColors.contrastText.warning },
|
|
1072
|
-
info: { main: themeColors.info, contrastText: themeColors.contrastText.info },
|
|
1073
|
-
}
|
|
1074
|
-
});
|
|
1075
|
-
}, [theme]);
|
|
1076
|
-
|
|
1077
|
-
return (
|
|
1078
|
-
<ThemeProvider theme={customTheme}>
|
|
1079
|
-
<MyComponent />
|
|
1080
|
-
</ThemeProvider>
|
|
1052
|
+
return useMemo(
|
|
1053
|
+
() =>
|
|
1054
|
+
createTheme(createSurfaceTheme(theme, { fonts: { body: 'Work Sans Variable' } }), {
|
|
1055
|
+
shape: { borderRadius: 10 },
|
|
1056
|
+
}),
|
|
1057
|
+
[theme]
|
|
1081
1058
|
);
|
|
1082
|
-
}
|
|
1059
|
+
};
|
|
1083
1060
|
```
|
|
1084
1061
|
|
|
1085
|
-
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.
|
|
1062
|
+
`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.
|
|
1063
|
+
|
|
1064
|
+
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).
|
|
1086
1065
|
|
|
1087
1066
|
## Sizing to the viewport on mobile
|
|
1088
1067
|
|
|
@@ -1294,27 +1273,27 @@ The sections above are the parts of a complete chat surface. Beyond them, a chat
|
|
|
1294
1273
|
|
|
1295
1274
|
## Best practices
|
|
1296
1275
|
|
|
1297
|
-
1. **Use type safety
|
|
1276
|
+
1. **Use type safety**: import generated types from `./types`
|
|
1298
1277
|
- ✅ `useUserInterfaceData<Context, Settings>()`
|
|
1299
1278
|
- ❌ `useUserInterfaceData<any, any>()`
|
|
1300
1279
|
|
|
1301
|
-
2. **Access data via destructuring
|
|
1280
|
+
2. **Access data via destructuring**: get data, settings, and setData from the hook
|
|
1302
1281
|
- ✅ `const { data, settings, setData } = useUserInterfaceData<Context, Settings>()`
|
|
1303
1282
|
- ❌ Trying to access missing hooks like `useUserInterfaceContext`
|
|
1304
1283
|
|
|
1305
|
-
3. **Declare every capability you render
|
|
1284
|
+
3. **Declare every capability you render**: `data` carries exactly what the bundle declares
|
|
1306
1285
|
- ✅ Add the capability to `reads` (or `writes`) and read `data.inventory.Stock` directly
|
|
1307
1286
|
- ❌ Render a capability the bundle never declared and guard the `undefined` with `?.`
|
|
1308
1287
|
|
|
1309
|
-
4. **Respect write boundaries
|
|
1288
|
+
4. **Respect write boundaries**: only update capabilities in `writes`
|
|
1310
1289
|
- ✅ Use `setData` for capabilities in `writes`
|
|
1311
1290
|
- ❌ Try to update read-only capabilities
|
|
1312
1291
|
|
|
1313
|
-
5. **Responsive design
|
|
1292
|
+
5. **Responsive design**: ensure UIs work on different screen sizes
|
|
1314
1293
|
- ✅ Use flexbox/grid, size to the container, test on mobile
|
|
1315
1294
|
- ❌ Fixed widths, desktop-only design, `100vh` without a `dvh` fallback
|
|
1316
1295
|
|
|
1317
|
-
6. **Performance
|
|
1296
|
+
6. **Performance**: use React hooks efficiently
|
|
1318
1297
|
- ✅ `useEffect` for side effects, memoisation for expensive renders
|
|
1319
1298
|
- ❌ Recalculate everything on every render
|
|
1320
1299
|
|
|
@@ -1389,5 +1368,5 @@ See [Fix duplicate package errors in a UI](../recipes/fix-duplicate-packages.md)
|
|
|
1389
1368
|
|
|
1390
1369
|
## Next steps
|
|
1391
1370
|
|
|
1392
|
-
- [Internationalisation guide](./internationalization.md)
|
|
1393
|
-
- [Getting started](../getting-started.md)
|
|
1371
|
+
- [Internationalisation guide](./internationalization.md): add multi-language support
|
|
1372
|
+
- [Getting started](../getting-started.md): run the dev server
|
|
@@ -500,9 +500,11 @@ Every handler receives `session` (where the session stands: `completedTicks`, `m
|
|
|
500
500
|
grep -rn "caller.teamId" endpoints
|
|
501
501
|
```
|
|
502
502
|
|
|
503
|
-
### 7e. Give the scenario editor endpoints
|
|
503
|
+
### 7e. Give the scenario editor scenario-scoped endpoints
|
|
504
504
|
|
|
505
|
-
The scenario editor edits a scenario, not a session, so
|
|
505
|
+
The scenario editor edits a scenario, not a session, so it lists only endpoints declaring `"scope": "scenario"`, and the build refuses any other (`EDITOR_ENDPOINT_NOT_SCENARIO`). A 0.6 scenario builder could list any endpoint, because the dev server answered it from whatever session was running. For each endpoint the build names, set `"scope": "scenario"` and delete the `reads`, `writes`, `actions` and `roster` it declares (`SCENARIO_ENDPOINT_STATEFUL`), or give the editor an endpoint of its own. Then run `pnpm run sdk generate`. A scenario-scoped endpoint receives its declared `settings` as the scenario being edited resolves them, the editor's unsaved changes included, so declare `settings` rather than passing the values in the request. It receives no `context`, `participants` or `session`, which its generated `Handler` type no longer offers, and `caller` carries `role: 'author'` rather than `'facilitator'` and no `sessionId`, which is now optional: a handler that used it as a `string` needs a fallback, and one that checked for `'facilitator'` to accept the editor's calls checks for `'author'`. See [Scenario-scoped endpoints](./endpoints.md#scenario-scoped-endpoints).
|
|
506
|
+
|
|
507
|
+
**Already on 1.0?** This step is new in 1.1. 1.0 let the editor list a session-scoped endpoint that declared no `reads`, `writes` or `actions`, and 1.1 refuses it, so a package already on 1.0 with such an endpoint needs this step alone to move to 1.1. A production host that predates 1.1 refuses a scenario-scoped endpoint, so check the host supports it before you publish.
|
|
506
508
|
|
|
507
509
|
## Step 8: rename each validator's `Run` to `UpdateData`
|
|
508
510
|
|
|
@@ -631,7 +633,7 @@ Optional, but each item fixes a trap. A package created by `sdk new package` at
|
|
|
631
633
|
- **A stray `test.only` fails CI.** `playwright.config.ts.liquid` sets `forbidOnly` when `CI` is set, so one focused test no longer skips every other test. Merge it into `playwright.config.ts` if you did not replace that file above
|
|
632
634
|
- **The wrappers set `lang` and `dir`.** Delete the lines in each `main.tsx` that set them on the document
|
|
633
635
|
- **A shorter `CLAUDE.md` and refreshed rules.** Merge in the new `CLAUDE.md.template` and `claude/rules/` if you have not customised them heavily, as `workflow-update-sdk-version.md` describes
|
|
634
|
-
- **Refreshed dependencies.** Merge the versions in `package.json.liquid`, and after the Playwright bump run `pnpm exec playwright install chromium`
|
|
636
|
+
- **Refreshed dependencies.** Merge the versions in `package.json.liquid`, and after the Playwright bump run `pnpm exec playwright install chromium --only-shell` (drop `--only-shell` if you run tests with `--headed` or `--ui`)
|
|
635
637
|
|
|
636
638
|
Nothing breaks if you skip the new features 1.0 adds, but several replace workarounds games carry: the engine's private `state` and `complete: true` (see [Engine](./engine.md#keeping-memory-between-ticks) and [Game completion](./tick-controller.md#game-completion)), capabilities with `"lifetime": "session"` that undo and reset leave alone ([Lifetime](./capabilities.md#lifetime)), a facilitator's slide deck in the `presentation/` slot ([Building presentations](./presentation.md)), endpoints that act on the session or take files ([Endpoints](./endpoints.md)), and the `useAsset`, `usePastState` and `useViewerStorage` hooks ([User interfaces](./ui.md)).
|
|
637
639
|
|
|
@@ -661,6 +663,14 @@ pnpm run test:e2e
|
|
|
661
663
|
- Then search by hand for the changes no tool sees, listed at the top of this guide
|
|
662
664
|
- Finally, play a round in the dev server and check each surface, the timer and completion
|
|
663
665
|
|
|
666
|
+
## After 1.0
|
|
667
|
+
|
|
668
|
+
A minor release that changes a public type a test may build by hand lists it here as well as in the [changelog](../changelog.md).
|
|
669
|
+
|
|
670
|
+
### 1.2: give `Brand.icon` a variant for each background
|
|
671
|
+
|
|
672
|
+
`Brand.icon` is `{ onLight?, onDark? }`, the shape of `logo`, rather than one URL. Only a `Brand` you build yourself, in a test or a mock, needs the change: replace `icon: 'icon.svg'` with `icon: { onLight: 'icon.svg', onDark: 'icon.svg' }`, or a file for each. The wrapper turns a single icon from an older host into both variants, so a game reading the brand through `useBrandIcon()` needs nothing.
|
|
673
|
+
|
|
664
674
|
## Before you publish
|
|
665
675
|
|
|
666
676
|
A 1.0 build is a manifest version 3 package, and the platform must accept version 3 before you publish one. Until it does, the platform refuses the upload, and a version 2 package you published from 0.6 keeps running as it is. Check with Business Simulations that the platform you publish to accepts version 3 packages, and keep publishing from 0.6 until it does.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Validators
|
|
2
2
|
|
|
3
|
-
A validator is a read-only gate on what a participant does: a context write before it is applied, and a request for the next tick before it runs. It returns a verdict and never modifies the proposed state. The runtime applies the write, or runs the tick, only when every validator that runs allows it.
|
|
3
|
+
A validator is a read-only gate on what a participant does: a context write before it is applied, and a request for the next tick before it runs. It returns a verdict and never modifies the proposed state. The runtime applies the write, or runs the tick, only when every validator that runs allows it. A validator can also gate a scenario, refusing one whose settings break your game's rules ([Gating scenarios](#gating-scenarios)).
|
|
4
4
|
|
|
5
5
|
## The model
|
|
6
6
|
|
|
@@ -17,7 +17,7 @@ A validator sits between a UI's submission and the runtime's apply step, on the
|
|
|
17
17
|
type ValidationResult = { ok: true } | { ok: false; message: string };
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
-
A validator's logic exports one function per
|
|
20
|
+
A validator's logic exports one function per thing it gates. `UpdateData` gates a context write; `RequestTick` gates a request for the next tick ([Gating tick requests](#gating-tick-requests)); `Scenario` gates a scenario ([Gating scenarios](#gating-scenarios)). Export any of them: a validator is run only for what it has a gate for, and the build reads which from the exports, so there is nothing to declare in the bundle.
|
|
21
21
|
|
|
22
22
|
### Why reject rather than modify
|
|
23
23
|
|
|
@@ -61,7 +61,7 @@ validators/decisionlimit/
|
|
|
61
61
|
│ ├── logic.ts # UpdateData, and optionally RequestTick
|
|
62
62
|
│ └── logic.test.ts
|
|
63
63
|
├── defaults.ts # Generated: the starting context and settings, for tests
|
|
64
|
-
└── types.ts # Generated: Context, Settings, ValidatorFunction, RequestTickFunction
|
|
64
|
+
└── types.ts # Generated: Context, Settings, ValidatorFunction, RequestTickFunction, ScenarioFunction
|
|
65
65
|
```
|
|
66
66
|
|
|
67
67
|
`identifier` names the directory; it is not written into `validator.sdk.json`. The capabilities in `reads` must already exist (here, a `decisions` capability).
|
|
@@ -96,6 +96,8 @@ The validator receives:
|
|
|
96
96
|
|
|
97
97
|
The `message` string is free-form. The SDK does not prescribe a format, so games encode whatever structure they need (a locale key, a JSON blob) inside it.
|
|
98
98
|
|
|
99
|
+
A refusal is feedback to the participant, so make the message say why the decision was refused, not just that it was.
|
|
100
|
+
|
|
99
101
|
### Reads only
|
|
100
102
|
|
|
101
103
|
Validators declare `reads` but no `writes`. They are pure verdicts and cannot mutate state. The generated `Context` type reflects only the capabilities they read from.
|
|
@@ -187,6 +189,64 @@ It runs on every request, before the tick starts. The rule that a validator runs
|
|
|
187
189
|
|
|
188
190
|
A refusal stops the tick, and the participant's `requestTick()` rejects with the validator's message, as a refused write does. Only a request from a player surface (a participant's or an observer's) is gated. The facilitator's own tick, from the session surface or the console, and a timer's tick are never gated, which is what lets the facilitator run a round the room is not allowed to yet. Undo and reset are never validated. The `pacing` capability in the example above is a shared one the facilitator raises from the session UI as each round opens.
|
|
189
191
|
|
|
192
|
+
## Gating scenarios
|
|
193
|
+
|
|
194
|
+
A settings schema checks each value on its own. It cannot say that two values conflict, such as a lowest price above the highest, or that a value has no sensible default and every scenario must supply its own, such as the name of the client an edition is built for. A `Scenario` gate says both.
|
|
195
|
+
|
|
196
|
+
Export `Scenario` from a validator's logic. It receives the settings the validator lists in `settings`, resolved through the defaults and the scenario being judged, and the `locale` to phrase a problem in. It returns every problem it finds, each naming the setting it is about as a dotted `path`; an empty array passes:
|
|
197
|
+
|
|
198
|
+
```typescript
|
|
199
|
+
import type { ScenarioFunction } from '../types';
|
|
200
|
+
|
|
201
|
+
export const Scenario: ScenarioFunction = async ({ settings }) => {
|
|
202
|
+
const { MinPrice, MaxPrice } = settings.pricing;
|
|
203
|
+
const problems = [];
|
|
204
|
+
if (MinPrice > MaxPrice) {
|
|
205
|
+
problems.push({
|
|
206
|
+
path: 'pricing.MinPrice',
|
|
207
|
+
message: `The lowest price (£${MinPrice}) must be at or below the highest price (£${MaxPrice})`,
|
|
208
|
+
});
|
|
209
|
+
}
|
|
210
|
+
if (settings.edition.ClientName === '') {
|
|
211
|
+
problems.push({
|
|
212
|
+
path: 'edition.ClientName',
|
|
213
|
+
message: 'Every scenario names the client it is built for',
|
|
214
|
+
});
|
|
215
|
+
}
|
|
216
|
+
return problems;
|
|
217
|
+
};
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
A game whose validator exports `Scenario` lists the feature in `seriousgaming.sdk.json`, and the build refuses it otherwise (`FEATURE_UNDECLARED`). A runtime that cannot run the gate then refuses the game, rather than saving scenarios your rules would refuse:
|
|
221
|
+
|
|
222
|
+
```json
|
|
223
|
+
{
|
|
224
|
+
"requires": ["scenario-validation"]
|
|
225
|
+
}
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
### When it runs
|
|
229
|
+
|
|
230
|
+
- **`sdk build`** runs it on every scenario in `scenarios/`, and on the defaults alone when no scenario is the default, since a session can then run on no scenario. A problem fails the build (`SCENARIO_REFUSED`), pointing at the setting in the scenario's file
|
|
231
|
+
- **Saving a scenario** runs it, from the scenario editor, a form the platform generates, or an agent writing settings, and a problem refuses the save with every problem listed
|
|
232
|
+
- **Never when a session starts.** By then its scenario has passed
|
|
233
|
+
|
|
234
|
+
### It judges values, not where they came from
|
|
235
|
+
|
|
236
|
+
A saved scenario holds every setting, not only the ones its author changed, so the gate cannot tell a value the scenario supplied from one left at its default. Give a setting every scenario must replace an obviously empty default (`""`, `[]` or `{}`) and have the gate refuse that. Avoid a placeholder that could be a real choice, such as `0` for a price.
|
|
237
|
+
|
|
238
|
+
### Write problems a person or an agent can act on
|
|
239
|
+
|
|
240
|
+
A problem's message is shown as it is, to whoever is editing the scenario, and an AI agent editing one has nothing else to go on. Say what is allowed, not only what is wrong ('must be at or below the highest price', not 'invalid'), and give the `path` of the setting to change.
|
|
241
|
+
|
|
242
|
+
### Show the same problems while editing
|
|
243
|
+
|
|
244
|
+
The gate is the last word, and it runs on save. A [scenario editor](./scenario-editor.md) can show the same problems as the author types by importing the rules the gate uses. Put the rules in a file both can reach, such as `shared/scenario-rules.ts`, call it from the gate, and call it from the editor to mark each field. Rules shared with logic run in the logic environment too, so keep them to plain functions with no browser or Node APIs.
|
|
245
|
+
|
|
246
|
+
The gate reads no game state and receives no `actor`, `meta` or callbacks: there is no session or participant behind a scenario. It ignores the validator's `reads`, so a validator that only exports `Scenario` declares none.
|
|
247
|
+
|
|
248
|
+
The gate runs when a scenario is saved, not each time one is used, so a scenario a facilitator saved before you added or tightened a rule has never met it. Bump `scenarioFormat` in `seriousgaming.sdk.json` when you do, and a runtime stops using those older scenarios. See [Scenario format: when to bump it](./scenarios.md#scenario-format-when-to-bump-it).
|
|
249
|
+
|
|
190
250
|
## Settings
|
|
191
251
|
|
|
192
252
|
A validator reads [settings](./settings.md) the way every other resource does: list the settings resources in the bundle's `settings`, and it receives exactly those as `settings`, keyed by identifier. They resolve through the same layers as the engine's, so a scenario or the facilitator's setup screen can change a limit without touching the logic.
|
|
@@ -214,4 +274,5 @@ if (selected > settings.decisionlimit.MaxSelected) {
|
|
|
214
274
|
## Related
|
|
215
275
|
|
|
216
276
|
- [Create a validator recipe](../recipes/create-validator.md): step-by-step scaffolding
|
|
277
|
+
- [Validate a game's scenarios recipe](../recipes/validate-scenarios.md): add a `Scenario` gate
|
|
217
278
|
- [Hooks guide](hooks.md): for out-of-tick reactions
|