@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
|
@@ -33,6 +33,8 @@ Most steps are mechanical and the compiler finds what they break. **These change
|
|
|
33
33
|
|
|
34
34
|
The [changelog](../changelog.md) carries the detail behind every step.
|
|
35
35
|
|
|
36
|
+
**Keywords:** upgrade, migrate, migration, 0.6 to 1.0, breaking changes, configurationSchema, settings resources, @seriousgaming, rename packages, upgrade steps
|
|
37
|
+
|
|
36
38
|
## Step 1: rename the packages
|
|
37
39
|
|
|
38
40
|
The three public packages move to the `@seriousgaming` scope on the public npm registry, and install without a token. Their subpaths are unchanged, and so is the `seriousgaming-sdk` command, so `pnpm run sdk` keeps working.
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
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
|
+
**Keywords:** validator, validation, reject, gate, UpdateData, RequestTick, Scenario gate, actor, business rules, refuse a write, check a tick request, validate scenarios
|
|
6
|
+
|
|
5
7
|
## The model
|
|
6
8
|
|
|
7
9
|
Some rules cannot be written in `variablesSchema`. JSON Schema handles the shape of the data ('Price must be a non-negative number'), but not a rule across fields, such as 'only three of these ten booleans may be true at once' or 'the budget across these fields must not exceed N'. The engine cannot gate such a rule either, because it runs on the tick rather than when a UI submits. That leaves the front end, which is the wrong layer for an integrity rule: devtools bypass it, and so do test scripts and future non-web clients.
|
|
@@ -193,9 +195,11 @@ A refusal stops the tick, and the participant's `requestTick()` rejects with the
|
|
|
193
195
|
|
|
194
196
|
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
197
|
|
|
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
|
|
198
|
+
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 by its `path`; an empty array passes:
|
|
197
199
|
|
|
198
200
|
```typescript
|
|
201
|
+
import { settingPath } from '@seriousgaming/sdk';
|
|
202
|
+
|
|
199
203
|
import type { ScenarioFunction } from '../types';
|
|
200
204
|
|
|
201
205
|
export const Scenario: ScenarioFunction = async ({ settings }) => {
|
|
@@ -203,13 +207,13 @@ export const Scenario: ScenarioFunction = async ({ settings }) => {
|
|
|
203
207
|
const problems = [];
|
|
204
208
|
if (MinPrice > MaxPrice) {
|
|
205
209
|
problems.push({
|
|
206
|
-
path: 'pricing
|
|
210
|
+
path: settingPath('pricing', 'MinPrice'),
|
|
207
211
|
message: `The lowest price (£${MinPrice}) must be at or below the highest price (£${MaxPrice})`,
|
|
208
212
|
});
|
|
209
213
|
}
|
|
210
214
|
if (settings.edition.ClientName === '') {
|
|
211
215
|
problems.push({
|
|
212
|
-
path: 'edition
|
|
216
|
+
path: settingPath('edition', 'ClientName'),
|
|
213
217
|
message: 'Every scenario names the client it is built for',
|
|
214
218
|
});
|
|
215
219
|
}
|
|
@@ -217,6 +221,8 @@ export const Scenario: ScenarioFunction = async ({ settings }) => {
|
|
|
217
221
|
};
|
|
218
222
|
```
|
|
219
223
|
|
|
224
|
+
A `path` is a setting path: `pricing.MinPrice`, the settings identifier and each key below it (see [How a setting is named](./settings.md#how-a-setting-is-named)). An editor reads it back to show the problem beside its field. Build it with `settingPath` rather than joining keys with dots, so a map entry whose key holds a dot is still named one way: `settingPath('cast', 'Portraits', 'a.b')` is `cast.Portraits["a.b"]`.
|
|
225
|
+
|
|
220
226
|
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
227
|
|
|
222
228
|
```json
|
|
@@ -225,6 +231,60 @@ A game whose validator exports `Scenario` lists the feature in `seriousgaming.sd
|
|
|
225
231
|
}
|
|
226
232
|
```
|
|
227
233
|
|
|
234
|
+
### Checking the files a scenario names
|
|
235
|
+
|
|
236
|
+
A rule about a file setting is often a rule about the file: that the portrait is there, or that the briefing is not empty. List `scenario-files` in `requires` beside `scenario-validation`, and the gate receives `callbacks` with two file reads, `readAsset` and `describeAsset`:
|
|
237
|
+
|
|
238
|
+
```json
|
|
239
|
+
{
|
|
240
|
+
"requires": ["scenario-validation", "scenario-files"]
|
|
241
|
+
}
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
```typescript
|
|
245
|
+
import type { ScenarioFunction } from '../types';
|
|
246
|
+
|
|
247
|
+
export const Scenario: ScenarioFunction = async ({ settings, callbacks }) => {
|
|
248
|
+
const portrait = settings.cast.CeoPortrait;
|
|
249
|
+
if (portrait !== '' && (await callbacks.describeAsset(portrait)) === undefined) {
|
|
250
|
+
return [
|
|
251
|
+
{
|
|
252
|
+
path: 'cast.CeoPortrait',
|
|
253
|
+
message: `The CEO's portrait (${portrait}) is not a file this scenario has. Upload it again`,
|
|
254
|
+
},
|
|
255
|
+
];
|
|
256
|
+
}
|
|
257
|
+
return [];
|
|
258
|
+
};
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
- **They read the scenario being judged.** At build, `asset:` resolves against that scenario's own `assets/` and `shared:` against `shared-assets/`; a package scenario cannot name a blob, so a `blob:` reference finds nothing. On save, a draft's files resolve as the draft reads them: the built-in scenario it descends from, which for a draft of a package scenario is that scenario, and the files uploaded to it
|
|
262
|
+
- **`describeAsset`** answers `{ mimeType, size }`, or `undefined` for a file that is not there, without reading it. Prefer it when you only need to know the file exists or fits. **`readAsset`** returns the bytes, and rejects for a file that is not there
|
|
263
|
+
- **Nothing else.** No `generateText` and no `extractText`: the gate stays quick and gives the same answer every time. A rule that needs either belongs in an endpoint the scenario editor calls
|
|
264
|
+
- **Reads count against the gate's time limit**, so a gate reading every video whole may run out of time and refuse the scenario. Use `describeAsset` for those
|
|
265
|
+
- **`readAsset` reads nothing over 10 MB.** For a larger file it rejects with a `ScenarioAssetTooLargeError`, before reading any of it, and unless you catch it the gate counts as refusing the scenario: the build fails, or the save is refused, naming the file, its size and the limit. The limit is `SCENARIO_GATE_READ_LIMIT_BYTES` from `@seriousgaming/sdk` (10,485,760 bytes), the same in every runtime, so the gate gives the same answer at build and on save. To check that a video is there, or how big it is, call `describeAsset`, which works on a file of any size. To catch the error, test its `name`, not `instanceof`: the gate may run apart from the SDK that defines the class
|
|
266
|
+
- **Without `scenario-files`**, each call throws, naming the feature, and the gate counts as refusing the scenario. The build cannot tell in advance whether your gate reads a file, so this is where you find out
|
|
267
|
+
- **Your generated `ScenarioFunction` requires `callbacks`** once the package lists the feature, so a test calls the gate with them. Build them from plain functions:
|
|
268
|
+
|
|
269
|
+
```typescript
|
|
270
|
+
const judge = (ui: Partial<Settings['ui']>) =>
|
|
271
|
+
Scenario({
|
|
272
|
+
settings: { ui: { ...defaultSettings.ui, ...ui } },
|
|
273
|
+
locale: 'en',
|
|
274
|
+
callbacks: {
|
|
275
|
+
describeAsset: async (reference) =>
|
|
276
|
+
reference === 'shared:branding/logo.svg'
|
|
277
|
+
? { mimeType: 'image/svg+xml', size: 2048 }
|
|
278
|
+
: undefined,
|
|
279
|
+
readAsset: async (reference) => {
|
|
280
|
+
throw new Error(`${reference} is not read in this test`);
|
|
281
|
+
},
|
|
282
|
+
},
|
|
283
|
+
});
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
`examples/factory`'s `scenariocheck` validator refuses a scenario whose branding logo is not a file it has.
|
|
287
|
+
|
|
228
288
|
### When it runs
|
|
229
289
|
|
|
230
290
|
- **`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
|
|
@@ -243,7 +303,7 @@ A problem's message is shown as it is, to whoever is editing the scenario, and a
|
|
|
243
303
|
|
|
244
304
|
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
305
|
|
|
246
|
-
The gate reads no game state and receives no `actor
|
|
306
|
+
The gate reads no game state and receives no `actor` or `meta`: there is no session or participant behind a scenario. Its only callbacks are the file reads above. It ignores the validator's `reads`, so a validator that only exports `Scenario` declares none.
|
|
247
307
|
|
|
248
308
|
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
309
|
|
|
@@ -174,7 +174,7 @@ await renameOwnTeam('The Cartographers');
|
|
|
174
174
|
|
|
175
175
|
It names no team: the host resolves the caller's, so a surface can only rename its own. Render `useUserInterfaceOwnTeam()?.name` rather than what you sent, because a facilitator may rename the same team at the same moment and the last write wins. A blank or over-long name is refused as a terminal `MutationError`. See [Letting a team name itself](./ui.md) for the full contract.
|
|
176
176
|
|
|
177
|
-
The lobby is also where a participant notices they mistyped their own name. Where `useUserInterfaceCanRenameSelf()` is `true`, `renameSelf(name)` fixes it. See [Letting a participant fix their own name](./ui.md#letting-a-participant-fix-their-own-name).
|
|
177
|
+
The lobby is also where a participant notices they mistyped their own name. Where `useUserInterfaceCanRenameSelf()` is `true`, `renameSelf(name)` fixes it. See [Letting a participant fix their own name](./ui-participants.md#letting-a-participant-fix-their-own-name).
|
|
178
178
|
|
|
179
179
|
## Stopping the clock
|
|
180
180
|
|
package/dist/docs/index.md
CHANGED
|
@@ -49,6 +49,7 @@ The SDK and the deck library are Apache-2.0. The CLI and the dev server are unde
|
|
|
49
49
|
- **[Guides](./guides/index.md)**: one page per resource kind or topic, explaining it and serving as its reference
|
|
50
50
|
- **[Recipes](./recipes/index.md)**: one task each, step by step
|
|
51
51
|
- **[API reference](./api/index.md)**: every export of the SDK, the deck library and the test client, one page per entry point
|
|
52
|
+
- **[Page index](./page-index.md)**: every page with a one-sentence summary and its length, to find the page for a fact
|
|
52
53
|
|
|
53
54
|
## The CLI and the dev server
|
|
54
55
|
|
|
@@ -68,4 +69,4 @@ The SDK and the deck library are Apache-2.0. The CLI and the dev server are unde
|
|
|
68
69
|
- **[Upgrading](./guides/upgrading.md)**: the steps from 0.6 to 1.0
|
|
69
70
|
- **[Changelog for 0.x](./changelog-0.x.md)**: every release before 1.0
|
|
70
71
|
|
|
71
|
-
The docs at sdk.seriousgaming.com describe the newest release. The docs for the version you have installed ship inside it: `pnpm run sdk docs view` lists them and prints any page, and `pnpm run sdk docs export` copies them into your package for an editor or agent to search.
|
|
72
|
+
The docs at sdk.seriousgaming.com describe the newest release. The docs for the version you have installed ship inside it: `pnpm run sdk docs view` lists them and prints any page, or one section of it with `--section`, and `pnpm run sdk docs export` copies them into your package for an editor or agent to search.
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
<!-- Generated by `pnpm docs:generate` from every page under `sdk-tools/docs` and `sdk-tools/docs-partials/page-index/`. Edit those, not this file. -->
|
|
2
|
+
|
|
3
|
+
# Page index
|
|
4
|
+
|
|
5
|
+
Every page of the documentation, with a one-sentence summary and its length, so you can find the page that holds a fact before you read anything long.
|
|
6
|
+
|
|
7
|
+
**Keywords:** index, page index, table of contents, sitemap, find a page, outline, sections, page length, search the docs
|
|
8
|
+
|
|
9
|
+
Many guides are long: the longest run past 60,000 characters. Rather than reading one whole, find it here, list its sections with `--outline`, and read the one you need with `--section`:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
pnpm run --silent sdk docs view page-index.md
|
|
13
|
+
pnpm run --silent sdk docs view guides/session.md --outline
|
|
14
|
+
pnpm run --silent sdk docs view guides/session.md --section 'Building the session UI'
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
`--section` takes a heading's text or its slug, the anchor the outline prints beside it, and returns the heading and everything under it up to the next heading of the same or a higher level. Add `--json` to either for the result as data. Each page also carries a `**Keywords:**` line, so `grep -rn` over the docs lands on the right one.
|
|
18
|
+
|
|
19
|
+
This index lists pages; `--outline` lists a page's sections, each with its slug and its exact length. Lengths here are rounded to the nearest thousand characters, and the changelogs, which grow with every release, are listed without one.
|
|
20
|
+
|
|
21
|
+
## Start here and reference
|
|
22
|
+
|
|
23
|
+
- [`index.md`](index.md), about 6k characters: The Serious Gaming SDK is for building serious games: facilitated learning experiences, such as business simulations and experiential learning, in which teams make decisions and see the consequences.
|
|
24
|
+
- [`ai-agents.md`](ai-agents.md), about 5k characters: An AI coding agent can build, check, and play a serious game with this SDK from the terminal alone, with no browser and no prompt to answer.
|
|
25
|
+
- [`changelog-0.x.md`](changelog-0.x.md): Every release before 1.0, from 0.0.1 to 0.6.0, kept as history.
|
|
26
|
+
- [`changelog.md`](changelog.md): All notable changes to the Serious Gaming SDK are recorded here.
|
|
27
|
+
- [`cli-and-dev-server.md`](cli-and-dev-server.md), about 14k characters: The dev server runs your game on your own machine, with every screen in the browser, and the CLI plays and inspects the same session from the terminal.
|
|
28
|
+
- [`cli-error-codes.md`](cli-error-codes.md), about 31k characters: Every code a failed `seriousgaming-sdk` command can report.
|
|
29
|
+
- [`cli-reference.md`](cli-reference.md), about 158k characters: Every `seriousgaming-sdk` command and flag, in one place.
|
|
30
|
+
- [`cli-simulation-testing.md`](cli-simulation-testing.md), about 11k characters: Play a game from the terminal: configure it, start a session, make decisions, advance ticks, and read the state back as JSON.
|
|
31
|
+
- [`environment-variables.md`](environment-variables.md), about 9k characters: A single reference for every environment variable the dev server and CLI read.
|
|
32
|
+
- [`getting-started.md`](getting-started.md), about 11k characters: Scaffold the starter game, play it in the dev server, change one thing, and see the change.
|
|
33
|
+
- [`troubleshooting.md`](troubleshooting.md), about 34k characters: Find the symptom you are seeing, then read its cause and fix.
|
|
34
|
+
|
|
35
|
+
## Concepts
|
|
36
|
+
|
|
37
|
+
- [`concepts/index.md`](concepts/index.md), about 9k characters: The model behind the SDK on one page, and how its parts fit together.
|
|
38
|
+
- [`concepts/terminology.md`](concepts/terminology.md), about 26k characters: Definitions of the terms used across the SDK, the CLI, the dev server, and these docs.
|
|
39
|
+
|
|
40
|
+
## Guides
|
|
41
|
+
|
|
42
|
+
- [`guides/index.md`](guides/index.md), about 5k characters: Each guide is the one page for a resource kind or a topic: it explains the model, then serves as the reference, with every field, every option, and the rules behind them.
|
|
43
|
+
- [`guides/ai-facilitation.md`](guides/ai-facilitation.md), about 14k characters: A facilitator running your game may have an AI agent beside them: something they can ask 'how is Team B doing', 'why has their profit fallen', or 'set their unit price to 3.53'.
|
|
44
|
+
- [`guides/capabilities.md`](guides/capabilities.md), about 20k characters: Capabilities hold your game's state: named groups of variables that the engine and screens read and write.
|
|
45
|
+
- [`guides/designing-a-game.md`](guides/designing-a-game.md), about 9k characters: A serious game teaches by letting people act and then see what their actions caused.
|
|
46
|
+
- [`guides/designing-screens.md`](guides/designing-screens.md), about 12k characters: What a good simulation screen looks like, whatever the brand: how to decide what a screen should be before you build it, and how to check it afterwards.
|
|
47
|
+
- [`guides/endpoints.md`](guides/endpoints.md), about 29k characters: An endpoint is a named, server-side handler that a caller invokes by identifier: one of the game's own user interfaces, or a caller outside the game, such as a facilitator's AI agent or a platform API, when the endpoint allows it.
|
|
48
|
+
- [`guides/engine-testing.md`](guides/engine-testing.md), about 28k characters: Test your whole game in-process: no dev server, no browser, and no LLM API key required, because service callbacks are stubbed by default.
|
|
49
|
+
- [`guides/engine.md`](guides/engine.md), about 33k characters: The engine is the logic that moves your game forward: it sets up the board, then plays one round each tick.
|
|
50
|
+
- [`guides/file-handling.md`](guides/file-handling.md), about 28k characters: Ship files with your game or let participants upload them, then show them in any UI and read them in logic, all through one reference scheme.
|
|
51
|
+
- [`guides/games.md`](guides/games.md), about 7k characters: Shape the game as a whole: how many rounds it runs, how teams form, which languages it speaks, and where participants wait.
|
|
52
|
+
- [`guides/global-settings.md`](guides/global-settings.md), about 4k characters: The global settings file lets you store API keys and defaults once, in a single user-owned file, so every project picks them up.
|
|
53
|
+
- [`guides/guide.md`](guides/guide.md), about 10k characters: A facilitator guide bundles the run-sheet for a simulation into the package itself: markdown chapters and images that the host renders natively on the facilitator's page.
|
|
54
|
+
- [`guides/hooks.md`](guides/hooks.md), about 10k characters: A hook is logic that runs when the runtime emits a lifecycle signal, such as a participant joining a team.
|
|
55
|
+
- [`guides/internationalization.md`](guides/internationalization.md), about 11k characters: Run your game in more than one language: declare the locales it supports, then translate its screens, scenario content, dates, and numbers.
|
|
56
|
+
- [`guides/llm-integration.md`](guides/llm-integration.md), about 26k characters: Use generated text to give teams feedback, play characters, or write round reports that react to what they did.
|
|
57
|
+
- [`guides/multi-team-games.md`](guides/multi-team-games.md), about 35k characters: Let teams compete for one market, cooperate on a shared goal, or each play their own copy of the game.
|
|
58
|
+
- [`guides/patterns.md`](guides/patterns.md), about 12k characters: Three patterns for an engine's state and logic, each built up from the CLI commands that create its resources: a stock level that never goes negative, revenue computed in a second step, and a production loop split into one step per concern.
|
|
59
|
+
- [`guides/presentation.md`](guides/presentation.md), about 16k characters: Ship the facilitator's slide deck as part of the game, live with the session's results and exportable for anyone who wants to edit it.
|
|
60
|
+
- [`guides/production-constraints.md`](guides/production-constraints.md), about 10k characters: In production your UI bundle runs cross-origin, behind a strict content security policy and a short-lived auth cookie, and talks to the host only through a typed message channel.
|
|
61
|
+
- [`guides/scenario-editor.md`](guides/scenario-editor.md), about 10k characters: The `scenario_editor` slot holds the screen people use to build new scenarios for a released game, without rebuilding it.
|
|
62
|
+
- [`guides/scenarios.md`](guides/scenarios.md), about 31k characters: A scenario is a named set of settings overrides and static assets that makes a distinct flavour of a game: a different storyline, difficulty preset, or themed variant.
|
|
63
|
+
- [`guides/session-game-flow.md`](guides/session-game-flow.md), about 20k characters: How a session UI drives the session: ticks, the timer, host overlays, undo and reset, the waiting room, the language, the roster, and the participant list.
|
|
64
|
+
- [`guides/session-hooks.md`](guides/session-hooks.md), about 14k characters: Every hook a session UI reads its data and callbacks from, and the messages the host sends it.
|
|
65
|
+
- [`guides/session.md`](guides/session.md), about 23k characters: The session UI is the facilitator's view of the whole room: every team's position side by side, with the controls to run the session.
|
|
66
|
+
- [`guides/settings.md`](guides/settings.md), about 34k characters: Settings are a game's read-only parameters: a price, a difficulty, a round length, a menu, an answer key.
|
|
67
|
+
- [`guides/setup.md`](guides/setup.md), about 9k characters: The `setup` slot holds the small form a facilitator fills in when they create a session.
|
|
68
|
+
- [`guides/speech-generation.md`](guides/speech-generation.md), about 10k characters: Give characters and briefings a voice: generate speech from server-side logic and play it in any UI.
|
|
69
|
+
- [`guides/starter-game.md`](guides/starter-game.md), about 18k characters: `new package` hands you Lemonade Stand, a complete game rather than an empty shell.
|
|
70
|
+
- [`guides/testing.md`](guides/testing.md), about 32k characters: Test your engine's logic and your user interfaces, so a broken rule or a broken screen fails on your machine rather than in front of a room.
|
|
71
|
+
- [`guides/theming-and-branding.md`](guides/theming-and-branding.md), about 11k characters: 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.
|
|
72
|
+
- [`guides/tick-controller.md`](guides/tick-controller.md), about 30k characters: A tick controller makes ticks happen on their own, on a schedule your logic decides, and can say when the game is finished.
|
|
73
|
+
- [`guides/type-safety.md`](guides/type-safety.md), about 16k characters: The SDK generates TypeScript types from your schemas, so a misspelt variable fails when you build rather than in front of a room.
|
|
74
|
+
- [`guides/ui-files-and-llms.md`](guides/ui-files-and-llms.md), about 13k characters: How a game UI links to static assets, uploads and shows files, reads an asset's contents, and reaches an LLM through an endpoint to build a chat.
|
|
75
|
+
- [`guides/ui-participants.md`](guides/ui-participants.md), about 15k characters: 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.
|
|
76
|
+
- [`guides/ui-styling.md`](guides/ui-styling.md), about 11k characters: How a game UI handles language, theme, and screen size, and how to customise the Vite build that serves and bundles it.
|
|
77
|
+
- [`guides/ui-ticks.md`](guides/ui-ticks.md), about 15k characters: How a game UI ends a round and shows the time left: requesting a tick, awaiting a write or tick and handling a `MutationError`, and driving a countdown from the tick timer.
|
|
78
|
+
- [`guides/ui.md`](guides/ui.md), about 17k characters: The game UI is what each participant sees and plays: where they read the situation, make decisions, and see what those decisions caused.
|
|
79
|
+
- [`guides/upgrading.md`](guides/upgrading.md), about 66k characters: This guide takes a game package on 0.6 to 1.0, in 13 steps.
|
|
80
|
+
- [`guides/validators.md`](guides/validators.md), about 23k characters: 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.
|
|
81
|
+
- [`guides/waiting-room.md`](guides/waiting-room.md), about 14k characters: The waiting room is the holding screen participants see while a session is parked, and you can replace the host's stock panel with your own.
|
|
82
|
+
|
|
83
|
+
## Recipes
|
|
84
|
+
|
|
85
|
+
- [`recipes/index.md`](recipes/index.md), about 7k characters: Each recipe is one task, start to finish: prerequisites, numbered steps, a way to check it worked, and fixes for what usually goes wrong.
|
|
86
|
+
- [`recipes/act-on-the-session-from-an-endpoint.md`](recipes/act-on-the-session-from-an-endpoint.md), about 4k characters: Let one endpoint call do what a facilitator would otherwise do in several steps, such as posting a notice, closing the waiting room and starting the next round, under your game's own rules.
|
|
87
|
+
- [`recipes/adapt-a-game-for-walkthroughs.md`](recipes/adapt-a-game-for-walkthroughs.md), about 6k characters: A walkthrough is a disposable second run of your game beside the session, for demonstrating it: one team, one participant, always from tick 0, and isolated from the session in both directions.
|
|
88
|
+
- [`recipes/adapt-ui-for-observers.md`](recipes/adapt-ui-for-observers.md), about 4k characters: An observer is a facilitator watching one team's live game UI without joining as a team member.
|
|
89
|
+
- [`recipes/call-endpoint-from-ui.md`](recipes/call-endpoint-from-ui.md), about 6k characters: Call a server-side endpoint from any of your game's screens and handle its response or its failure.
|
|
90
|
+
- [`recipes/check-a-package-from-a-script.md`](recipes/check-a-package-from-a-script.md), about 5k characters: Validate a package and play a few ticks from CI or an AI agent, and turn each failure into the file and line to fix.
|
|
91
|
+
- [`recipes/create-capability.md`](recipes/create-capability.md), about 3k characters: Define a named slice of the game's state that the engine and screens read and write.
|
|
92
|
+
- [`recipes/create-endpoint.md`](recipes/create-endpoint.md), about 7k characters: Add a server-side handler your screens, or callers outside the game, can invoke by name with a validated request and response.
|
|
93
|
+
- [`recipes/create-engine.md`](recipes/create-engine.md), about 4k characters: Write the engine that moves the game on each tick: here, one that reads a price and writes the day's revenue.
|
|
94
|
+
- [`recipes/create-game.md`](recipes/create-game.md), about 3k characters: Set what your package's game is: its name in each locale, how long it runs, and its teams.
|
|
95
|
+
- [`recipes/create-guide.md`](recipes/create-guide.md), about 3k characters: Bundle a facilitator guide with your game: markdown chapters shown on the facilitator's page.
|
|
96
|
+
- [`recipes/create-hook.md`](recipes/create-hook.md), about 3k characters: React to a lifecycle signal, such as a participant joining a team, outside the tick loop.
|
|
97
|
+
- [`recipes/create-presentation.md`](recipes/create-presentation.md), about 7k characters: Ship the facilitator's slide deck with the game, so the briefing, the round dividers, the debriefs and the results travel with the package rather than in an email after train the trainer.
|
|
98
|
+
- [`recipes/create-scenario-editor.md`](recipes/create-scenario-editor.md), about 3k characters: Give people a screen for building new scenarios for your released game, without rebuilding it.
|
|
99
|
+
- [`recipes/create-scenario.md`](recipes/create-scenario.md), about 3k characters: Bundle a game flavour with settings overrides and static assets.
|
|
100
|
+
- [`recipes/create-session-ui.md`](recipes/create-session-ui.md), about 5k characters: Build the facilitator's screen: every team's state side by side, with controls to change values and run the session.
|
|
101
|
+
- [`recipes/create-settings.md`](recipes/create-settings.md), about 4k characters: Give a game a read-only parameter, such as a price, a difficulty, or an answer key, that its logic and screens read and that scenarios and facilitators can change before play starts.
|
|
102
|
+
- [`recipes/create-setup.md`](recipes/create-setup.md), about 3k characters: Give facilitators a short form at session creation that sets a few of your game's settings for that session only.
|
|
103
|
+
- [`recipes/create-tick-controller.md`](recipes/create-tick-controller.md), about 3k characters: Make ticks fire automatically, on an interval or a schedule your game's logic decides.
|
|
104
|
+
- [`recipes/create-user-interface.md`](recipes/create-user-interface.md), about 4k characters: Build the game UI: the screen each participant sees, showing the game's state and taking their decisions.
|
|
105
|
+
- [`recipes/create-validator.md`](recipes/create-validator.md), about 4k characters: Reject a participant's write that breaks the game's rules, before the runtime applies it.
|
|
106
|
+
- [`recipes/create-waiting-room-ui.md`](recipes/create-waiting-room-ui.md), about 5k characters: Replace the host's stock holding screen with your own, so participants see your branding and your words while the facilitator has the waiting room open.
|
|
107
|
+
- [`recipes/declare-api-uses.md`](recipes/declare-api-uses.md), about 4k characters: A logic-bearing resource (engine, hook, tick controller, endpoint) must declare the runtime callbacks it intends to call.
|
|
108
|
+
- [`recipes/design-state-for-concurrent-writes.md`](recipes/design-state-for-concurrent-writes.md), about 6k characters: Shape capabilities and `setData` calls so that several participants writing at once never overwrite each other.
|
|
109
|
+
- [`recipes/distribute-package.md`](recipes/distribute-package.md), about 3k characters: Wrap a built `dist/` directory into a single zip archive that a production runtime can ingest as an upload.
|
|
110
|
+
- [`recipes/e2e-testing.md`](recipes/e2e-testing.md), about 5k characters: Test your game's screens in a real browser against an isolated dev server.
|
|
111
|
+
- [`recipes/end-game-on-condition.md`](recipes/end-game-on-condition.md), about 5k characters: Stop a game automatically when a goal is reached, rather than after a fixed number of ticks.
|
|
112
|
+
- [`recipes/fix-duplicate-packages.md`](recipes/fix-duplicate-packages.md), about 4k characters: Resolve 'Invalid hook call' and similar errors caused by multiple copies of the same package being loaded by the dev server.
|
|
113
|
+
- [`recipes/make-a-guide-follow-the-scenario.md`](recipes/make-a-guide-follow-the-scenario.md), about 5k characters: Show the session's settings in the facilitator guide, and show content only to the scenarios that need it.
|
|
114
|
+
- [`recipes/make-an-endpoint-external.md`](recipes/make-an-endpoint-external.md), about 5k characters: Publish one of your endpoints to callers outside the game, such as a facilitator's AI agent or a platform API, so it can be invoked by asking or by another system rather than by clicking.
|
|
115
|
+
- [`recipes/negotiate-across-teams.md`](recipes/negotiate-across-teams.md), about 8k characters: Build a game where two teams propose, agree, and settle an exchange with each other, using a team-readable ledger and authoritative settlement at tick time.
|
|
116
|
+
- [`recipes/observe-other-teams-state.md`](recipes/observe-other-teams-state.md), about 8k characters: Let one team's user interface watch another team's pending decisions live, without waiting for a tick.
|
|
117
|
+
- [`recipes/publish-a-package.md`](recipes/publish-a-package.md), about 7k characters: Build, bundle, and upload a package to the Serious Gaming platform in a single command.
|
|
118
|
+
- [`recipes/remember-a-viewers-choice.md`](recipes/remember-a-viewers-choice.md), about 3k characters: A viewer's own choices, such as the tab they had open, a panel they collapsed, or a sort order, should survive a reload.
|
|
119
|
+
- [`recipes/review-a-past-day.md`](recipes/review-a-past-day.md), about 5k characters: Let participants scrub back through their team's committed ticks, or chart a value across every tick, with `usePastState` and `getPastState`.
|
|
120
|
+
- [`recipes/screenshot-a-surface.md`](recipes/screenshot-a-surface.md), about 5k characters: Capture one of your game's screens as a PNG from the command line, at the size and in the scheme you choose, with the errors the page reported.
|
|
121
|
+
- [`recipes/share-assets-across-scenarios.md`](recipes/share-assets-across-scenarios.md), about 5k characters: Reference one file from several scenarios without copying it, using a package-level `shared:` reference.
|
|
122
|
+
- [`recipes/share-logic-between-engine-and-ui.md`](recipes/share-logic-between-engine-and-ui.md), about 6k characters: Put a calculation in one file and use it from both your engine logic and your user interface, so a live preview cannot drift from the result the engine actually computes.
|
|
123
|
+
- [`recipes/show-all-teams-participants.md`](recipes/show-all-teams-participants.md), about 4k characters: Let a game UI read the participant roster of every team in a shared-state session, so it can render a directory of who is on each competing team.
|
|
124
|
+
- [`recipes/start-from-an-empty-package.md`](recipes/start-from-an-empty-package.md), about 6k characters: Build a game from nothing: a capability for its state, an engine that changes it each tick, and a game UI to show it.
|
|
125
|
+
- [`recipes/take-a-file-in-an-endpoint.md`](recipes/take-a-file-in-an-endpoint.md), about 4k characters: Let an endpoint accept a file, such as a team photo or a research PDF, from a game UI, a script calling the API, or an AI agent.
|
|
126
|
+
- [`recipes/test-a-multi-role-game.md`](recipes/test-a-multi-role-game.md), about 4k characters: Drive a game that needs several participants per team (for example a buyer and a seller who each act before a tick advances) from a single dev-server session, using the per-team participant roster.
|
|
127
|
+
- [`recipes/test-user-interface.md`](recipes/test-user-interface.md), about 5k characters: Write and run component tests for a user interface with Vitest, React Testing Library, and the SDK's render helpers.
|
|
128
|
+
- [`recipes/test-with-engine.md`](recipes/test-with-engine.md), about 5k characters: Test your whole game (engine, hooks, validators, endpoints, and completion) in one Node.js process, with no dev server, browser, or subprocess.
|
|
129
|
+
- [`recipes/upload-and-display-files.md`](recipes/upload-and-display-files.md), about 6k characters: Let a participant attach a file (a PDF, CSV, or image) in the game UI, show it back, and optionally summarise it in the engine.
|
|
130
|
+
- [`recipes/use-request-play.md`](recipes/use-request-play.md), about 2k characters: Leave the configuration step and start the game from within your setup screen, so operators can move to play from your own control as well as from the host's Play button.
|
|
131
|
+
- [`recipes/use-request-tick.md`](recipes/use-request-tick.md), about 3k characters: Trigger the next game tick from within your user interface, so participants submit their decisions via your own button.
|
|
132
|
+
- [`recipes/validate-scenarios.md`](recipes/validate-scenarios.md), about 4k characters: Refuse a scenario whose settings break your game's rules, at build and when one is saved, never when a session starts.
|
|
133
|
+
|
|
134
|
+
## API reference
|
|
135
|
+
|
|
136
|
+
- [`api/index.md`](api/index.md), about 7k characters: Every type, function, hook and component your game imports, one page per entry point.
|
|
137
|
+
- [`api/deck.md`](api/deck.md), about 8k characters: Every export of `@seriousgaming/deck`, with the declaration it is published with.
|
|
138
|
+
- [`api/sdk-commands.md`](api/sdk-commands.md), about 7k characters: What a client may ask a session to do.
|
|
139
|
+
- [`api/sdk-e2e.md`](api/sdk-e2e.md), about 11k characters: End-to-end testing helpers for Serious Gaming SDK consumers.
|
|
140
|
+
- [`api/sdk-projection.md`](api/sdk-projection.md), about 5k characters: The one documented shape of a session's observable state.
|
|
141
|
+
- [`api/sdk-testing.md`](api/sdk-testing.md), about 7k characters: Helpers for unit-testing a game's logic without a runtime.
|
|
142
|
+
- [`api/sdk-tools-client.md`](api/sdk-tools-client.md), about 14k characters: Programmatic API for testing a game in-process.
|
|
143
|
+
- [`api/sdk-ui-testing.md`](api/sdk-ui-testing.md), about 8k characters: Every export of `@seriousgaming/sdk/ui/testing`, with the declaration it is published with.
|
|
144
|
+
- [`api/sdk-ui.md`](api/sdk-ui.md), about 35k characters: Every export of `@seriousgaming/sdk/ui`, with the declaration it is published with.
|
|
145
|
+
- [`api/sdk.md`](api/sdk.md), about 58k characters: Every export of `@seriousgaming/sdk`, with the declaration it is published with.
|
|
@@ -129,5 +129,5 @@ Hold one line throughout: fill in the social context a solo run lacks, and suppr
|
|
|
129
129
|
## Related
|
|
130
130
|
|
|
131
131
|
- [Engines guide, walkthroughs](../guides/engine.md#walkthroughs)
|
|
132
|
-
- [Building user interfaces guide, walkthroughs](../guides/ui.md#walkthroughs)
|
|
132
|
+
- [Building user interfaces guide, walkthroughs](../guides/ui-participants.md#walkthroughs)
|
|
133
133
|
- [Adapt a UI for observers](adapt-ui-for-observers.md)
|
|
@@ -70,5 +70,5 @@ An observer is a facilitator watching one team's live game UI without joining as
|
|
|
70
70
|
|
|
71
71
|
## Related
|
|
72
72
|
|
|
73
|
-
- [User interfaces guide: observers](../guides/ui.md#observers)
|
|
73
|
+
- [User interfaces guide: observers](../guides/ui-participants.md#observers)
|
|
74
74
|
- [Observe other teams' state](observe-other-teams-state.md)
|
|
@@ -28,6 +28,16 @@ A game holds at most one presentation. It is read-only: it reads every team's st
|
|
|
28
28
|
|
|
29
29
|
### 1. Create the presentation
|
|
30
30
|
|
|
31
|
+
The starter game already fills the slot, so in a package made with `new package` change its `reads` and `settings` instead, then rewrite its slides in step 2:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
pnpm run sdk update presentation --patch '[
|
|
35
|
+
{ "op": "replace", "path": "/definition/reads", "value": ["results"] }
|
|
36
|
+
]'
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
In a package without one, create it:
|
|
40
|
+
|
|
31
41
|
```bash
|
|
32
42
|
pnpm run sdk new presentation '{
|
|
33
43
|
"definition": {
|
|
@@ -137,6 +147,7 @@ Open http://localhost:3000/presentation for the deck during the session, or http
|
|
|
137
147
|
|
|
138
148
|
## Related
|
|
139
149
|
|
|
150
|
+
- [Designing screens](../guides/designing-screens.md): the brief to write before you build, and the check to run after
|
|
140
151
|
- [Presentation guide](../guides/presentation.md): the slot, the deck library, resume and export
|
|
141
152
|
- [Create a facilitator guide](create-guide.md): the run sheet beside the deck
|
|
142
153
|
- [Create a scenario](create-scenario.md): vary the deck through settings and assets
|
|
@@ -97,6 +97,7 @@ Describe every property in the settings schema: `title`, `description` with unit
|
|
|
97
97
|
|
|
98
98
|
## Related
|
|
99
99
|
|
|
100
|
+
- [Designing screens](../guides/designing-screens.md): the brief to write before you build, and the check to run after
|
|
100
101
|
- [Create a setup screen](create-setup.md)
|
|
101
102
|
- [Create a scenario](create-scenario.md)
|
|
102
103
|
- [Scenarios guide](../guides/scenarios.md)
|
|
@@ -81,7 +81,7 @@ Build the facilitator's screen: every team's state side by side, with controls t
|
|
|
81
81
|
}
|
|
82
82
|
```
|
|
83
83
|
|
|
84
|
-
A `scope: 'shared'` capability arrives once, in `sessionData.shared.context`, and is written with the one-argument `setData(update)`. See [Writing shared capabilities](../guides/multi-team-games.md#facilitator-writable-shared-capabilities) and the [session UI hooks reference](../guides/session.md
|
|
84
|
+
A `scope: 'shared'` capability arrives once, in `sessionData.shared.context`, and is written with the one-argument `setData(update)`. See [Writing shared capabilities](../guides/multi-team-games.md#facilitator-writable-shared-capabilities) and the [session UI hooks reference](../guides/session-hooks.md) for roster control, timers, undo, and reset.
|
|
85
85
|
|
|
86
86
|
3. If you replaced the starter's session UI, delete its other components and tests under `session/src/`, which read capabilities this one no longer declares
|
|
87
87
|
|
|
@@ -111,6 +111,7 @@ The session UI is the console at http://localhost:3000. Change a price on one te
|
|
|
111
111
|
|
|
112
112
|
## Related
|
|
113
113
|
|
|
114
|
+
- [Designing screens](../guides/designing-screens.md): the brief to write before you build, and the check to run after
|
|
114
115
|
- [Session UI guide](../guides/session.md)
|
|
115
116
|
- [Create a user interface](create-user-interface.md)
|
|
116
117
|
- [Test a user interface](test-user-interface.md)
|
|
@@ -110,6 +110,7 @@ The configuration step exists only when the package has a `setup/setup.sdk.json`
|
|
|
110
110
|
|
|
111
111
|
## Related
|
|
112
112
|
|
|
113
|
+
- [Designing screens](../guides/designing-screens.md): the brief to write before you build, and the check to run after
|
|
113
114
|
- [Create a scenario editor](create-scenario-editor.md)
|
|
114
115
|
- [Use requestPlay in a setup screen](use-request-play.md)
|
|
115
116
|
- [Create a settings resource](create-settings.md)
|
|
@@ -90,6 +90,7 @@ Open a team's participant view. It shows the current price and revenue, and **Ra
|
|
|
90
90
|
|
|
91
91
|
## Related
|
|
92
92
|
|
|
93
|
+
- [Designing screens](../guides/designing-screens.md): the brief to write before you build, and the check to run after
|
|
93
94
|
- [User interfaces guide](../guides/ui.md): reading and writing state, ticks, participants, timers and theming
|
|
94
95
|
- [Design state for concurrent writes](design-state-for-concurrent-writes.md)
|
|
95
96
|
- [Use requestTick in a UI](use-request-tick.md)
|
|
@@ -104,6 +104,7 @@ Open http://localhost:3000, press the backtick key for the dev drawer, switch on
|
|
|
104
104
|
|
|
105
105
|
## Related
|
|
106
106
|
|
|
107
|
+
- [Designing screens](../guides/designing-screens.md): the brief to write before you build, and the check to run after
|
|
107
108
|
- [Waiting room guide](../guides/waiting-room.md): held starts, join codes, roster, and layout
|
|
108
109
|
- [Create a tick controller](create-tick-controller.md)
|
|
109
110
|
- [Test a user interface](test-user-interface.md)
|
|
@@ -60,7 +60,7 @@ Shape capabilities and `setData` calls so that several participants writing at o
|
|
|
60
60
|
if (participant) setData({ votes: { Votes: { [participant.id]: 'yes' } } });
|
|
61
61
|
```
|
|
62
62
|
|
|
63
|
-
5. Await the writes that matter through `useMutationReporter`, and show its `failure` (leaving out `validation-rejected`, which `useUserInterfaceValidationRejections` already explains) and its `late` notice. Never retry on your own: on a `conflict` the host has already retried, so offer `failure.retry` behind a 'Try again' button. See [Awaiting state changes](../guides/ui.md#awaiting-state-changes)
|
|
63
|
+
5. Await the writes that matter through `useMutationReporter`, and show its `failure` (leaving out `validation-rejected`, which `useUserInterfaceValidationRejections` already explains) and its `late` notice. Never retry on your own: on a `conflict` the host has already retried, so offer `failure.retry` behind a 'Try again' button. See [Awaiting state changes](../guides/ui-ticks.md#awaiting-state-changes)
|
|
64
64
|
|
|
65
65
|
6. Arbitrate a slot that is contested by design (two people claiming one role) with a [validator](create-validator.md) that compares `previous` with `next` and rejects the losing write. For a shared numeric pool, reconcile in the engine at tick time instead
|
|
66
66
|
|
|
@@ -92,10 +92,10 @@ build is clean too.
|
|
|
92
92
|
| Problem | Solution |
|
|
93
93
|
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
94
94
|
| The error persists after the restart | Add the library that bundles React itself (for example `@react-three/fiber`) to `dedupe` |
|
|
95
|
-
| The SDK warns about two Vite configs | Remove the `vite.config.ts` inside `ui/` and keep one at the project root; see [Customising Vite](../guides/ui.md#customising-vite-dev-and-build)
|
|
95
|
+
| The SDK warns about two Vite configs | Remove the `vite.config.ts` inside `ui/` and keep one at the project root; see [Customising Vite](../guides/ui-styling.md#customising-vite-dev-and-build) |
|
|
96
96
|
| A Vite option in your file has no effect | The SDK owns structural fields (`root`, `base`, build output, entry points); additive options such as `resolve.dedupe`, `resolve.alias`, `optimizeDeps`, and `plugins` merge in |
|
|
97
97
|
|
|
98
98
|
## Related
|
|
99
99
|
|
|
100
|
-
- [Customising Vite](../guides/ui.md#customising-vite-dev-and-build): where the file goes and what merges
|
|
100
|
+
- [Customising Vite](../guides/ui-styling.md#customising-vite-dev-and-build): where the file goes and what merges
|
|
101
101
|
- [User interfaces guide](../guides/ui.md)
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
Each recipe is one task, start to finish: prerequisites, numbered steps, a way to check it worked, and fixes for what usually goes wrong. For the full reference on a resource type, see the [guides](../guides/index.md).
|
|
4
4
|
|
|
5
|
+
**Keywords:** recipes, how to, tasks, step by step, all recipes, recipe list
|
|
6
|
+
|
|
5
7
|
## Getting started
|
|
6
8
|
|
|
7
9
|
New to the SDK? Start with [Getting started](../getting-started.md), which plays and changes the starter game, then come back here for one task at a time.
|
|
@@ -86,5 +88,6 @@ The full reference is the [Multi-team games](../guides/multi-team-games.md) guid
|
|
|
86
88
|
- [Drive a game from the CLI](../cli-simulation-testing.md): configure, tick, patch, and read a session from the terminal
|
|
87
89
|
- [Test a user interface](test-user-interface.md): write and run React component tests
|
|
88
90
|
- [Test UIs end to end with Playwright](e2e-testing.md): browser tests against the dev server
|
|
91
|
+
- [Screenshot a surface](screenshot-a-surface.md): capture a screen at phone and desktop size, with the errors the page reported
|
|
89
92
|
- [Test a whole game in-process](test-with-engine.md): whole games with `createTestSession`, for rules, flow, hooks, validators and completion
|
|
90
93
|
- [Fix duplicate package errors in a UI](fix-duplicate-packages.md): resolve 'Invalid hook call' errors caused by two copies of React
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# Screenshot a surface
|
|
2
|
+
|
|
3
|
+
Capture one of your game's screens as a PNG from the command line, at the size and in the scheme you choose, with the errors the page reported.
|
|
4
|
+
|
|
5
|
+
**Keywords:** screenshot, capture, PNG, image, phone, mobile, desktop, viewport, dark mode, colour scheme, brand, locale, visual check, layout, cut off, overflow, console errors, failed requests, Playwright, Chromium, BROWSER_MISSING, SURFACE_NOT_RENDERED
|
|
6
|
+
|
|
7
|
+
## Prerequisites
|
|
8
|
+
|
|
9
|
+
- A game package with the surface you want to see, such as `ui/` for the participant's screen
|
|
10
|
+
- `@playwright/test` in the package's `devDependencies` and its Chromium installed. A package made with `sdk new package` has the dependency; install the browser once:
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
pnpm exec playwright install chromium
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Steps
|
|
17
|
+
|
|
18
|
+
1. Bring the session to the state you want to see. The capture shows the session as it stands, so tick, patch or configure it first:
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
pnpm run sdk tick
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
2. Capture the screen at phone size. The path is the surface's URL path on the dev server: `/team/1/player/1` is the first participant of the first team, `/` the facilitator's session surface, and `/team/1/observe`, `/team/1/waiting-room`, `/setup`, `/presentation` and `/walkthrough` the others:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
pnpm run --silent sdk screenshot /team/1/player/1 --width 390 --height 844 --out phone.png --json
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
3. Capture it again at desktop size, and in dark mode if the screen supports it:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
pnpm run --silent sdk screenshot /team/1/player/1 --width 1280 --height 800 --scheme dark --out desktop.png --json
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
4. Open each PNG and look for text that is cut off, controls that overlap, and colours that are hard to read. Pass `--full-page` to capture the whole height of a screen that scrolls, rather than one viewport of it
|
|
37
|
+
|
|
38
|
+
5. Read the lists in the result. `consoleErrors`, `failedRequests` and `uncaughtExceptions` hold what the page reported while it loaded, the surface's own frame included, so a missing image or a thrown error shows up even when the picture looks right:
|
|
39
|
+
|
|
40
|
+
```json
|
|
41
|
+
{
|
|
42
|
+
"ok": true,
|
|
43
|
+
"command": "screenshot",
|
|
44
|
+
"data": {
|
|
45
|
+
"path": "/home/me/my-game/phone.png",
|
|
46
|
+
"url": "http://localhost:3000/team/1/player/1?bare",
|
|
47
|
+
"width": 390,
|
|
48
|
+
"height": 844,
|
|
49
|
+
"fullPage": false,
|
|
50
|
+
"server": "running",
|
|
51
|
+
"consoleErrors": [],
|
|
52
|
+
"failedRequests": [],
|
|
53
|
+
"uncaughtExceptions": []
|
|
54
|
+
},
|
|
55
|
+
"diagnostics": [],
|
|
56
|
+
"warnings": []
|
|
57
|
+
}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
6. To see the screen in another language or brand, add `--locale <code>` (one of the game's `supportedLocales`) or `--brand <id>` (one the dev server offers). The locale is the session's, so a running dev server is switched to it for the capture and back afterwards
|
|
61
|
+
|
|
62
|
+
## Verify
|
|
63
|
+
|
|
64
|
+
The command exits 0 and the PNG at `path` is `--width` pixels wide and `--height` pixels tall, or taller with `--full-page`. The capture waits for the surface to report its first paint, so it never shows the loading screen.
|
|
65
|
+
|
|
66
|
+
## Troubleshooting
|
|
67
|
+
|
|
68
|
+
| Problem | Solution |
|
|
69
|
+
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
70
|
+
| `BROWSER_MISSING` (exit 5) | The package has no Playwright, or no Chromium for it. Run `pnpm add -D @playwright/test`, then `pnpm exec playwright install chromium` |
|
|
71
|
+
| `SURFACE_NOT_RENDERED` (exit 4) | The surface did not connect, or did not report its first paint before `--timeout` (30 seconds by default). Read `uncaughtExceptions` and `consoleErrors` in `error.details`: most often the UI threw while it first rendered |
|
|
72
|
+
| The screenshot shows the setup screen | The game has a `setup` slot and the session is still at its configuration step. Run `pnpm run sdk play`, then capture again |
|
|
73
|
+
| The screen shows an earlier state | No dev server was running, so the capture started a fresh session. Run `pnpm run sdk tick` (which leaves a server running) before capturing |
|
|
74
|
+
| `USAGE_BAD_FLAG` naming `--locale`/`--brand` | The game does not ship that locale, or the dev server offers no such brand: the message lists the ones it has |
|
|
75
|
+
|
|
76
|
+
## Related
|
|
77
|
+
|
|
78
|
+
- [Test UIs end to end with Playwright](e2e-testing.md): assert on a screen rather than look at it
|
|
79
|
+
- [Drive a game from the CLI](../cli-simulation-testing.md): reach the state you want to capture
|
|
80
|
+
- [CLI reference](../cli-reference.md#screenshot-a-surface): every flag
|
|
@@ -47,5 +47,5 @@ Act as each role in its tab. Because each tab carries its own participant identi
|
|
|
47
47
|
|
|
48
48
|
## Related
|
|
49
49
|
|
|
50
|
-
- [Accessing participant info](../guides/ui.md#accessing-participant-info)
|
|
50
|
+
- [Accessing participant info](../guides/ui-participants.md#accessing-participant-info)
|
|
51
51
|
- [Test UIs end to end with Playwright](e2e-testing.md): drive several participants from a test
|
|
@@ -133,13 +133,13 @@ pnpm run sdk view
|
|
|
133
133
|
|
|
134
134
|
## Troubleshooting
|
|
135
135
|
|
|
136
|
-
| Problem | Solution
|
|
137
|
-
| ------------------------------------ |
|
|
138
|
-
| `data.upload` is a type error | `upload` is not in the UI's `reads` or `writes`; step 2 regenerates `types.ts`
|
|
139
|
-
| `UndeclaredApiUseError` at tick time | The engine calls a service missing from its `uses` (step 4)
|
|
140
|
-
| The engine never sees the reference | Add `upload` to the engine's `reads`
|
|
141
|
-
| The PDF does not render | Match the `<embed>` type to the file; see [
|
|
142
|
-
| `LLMClientError` from `generateText` | Platform access is not configured; see [Environment variables](../environment-variables.md)
|
|
136
|
+
| Problem | Solution |
|
|
137
|
+
| ------------------------------------ | ----------------------------------------------------------------------------------------------- |
|
|
138
|
+
| `data.upload` is a type error | `upload` is not in the UI's `reads` or `writes`; step 2 regenerates `types.ts` |
|
|
139
|
+
| `UndeclaredApiUseError` at tick time | The engine calls a service missing from its `uses` (step 4) |
|
|
140
|
+
| The engine never sees the reference | Add `upload` to the engine's `reads` |
|
|
141
|
+
| The PDF does not render | Match the `<embed>` type to the file; see [Media types](../guides/file-handling.md#media-types) |
|
|
142
|
+
| `LLMClientError` from `generateText` | Platform access is not configured; see [Environment variables](../environment-variables.md) |
|
|
143
143
|
|
|
144
144
|
## Related
|
|
145
145
|
|
|
@@ -68,8 +68,8 @@ The hook must be called inside a component rendered within `UserInterfaceWrapper
|
|
|
68
68
|
|
|
69
69
|
**UI shows a brief flicker after calling `setData` then `requestTick`**
|
|
70
70
|
|
|
71
|
-
When you call `await setData({ ... }); await callbacks.requestTick();`, the `setData` change is visible immediately but the tick is asynchronous. Between the two, UIs show the raw `setData` values without any engine-computed results. This resolves once the tick completes (typically a few milliseconds). See [Combining setData with requestTick](../guides/ui.md#combining-setdata-with-requesttick) for strategies to handle the intermediate state.
|
|
71
|
+
When you call `await setData({ ... }); await callbacks.requestTick();`, the `setData` change is visible immediately but the tick is asynchronous. Between the two, UIs show the raw `setData` values without any engine-computed results. This resolves once the tick completes (typically a few milliseconds). See [Combining setData with requestTick](../guides/ui-ticks.md#combining-setdata-with-requesttick) for strategies to handle the intermediate state.
|
|
72
72
|
|
|
73
73
|
## Related
|
|
74
74
|
|
|
75
|
-
- [User interfaces guide: requesting a tick](../guides/ui.md#requesting-a-tick)
|
|
75
|
+
- [User interfaces guide: requesting a tick](../guides/ui-ticks.md#requesting-a-tick)
|