@seriousgaming/sdk-tools 1.0.0-alpha.4 → 1.1.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 +20003 -5523
- package/dist/client.js +15534 -1134
- 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 +213 -0
- package/dist/dev/console/assets/icon-CRaj5uhr.svg +24 -0
- package/dist/dev/console/assets/index-q6-lvlN3.css +1 -0
- package/dist/dev/console/assets/index-qxHcu9fJ.js +204 -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 +166 -0
- package/dist/docs/api/sdk.md +70 -4
- package/dist/docs/changelog.md +64 -6
- 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 +64 -3
- 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 +2 -9
- package/dist/docs/guides/scenario-editor.md +11 -11
- package/dist/docs/guides/scenarios.md +26 -14
- package/dist/docs/guides/session.md +29 -35
- 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 +194 -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 +28 -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 +2 -2
- 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 +67 -0
- package/dist/host/host-channel.d.ts +11 -2
- package/dist/host/index.d.ts +7 -1
- package/dist/host/protocol.d.ts +49 -5
- package/dist/host/theme.d.ts +28 -2
- package/dist/host.js +11490 -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 +1 -0
- 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 +6 -0
- package/dist/validation/file-settings.d.ts +49 -0
- package/dist/validation/guide-settings-validator.d.ts +26 -0
- package/package.json +6 -5
- package/dist/dev/console/assets/index-DgFglsnA.js +0 -204
|
@@ -1,16 +1,10 @@
|
|
|
1
1
|
# Building session UIs
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
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.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
## What you'll learn
|
|
5
|
+
It is facilitator-only and works across all teams at once, for session-wide dashboards, cross-team comparisons, and global game controls.
|
|
8
6
|
|
|
9
|
-
-
|
|
10
|
-
- How to read and write per-team state from a single session-level view
|
|
11
|
-
- How to target game flow controls at individual teams or all teams at once
|
|
12
|
-
- How to handle both independent and shared-state interaction modes
|
|
13
|
-
- How to configure the session UI per game and per scenario
|
|
7
|
+
**Keywords:** manage session, session UI, facilitator UI, session-level, cross-team, multi-team dashboard, facilitator controls, session dashboard, all teams, independent mode, shared-state mode
|
|
14
8
|
|
|
15
9
|
## What are session UIs?
|
|
16
10
|
|
|
@@ -29,6 +23,8 @@ The session UI is the facilitator's whole-session screen. The host renders it fu
|
|
|
29
23
|
|
|
30
24
|
Capability is inferred, not declared: shipping a session UI claims the whole canvas. There is no partial takeover and no per-capability negotiation.
|
|
31
25
|
|
|
26
|
+
Put the numbers that matter side by side: a facilitator who can spot a struggling team early can prompt reflection between rounds rather than after the game.
|
|
27
|
+
|
|
32
28
|
## Creating a session UI
|
|
33
29
|
|
|
34
30
|
The starter game already fills this slot, and `new` refuses a filled one with `RESOURCE_EXISTS`. In a package made by `new package`, change it with `update session` instead, or start from `new package --empty`.
|
|
@@ -197,6 +193,8 @@ function App() {
|
|
|
197
193
|
export default App;
|
|
198
194
|
```
|
|
199
195
|
|
|
196
|
+
`useSessionUserInterfaceData` also returns `scenarioName`: the name of the scenario the session is running, in the session's language, or `null` with none. It tells a facilitator with several copies of a scenario which one this session is on. Show it, never branch on it (see [Showing the scenario](./engine.md#showing-the-scenario)).
|
|
197
|
+
|
|
200
198
|
### Writing per-team overrides
|
|
201
199
|
|
|
202
200
|
The session-level `setData` requires a `teamId` parameter to specify which team to update, since the session UI is not scoped to one team:
|
|
@@ -457,16 +455,16 @@ function OverlayControls() {
|
|
|
457
455
|
}
|
|
458
456
|
```
|
|
459
457
|
|
|
460
|
-
**Always gate on `useSessionUserInterfaceHostOverlays()`.** Which overlays exist is the host's answer, not yours: a production host and the dev server do not offer the same set, and the guide is only available when the active game declares one. A button for an overlay the host does not have is a button that cannot work. The list is empty until the host answers, and it can change
|
|
458
|
+
**Always gate on `useSessionUserInterfaceHostOverlays()`.** Which overlays exist is the host's answer, not yours: a production host and the dev server do not offer the same set, and the guide is only available when the active game declares one. A button for an overlay the host does not have is a button that cannot work. The list is empty until the host answers, and it can change when the game is reloaded, for example when a guide is added or removed.
|
|
461
459
|
|
|
462
460
|
The second argument narrows the overlay:
|
|
463
461
|
|
|
464
|
-
| Overlay | Second argument
|
|
465
|
-
| --------------------- |
|
|
466
|
-
| `'facilitator-guide'` |
|
|
467
|
-
| `'print-sheets'` | A team id
|
|
462
|
+
| Overlay | Second argument | Omitted means |
|
|
463
|
+
| --------------------- | ------------------------------------------------ | ---------------- |
|
|
464
|
+
| `'facilitator-guide'` | None: a game holds one guide, and one is ignored | The game's guide |
|
|
465
|
+
| `'print-sheets'` | A team id | Every team |
|
|
468
466
|
|
|
469
|
-
It rejects with a `MutationError` carrying `{ kind: 'denied' }` for an overlay the host does not offer and for
|
|
467
|
+
It rejects with a `MutationError` carrying `{ kind: 'denied' }` for an overlay the host does not offer and for a team id that is not in the session.
|
|
470
468
|
|
|
471
469
|
### Undoing and resetting
|
|
472
470
|
|
|
@@ -492,8 +490,10 @@ function GameControls() {
|
|
|
492
490
|
}
|
|
493
491
|
```
|
|
494
492
|
|
|
495
|
-
- **`undoTick(teamId?)`** puts teams back on the board they were holding when the last tick was taken, decisions and all: it un-runs the engine rather than re-dealing the tick. When `teamId` is omitted, reverts all teams; naming one is independent mode only, since shared-state teams advance together. With no history to undo, the promise rejects with a `MutationError` whose `outcome.kind` is `denied
|
|
496
|
-
- **`resetGame(teamId?)`** clears all context, deletes game-scoped blobs, and re-initialises from scratch. When `teamId` is omitted, resets all teams. Settings are preserved
|
|
493
|
+
- **`undoTick(teamId?)`** puts teams back on the board they were holding when the last tick was taken, decisions and all: it un-runs the engine rather than re-dealing the tick. When `teamId` is omitted, reverts all teams; naming one is independent mode only, since shared-state teams advance together. With no history to undo, the promise rejects with a `MutationError` whose `outcome.kind` is `denied`
|
|
494
|
+
- **`resetGame(teamId?)`** clears all context, deletes game-scoped blobs, and re-initialises from scratch. When `teamId` is omitted, resets all teams. Settings are preserved
|
|
495
|
+
|
|
496
|
+
Undo lets a team try a round again without penalty, which supports psychological safety: people experiment more freely when a mistake can be taken back.
|
|
497
497
|
|
|
498
498
|
### Opening and closing the waiting room
|
|
499
499
|
|
|
@@ -703,30 +703,24 @@ Read colours from the theme hook below rather than hard-coding them, so your ses
|
|
|
703
703
|
|
|
704
704
|
## Using the theme
|
|
705
705
|
|
|
706
|
-
Edit `src/theme.ts` to use the session theme hook
|
|
706
|
+
Edit `src/theme.ts` to use the session theme hook, and turn it into MUI theme options with `createSurfaceTheme`:
|
|
707
707
|
|
|
708
708
|
```typescript
|
|
709
|
-
import { useSessionUserInterfaceTheme } from '@seriousgaming/sdk/ui';
|
|
709
|
+
import { createSurfaceTheme, useSessionUserInterfaceTheme } from '@seriousgaming/sdk/ui';
|
|
710
710
|
import { createTheme } from '@mui/material/styles';
|
|
711
711
|
import { useMemo } from 'react';
|
|
712
712
|
|
|
713
713
|
export function useAppTheme() {
|
|
714
714
|
const sdkTheme = useSessionUserInterfaceTheme();
|
|
715
715
|
return useMemo(
|
|
716
|
-
() =>
|
|
717
|
-
createTheme({
|
|
718
|
-
palette: {
|
|
719
|
-
mode: sdkTheme.mode,
|
|
720
|
-
primary: {
|
|
721
|
-
main: (sdkTheme.mode === 'light' ? sdkTheme.light : sdkTheme.dark).primary,
|
|
722
|
-
},
|
|
723
|
-
},
|
|
724
|
-
}),
|
|
716
|
+
() => createTheme(createSurfaceTheme(sdkTheme, { fonts: { body: 'Work Sans Variable' } })),
|
|
725
717
|
[sdkTheme]
|
|
726
718
|
);
|
|
727
719
|
}
|
|
728
720
|
```
|
|
729
721
|
|
|
722
|
+
The host's logo, name and fonts reach a session UI exactly as they reach a game UI: see [Theming and branding](./theming-and-branding.md).
|
|
723
|
+
|
|
730
724
|
## Dev server behaviour
|
|
731
725
|
|
|
732
726
|
When you run `pnpm run sdk dev` for a game with session UIs:
|
|
@@ -966,10 +960,10 @@ The session UI follows the same file structure conventions as other UI resource
|
|
|
966
960
|
|
|
967
961
|
## See also
|
|
968
962
|
|
|
969
|
-
- [Multi-team games](./multi-team-games.md)
|
|
970
|
-
- [Building user interfaces](./ui.md)
|
|
971
|
-
- [Building a setup screen](./setup.md)
|
|
972
|
-
- [Building a scenario editor](./scenario-editor.md)
|
|
973
|
-
- [Tick controllers](./tick-controller.md)
|
|
974
|
-
- [Testing](./testing.md)
|
|
975
|
-
- [CLI reference](../cli-reference.md)
|
|
963
|
+
- [Multi-team games](./multi-team-games.md): independent and shared-state interaction modes
|
|
964
|
+
- [Building user interfaces](./ui.md): building participant-facing game UIs
|
|
965
|
+
- [Building a setup screen](./setup.md): the form at session creation
|
|
966
|
+
- [Building a scenario editor](./scenario-editor.md): authoring lasting scenarios
|
|
967
|
+
- [Tick controllers](./tick-controller.md): automatic tick timing
|
|
968
|
+
- [Testing](./testing.md): writing UI tests
|
|
969
|
+
- [CLI reference](../cli-reference.md): `new`, `update`, and `delete session` commands
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
# Settings
|
|
2
2
|
|
|
3
|
-
Settings are a game's read-only parameters: a price, a difficulty, a round length, a menu, an answer key.
|
|
3
|
+
Settings are a game's read-only parameters: a price, a difficulty, a round length, a menu, an answer key.
|
|
4
|
+
|
|
5
|
+
This guide covers declaring them, reading them from logic and surfaces, overriding them per scenario and per session, and setting them from the CLI.
|
|
4
6
|
|
|
5
7
|
Not to be confused with [global settings](./global-settings.md), the file in your home directory that holds API keys for every project.
|
|
6
8
|
|
|
@@ -64,7 +66,7 @@ Run `pnpm run sdk new settings` with no JSON to be prompted for each property in
|
|
|
64
66
|
|
|
65
67
|
- Every property needs a `default`. `new settings`, `update settings` and `sdk build` all refuse a property without one
|
|
66
68
|
- Every default must fit its own schema, at any depth. `sdk build` refuses a string default on a number property, a default outside its range or `enum`, and an object default missing a key its own `required` lists, naming the settings resource and the path. The generated `Settings` type comes from the schema, so the compiler cannot catch a default that disagrees with it
|
|
67
|
-
- A top-level `required` is refused, because every property always has a value. For a value
|
|
69
|
+
- A top-level `required` is refused, because every property always has a value. For a value with no sensible default, such as one every scenario must supply, default to an empty value (`""`, `[]` or `{}`) and have a validator's `Scenario` gate refuse a scenario that leaves it empty (see [Gating scenarios](./validators.md#gating-scenarios)). Widen a type to allow `null` only when your game genuinely handles a missing value, since every reader then has to
|
|
68
70
|
|
|
69
71
|
A `required` inside an object-valued property is allowed. It holds the property's `default` to its keys, never a scenario or a setup change: those are partial at every depth, so a scenario or a setup UI may set one key of the object and leave the rest to the layer beneath. An array is the exception: it replaces the one beneath whole, so each item an override supplies must be complete.
|
|
70
72
|
|
|
@@ -76,6 +78,9 @@ A settings schema is read by more than the build. A hosted runtime's generic set
|
|
|
76
78
|
- Its units, in the description or title ('in pounds', 'per tick', 'as a fraction of revenue')
|
|
77
79
|
- A range, with `minimum` and `maximum`, wherever one exists
|
|
78
80
|
- An `enum` where the choices are closed
|
|
81
|
+
- A `blob` declaration on every value that holds a file (see [Settings that hold a file](#settings-that-hold-a-file))
|
|
82
|
+
|
|
83
|
+
**What an agent can change is what your settings hold.** An agent writing a scenario changes settings and nothing else. Content you want written per scenario, such as a briefing's text, a client's logo or a product list, belongs in a settings resource, not in code or a package file, or nothing short of a new release can change it. When a scenario needs an answer no schema can give, such as what a round would come to at a price, offer a [scenario-scoped endpoint](./endpoints.md#scenario-scoped-endpoints) an agent can call on its draft.
|
|
79
84
|
|
|
80
85
|
A `title` on a value is safe to write: the generated `types.ts` ignores it, so any wording works, 'Settings' and 'Context' included. Only a `title` on an object names a type there.
|
|
81
86
|
|
|
@@ -111,6 +116,27 @@ Some values are part of the game's design rather than something to tune: a const
|
|
|
111
116
|
- **Editors are not sent the schema.** A setup screen or scenario editor receives the values, not the schema, so show a locked field as read-only yourself, as the factory example's scenario editor does
|
|
112
117
|
- **Adding a lock is a scenario-format change.** A custom scenario saved before the lock may hold a value for it, so bump `scenarioFormat` when you lock a setting a released version left open (see [Scenario format: when to bump it](./scenarios.md#scenario-format-when-to-bump-it))
|
|
113
118
|
|
|
119
|
+
### Settings that hold a file
|
|
120
|
+
|
|
121
|
+
A setting can hold a file, such as a client's logo or a briefing document. Mark the string property with `blob`, the keyword an endpoint request uses for a file, saying what file it takes:
|
|
122
|
+
|
|
123
|
+
```json
|
|
124
|
+
"BrandingLogo": {
|
|
125
|
+
"type": "string",
|
|
126
|
+
"title": "Branding logo",
|
|
127
|
+
"description": "The workshop's logo, shown beside the Decisions heading. Empty shows none",
|
|
128
|
+
"default": "",
|
|
129
|
+
"blob": { "accept": ["image/svg+xml", "image/png", "image/jpeg"], "maxBytes": 524288 }
|
|
130
|
+
}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
`accept` lists media types, `image/*` style wildcards included, and takes any type when absent; `maxBytes` bounds the file. The value is an asset reference, `asset:`, `shared:` or `blob:` (see [Asset references](./file-handling.md#asset-references)), or empty for no file. Read it with `getAssetUrl` or `readAsset` as any reference.
|
|
134
|
+
|
|
135
|
+
- **The default is no file, or a shared one.** A default resolves with no scenario active, so it must be empty or a `shared:` reference
|
|
136
|
+
- **The build checks your files.** Every file a package scenario or a default names must be shipped, within `maxBytes`, and of a type `accept` lists, judged from its extension. A `blob:` reference in a package scenario fails the build: it is an upload, which no package can carry
|
|
137
|
+
- **Every write is checked against it.** A setup screen, the scenario editor or an agent sets a file by uploading it first and writing the `blob:` reference it gets back. A reference to a file nobody uploaded, or one too large or of the wrong type, is refused as `denied`, naming the setting. So is anything that is not a reference, a `data:` URI or a URL included
|
|
138
|
+
- **It tells an agent what to upload.** A schema alone says only that the value is a string; `blob` says it is a PNG of up to 512 KB
|
|
139
|
+
|
|
114
140
|
### How to divide settings
|
|
115
141
|
|
|
116
142
|
Split settings by who reads them rather than keeping one per resource. A package may hold one `engine` settings resource read only by the engine, or several named by topic (`pricing`, `documents`, `answers`) that several resources share. The starter game does both: its `menu` settings, the prices and the stall's capacity, are read by the engine, every surface, a hook and a validator, while each item's usual demand sits in an `engine` resource only the engine reads. Several resources may declare the same settings resource, and each receives the same values, so a surface never needs a copy of a value the engine already has.
|
|
@@ -1,13 +1,8 @@
|
|
|
1
1
|
# Building a setup screen
|
|
2
2
|
|
|
3
|
-
The `setup` slot holds the small form a facilitator fills in when they create a session. What it writes applies to that session only.
|
|
3
|
+
The `setup` slot holds the small form a facilitator fills in when they create a session. What it writes applies to that session only.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
- What the setup slot is for, and how it differs from the scenario editor
|
|
8
|
-
- How to create a setup screen and choose the settings it edits
|
|
9
|
-
- How to read and write settings with `useSettingsEditor`
|
|
10
|
-
- How to start play from your own control with `requestPlay`
|
|
5
|
+
This guide covers creating one, building its form, and how it behaves in the dev server.
|
|
11
6
|
|
|
12
7
|
## What setup is
|
|
13
8
|
|
|
@@ -1,20 +1,11 @@
|
|
|
1
1
|
# Speech generation guide
|
|
2
2
|
|
|
3
|
+
Give characters and briefings a voice: generate speech from server-side logic and play it in any UI.
|
|
4
|
+
|
|
3
5
|
The SDK exposes a provider-agnostic text-to-speech callback, `generateSpeech`. Engines, hooks, tick controllers, and endpoints can synthesise audio without knowing which provider executes the call. User interfaces reach it through an endpoint. The audio is persisted as a blob, so the same artefact can be played from a UI or analysed in an engine.
|
|
4
6
|
|
|
5
7
|
The dev server ships with one provider adapter (ElevenLabs). Additional providers (OpenAI, Google Cloud, Azure, AWS Polly) will land behind a future `TTS_PROVIDER` env var without breaking changes to game code.
|
|
6
8
|
|
|
7
|
-
## Table of contents
|
|
8
|
-
|
|
9
|
-
- [Overview](#overview)
|
|
10
|
-
- [Configuration](#configuration)
|
|
11
|
-
- [Voice presets](#voice-presets)
|
|
12
|
-
- [Tiers](#tiers)
|
|
13
|
-
- [Using generateSpeech in the engine, hooks, and tick controllers](#using-generatespeech-in-the-engine-hooks-and-tick-controllers)
|
|
14
|
-
- [Using generateSpeech in user interfaces](#using-generatespeech-in-user-interfaces)
|
|
15
|
-
- [Request and response shape](#request-and-response-shape)
|
|
16
|
-
- [Limitations](#limitations)
|
|
17
|
-
|
|
18
9
|
## Overview
|
|
19
10
|
|
|
20
11
|
`generateSpeech` accepts either a bare string or a request object, mirroring `generateText`:
|
|
@@ -125,7 +116,7 @@ For ElevenLabs, the defaults are `eleven_flash_v2_5` (quick), `eleven_turbo_v2_5
|
|
|
125
116
|
}
|
|
126
117
|
```
|
|
127
118
|
|
|
128
|
-
2. Run `pnpm run sdk generate` so the per-resource `types.ts` narrows the `Callbacks` alias
|
|
119
|
+
2. Run `pnpm run sdk generate` so the per-resource `types.ts` narrows the `Callbacks` alias
|
|
129
120
|
3. Call the callback from `Init` or `Run`:
|
|
130
121
|
|
|
131
122
|
```typescript
|
|
@@ -226,8 +217,8 @@ v1 is intentionally minimal so the API stays stable as providers come and go. Th
|
|
|
226
217
|
|
|
227
218
|
## Related
|
|
228
219
|
|
|
229
|
-
- [Declare the APIs a resource uses](./llm-integration.md#declare-the-apis-a-resource-uses)
|
|
230
|
-
- [Declare API uses](../recipes/declare-api-uses.md)
|
|
231
|
-
- [LLM integration](llm-integration.md)
|
|
232
|
-
- [File handling](file-handling.md)
|
|
233
|
-
- [Environment variables](../environment-variables.md)
|
|
220
|
+
- [Declare the APIs a resource uses](./llm-integration.md#declare-the-apis-a-resource-uses): the safety boundary mental model
|
|
221
|
+
- [Declare API uses](../recipes/declare-api-uses.md): step-by-step declaration recipe
|
|
222
|
+
- [LLM integration](llm-integration.md): the companion `generateText` callback
|
|
223
|
+
- [File handling](file-handling.md): the unified `asset:` / `blob:` scheme for files
|
|
224
|
+
- [Environment variables](../environment-variables.md): full env-var reference
|
|
@@ -88,7 +88,7 @@ See [Validators](./validators.md).
|
|
|
88
88
|
|
|
89
89
|
## User interfaces
|
|
90
90
|
|
|
91
|
-
Each is a small React app built with Vite and MUI, with its own `index.html`, `src/main.tsx` (the SDK wrapper, locale, and right-to-left set-up), `src/theme.ts` (
|
|
91
|
+
Each is a small React app built with Vite and MUI, with its own `index.html`, `src/main.tsx` (the SDK wrapper, locale, and right-to-left set-up), `src/theme.ts` (`createSurfaceTheme` over the host's theme, with Work Sans as the font), and `src/i18n.ts` (every string on the screen).
|
|
92
92
|
|
|
93
93
|
### `ui/`
|
|
94
94
|
|
|
@@ -98,6 +98,7 @@ The game UI: what each participant sees.
|
|
|
98
98
|
- `src/TodayPanel.tsx` and `src/MakeRow.tsx`: the controls for today's plan, one row per item, with the participant's own item marked
|
|
99
99
|
- `src/DayBar.tsx`: the **Open the stall** button, which calls `requestTick` to play the team's day
|
|
100
100
|
- `src/YesterdayPanel.tsx` and `src/HistoryPanel.tsx`: how yesterday went, and every day so far. The history table asks the host for the earlier days with `getPastState` and adds today's from live context, so nothing in context grows as the days go by (see [Review a past day in a UI](../recipes/review-a-past-day.md))
|
|
101
|
+
- `src/HostLogo.tsx`: the host's logo in the top bar, from `useBrandLogo()`, or nothing when the host sends none
|
|
101
102
|
- `src/writes.ts`: one mutation reporter every write goes through
|
|
102
103
|
- `src/menu.ts`, `src/format.ts`, `src/Section.tsx`, `src/ThemeToggle.tsx`: menu ordering, money formatting, the card layout, and a light or dark switch
|
|
103
104
|
- `ui.sdk.json`: reads every capability it shows, writes only `plan`, and reads the `ui` settings (`Step` and `CurrencySymbol`)
|
|
@@ -1,12 +1,6 @@
|
|
|
1
1
|
# Testing
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
## What you'll learn
|
|
6
|
-
|
|
7
|
-
- How to write unit tests for the engine
|
|
8
|
-
- How to test React user interface components
|
|
9
|
-
- How to run tests locally
|
|
3
|
+
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.
|
|
10
4
|
|
|
11
5
|
## Testing engine logic
|
|
12
6
|
|
|
@@ -155,13 +149,14 @@ For `InitAggregate`, pass `meta: { tick: 0 }`. A shared capability belongs in `r
|
|
|
155
149
|
|
|
156
150
|
Each kind of logic has its own builder, typed from the function it is passed to:
|
|
157
151
|
|
|
158
|
-
| Builder
|
|
159
|
-
|
|
|
160
|
-
| `logicArgs.hook`
|
|
161
|
-
| `logicArgs.endpoint`
|
|
162
|
-
| `logicArgs.
|
|
163
|
-
| `logicArgs.
|
|
164
|
-
| `logicArgs.
|
|
152
|
+
| Builder | For | Fills, beyond `meta`, `participants` and `callbacks` |
|
|
153
|
+
| ---------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
154
|
+
| `logicArgs.hook` | A hook's `Run` | The roster is the payload's `participant`. The signal defaults to `participantJoin`; name `signal: 'participantMove'` for a move, whose payload it then requires |
|
|
155
|
+
| `logicArgs.endpoint` | An endpoint's `Handle` or `Plan` | `team` (`team-1`), `session` (independent, no ticks completed) and `caller`: the team's first participant through `ui`, or pass `caller: { role: 'facilitator' }` (from `session`) |
|
|
156
|
+
| `logicArgs.scenarioEndpoint` | A scenario-scoped endpoint's `Handle` | `caller`: an author through `scenario_editor`. It takes `request` and `settings` (the draft's values) and builds no `context`, `participants` or `session` |
|
|
157
|
+
| `logicArgs.validator` | A validator's `UpdateData` | `actor`: the roster's first participant |
|
|
158
|
+
| `logicArgs.requestTick` | A validator's `RequestTick` | `actor`, and `requestedTick: 1` |
|
|
159
|
+
| `logicArgs.tickController` | `GetTickController` | `teams`: the one team `meta` names, with `context`. `waitingRoomOpen: false` |
|
|
165
160
|
|
|
166
161
|
```typescript
|
|
167
162
|
const result = await Handle(
|
|
@@ -184,6 +179,8 @@ await Run(
|
|
|
184
179
|
);
|
|
185
180
|
```
|
|
186
181
|
|
|
182
|
+
To act on a team other than `team-1`, pass `team: createMockTeam({ index: 1 })`, and for a hook's or a validator's participant, `createMockParticipant({ name: 'Ada' })`, both imported from `@seriousgaming/sdk/testing` with `logicArgs`. Build teams and participants with `createMockTeam`, `createMockParticipant` and their plurals rather than by hand: a field later added to either then reaches your test with a value, rather than failing to compile in every file that spelt one out.
|
|
183
|
+
|
|
187
184
|
### Testing with LLM callbacks
|
|
188
185
|
|
|
189
186
|
The callbacks `logicArgs` fills are offline stubs, the same a test session uses; pass one in `callbacks` to choose its answer. See [Service callbacks are stubbed](./engine-testing.md#service-callbacks-are-stubbed) for what each stub answers and how to override it.
|
|
@@ -262,18 +259,20 @@ describe('Dashboard', () => {
|
|
|
262
259
|
|
|
263
260
|
Default values when you omit an option:
|
|
264
261
|
|
|
265
|
-
| Option | Default
|
|
266
|
-
| ---------------- |
|
|
267
|
-
| `data` | `{}`
|
|
268
|
-
| `settings` | `{}`
|
|
269
|
-
| `completedTicks` | `0`
|
|
270
|
-
| `setData` | no-op
|
|
271
|
-
| `theme` | `createMockUserInterfaceTheme()` (light mode, MUI palette)
|
|
272
|
-
| `locale` | `{ locale: 'en' }`
|
|
273
|
-
| `participant` | `{ id: '1', name: 'Participant 1', index: 0, connected: true, teamId: 'team-1' }`
|
|
274
|
-
| `participants` | `[]` (`createMockParticipants(n)` builds a roster)
|
|
275
|
-
| `
|
|
276
|
-
| `
|
|
262
|
+
| Option | Default |
|
|
263
|
+
| ---------------- | ------------------------------------------------------------------------------------- |
|
|
264
|
+
| `data` | `{}` |
|
|
265
|
+
| `settings` | `{}` |
|
|
266
|
+
| `completedTicks` | `0` |
|
|
267
|
+
| `setData` | no-op |
|
|
268
|
+
| `theme` | `createMockUserInterfaceTheme()` (light mode, MUI palette) |
|
|
269
|
+
| `locale` | `{ locale: 'en' }` |
|
|
270
|
+
| `participant` | `{ id: '1', name: 'Participant 1', index: 0, connected: true, teamId: 'team-1' }` |
|
|
271
|
+
| `participants` | `[]` (`createMockParticipants(n)` builds a roster) |
|
|
272
|
+
| `ownTeam` | The participant's team, found in `teams`, else `null` (`createMockTeam()` builds one) |
|
|
273
|
+
| `timer` | Disabled (no auto-tick) |
|
|
274
|
+
| `scenarioName` | `null` |
|
|
275
|
+
| `callbacks` | All present as no-ops |
|
|
277
276
|
|
|
278
277
|
Every option, and those of the other two helpers, is listed in the [UI testing API reference](../api/sdk-ui-testing.md#renderuserinterfaceoptions).
|
|
279
278
|
|
|
@@ -301,11 +300,14 @@ it('calls updateSettings when a value changes', () => {
|
|
|
301
300
|
|
|
302
301
|
#### Session UIs
|
|
303
302
|
|
|
304
|
-
Type the helpers with the surface's generated types: `renderSessionUserInterface<SessionData>`, `createMockTeamState<TeamContext>` and `createMockSharedState<SharedContext>`. Each fixture's context then accepts only capabilities of its own scope, any of them optional, so a shared capability left on a team's fixture fails to compile, as reading one through a team does in the surface. Left untyped, the helpers accept any context.
|
|
303
|
+
Type the helpers with the surface's generated types: `renderSessionUserInterface<SessionData>`, `createMockTeamState<TeamContext>` and `createMockSharedState<SharedContext>`. Build the `teams` list with `createMockTeams(n)`, or `createMockTeam({ name })` for a team you name: `teamId` and `name` follow `index` unless you give them. Each fixture's context then accepts only capabilities of its own scope, any of them optional, so a shared capability left on a team's fixture fails to compile, as reading one through a team does in the surface. Left untyped, the helpers accept any context.
|
|
304
|
+
|
|
305
|
+
`sessionMeta` and `teamConfiguration` are merged over the defaults, so name only the field the test is about: `sessionMeta: { readOnly: true }` renders a frozen session, and `teamConfiguration: { max: 2 }` an independent one capped at two teams.
|
|
305
306
|
|
|
306
307
|
```typescript
|
|
307
308
|
import {
|
|
308
309
|
createMockSharedState,
|
|
310
|
+
createMockTeam,
|
|
309
311
|
createMockTeamState,
|
|
310
312
|
renderSessionUserInterface,
|
|
311
313
|
} from '@seriousgaming/sdk/ui/testing';
|
|
@@ -325,8 +327,8 @@ it('resets all teams', () => {
|
|
|
325
327
|
'team-1': createMockTeamState<TeamContext>({ completedTicks: 3 }),
|
|
326
328
|
},
|
|
327
329
|
},
|
|
328
|
-
teams: [{
|
|
329
|
-
teamConfiguration: {
|
|
330
|
+
teams: [createMockTeam({ name: 'Alpha' })],
|
|
331
|
+
teamConfiguration: { max: 6 },
|
|
330
332
|
callbacks: { resetGame },
|
|
331
333
|
});
|
|
332
334
|
|
|
@@ -342,7 +344,7 @@ it('writes a per-team override', () => {
|
|
|
342
344
|
'team-1': createMockTeamState<TeamContext>({ context: { price: { Price: 10 } } }),
|
|
343
345
|
},
|
|
344
346
|
},
|
|
345
|
-
teams: [{
|
|
347
|
+
teams: [createMockTeam({ name: 'Alpha' })],
|
|
346
348
|
setData,
|
|
347
349
|
});
|
|
348
350
|
|
|
@@ -392,7 +394,7 @@ setData({}, { deletes: ['pinboard.Notes.p1'] }); // the note's key is gone, not
|
|
|
392
394
|
|
|
393
395
|
### Troubleshooting
|
|
394
396
|
|
|
395
|
-
**
|
|
397
|
+
**'Invalid hook call' or 'Cannot read properties of null (reading "useContext")'**
|
|
396
398
|
|
|
397
399
|
Two copies of React are loaded: one from your package and one from the `file://` SDK dependency. Add `resolve.dedupe` to your `vitest.config.ts`, with the SDK packages beside React so a second copy of the SDK cannot hide the providers either:
|
|
398
400
|
|
|
@@ -414,7 +416,7 @@ export default defineConfig({
|
|
|
414
416
|
|
|
415
417
|
This is already included in the scaffold-generated `vitest.config.ts`.
|
|
416
418
|
|
|
417
|
-
**
|
|
419
|
+
**'Found multiple elements with the text: X' or DOM accumulation between tests**
|
|
418
420
|
|
|
419
421
|
React Testing Library cannot auto-detect Vitest's test lifecycle unless `globals: true` is set. Without it, the DOM is not cleaned up between tests. The scaffold-generated `test-setup.ts` handles this explicitly:
|
|
420
422
|
|
|
@@ -478,15 +480,15 @@ So drive every code path that writes through the runtime: an [engine test](#engi
|
|
|
478
480
|
|
|
479
481
|
## Best practices
|
|
480
482
|
|
|
481
|
-
1. **Test what the user sees**: assert on rendered text, input values, and visible state rather than internal component state
|
|
483
|
+
1. **Test what the user sees**: assert on rendered text, input values, and visible state rather than internal component state
|
|
482
484
|
|
|
483
|
-
2. **Use `fireEvent.change` for controlled inputs**: `userEvent.type` won't work correctly when the mock `setData`/`updateSettings` doesn't update the displayed value between keystrokes
|
|
485
|
+
2. **Use `fireEvent.change` for controlled inputs**: `userEvent.type` won't work correctly when the mock `setData`/`updateSettings` doesn't update the displayed value between keystrokes
|
|
484
486
|
|
|
485
|
-
3. **Keep context data close to realistic**: populate `mockData` with values that reflect a real game state. Tests that rely on fallback/undefined values hide bugs
|
|
487
|
+
3. **Keep context data close to realistic**: populate `mockData` with values that reflect a real game state. Tests that rely on fallback/undefined values hide bugs
|
|
486
488
|
|
|
487
|
-
4. **Test edge cases**: zero values, maximum values, empty arrays, and missing optional capabilities
|
|
489
|
+
4. **Test edge cases**: zero values, maximum values, empty arrays, and missing optional capabilities
|
|
488
490
|
|
|
489
|
-
5. **One `renderApp` helper per test file**: accept `dataOverrides` and `configOverrides` parameters so individual tests can vary only the data they care about
|
|
491
|
+
5. **One `renderApp` helper per test file**: accept `dataOverrides` and `configOverrides` parameters so individual tests can vary only the data they care about
|
|
490
492
|
|
|
491
493
|
## Engine tests
|
|
492
494
|
|
|
@@ -569,9 +571,9 @@ See [Recipe: Test UIs end to end with Playwright](../recipes/e2e-testing.md) for
|
|
|
569
571
|
|
|
570
572
|
## Next steps
|
|
571
573
|
|
|
572
|
-
- [Building user interfaces](./ui.md)
|
|
573
|
-
- [Creating engines](./engine.md)
|
|
574
|
-
- [Engine testing](./engine-testing.md) -
|
|
575
|
-
- [Recipe: Test a user interface](../recipes/test-user-interface.md) -
|
|
576
|
-
- [Recipe: Test a whole game in-process](../recipes/test-with-engine.md) -
|
|
577
|
-
- [Recipe: Test UIs end to end with Playwright](../recipes/e2e-testing.md) -
|
|
574
|
+
- [Building user interfaces](./ui.md): build and develop custom UIs
|
|
575
|
+
- [Creating engines](./engine.md): write a testable engine
|
|
576
|
+
- [Engine testing](./engine-testing.md): whole-game tests with `createTestSession`
|
|
577
|
+
- [Recipe: Test a user interface](../recipes/test-user-interface.md): step-by-step testing walkthrough
|
|
578
|
+
- [Recipe: Test a whole game in-process](../recipes/test-with-engine.md): in-process engine test setup
|
|
579
|
+
- [Recipe: Test UIs end to end with Playwright](../recipes/e2e-testing.md): browser-based end-to-end tests
|