@seriousgaming/sdk-tools 1.0.0 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +4 -4
- package/dist/brands/awkward/brand.json +16 -0
- package/dist/brands/awkward/logo-on-light.svg +4 -0
- package/dist/brands/serious-gaming/brand.json +42 -0
- package/dist/brands/serious-gaming/fonts/OFL-sora.txt +93 -0
- package/dist/brands/serious-gaming/fonts/OFL-work-sans.txt +93 -0
- package/dist/brands/serious-gaming/fonts/sora-latin-400-normal.woff2 +0 -0
- package/dist/brands/serious-gaming/fonts/sora-latin-600-normal.woff2 +0 -0
- package/dist/brands/serious-gaming/fonts/sora-latin-700-normal.woff2 +0 -0
- package/dist/brands/serious-gaming/fonts/work-sans-latin-wght-normal.woff2 +0 -0
- package/dist/brands/serious-gaming/icon.svg +24 -0
- package/dist/brands/serious-gaming/loader-on-dark.svg +25 -0
- package/dist/brands/serious-gaming/loader-on-light.svg +25 -0
- package/dist/brands/serious-gaming/logo-on-dark.svg +38 -0
- package/dist/brands/serious-gaming/logo-on-light.svg +42 -0
- package/dist/cli.js +20161 -5495
- package/dist/client.js +15737 -1151
- package/dist/core/save-scenario.d.ts +25 -0
- package/dist/core/session-endpoints.d.ts +12 -13
- package/dist/core/session-host.d.ts +9 -1
- package/dist/core/session-writes.d.ts +2 -2
- package/dist/core/session.d.ts +9 -1
- package/dist/dev/brand-summary.d.ts +16 -0
- package/dist/dev/brands.d.ts +230 -0
- package/dist/dev/console/assets/icon-CRaj5uhr.svg +24 -0
- package/dist/dev/console/assets/index-BNLEVOQA.js +204 -0
- package/dist/dev/console/assets/index-q6-lvlN3.css +1 -0
- package/dist/dev/console/assets/sora-latin-400-normal-CRt88UEn.woff2 +0 -0
- package/dist/dev/console/assets/sora-latin-600-normal-Cdg4DaK0.woff2 +0 -0
- package/dist/dev/console/assets/sora-latin-700-normal-9waGdLWo.woff2 +0 -0
- package/dist/dev/console/assets/work-sans-latin-wght-normal-Bl-S9Xys.woff2 +0 -0
- package/dist/dev/console/index.html +3 -1
- package/dist/dev/routes.d.ts +9 -0
- package/dist/dev/shell.d.ts +14 -0
- package/dist/dev/view/batch.d.ts +0 -2
- package/dist/docs/ai-agents.md +75 -0
- package/dist/docs/api/deck.md +38 -0
- package/dist/docs/api/index.md +5 -5
- package/dist/docs/api/sdk-commands.md +1 -1
- package/dist/docs/api/sdk-e2e.md +1 -0
- package/dist/docs/api/sdk-projection.md +1 -0
- package/dist/docs/api/sdk-testing.md +52 -1
- package/dist/docs/api/sdk-tools-client.md +1 -0
- package/dist/docs/api/sdk-ui-testing.md +30 -4
- package/dist/docs/api/sdk-ui.md +185 -0
- package/dist/docs/api/sdk.md +70 -4
- package/dist/docs/changelog.md +85 -4
- package/dist/docs/cli-and-dev-server.md +2 -0
- package/dist/docs/cli-error-codes.md +65 -59
- package/dist/docs/cli-reference.md +84 -45
- package/dist/docs/concepts/index.md +74 -6
- package/dist/docs/concepts/terminology.md +17 -11
- package/dist/docs/getting-started.md +30 -11
- package/dist/docs/guides/ai-facilitation.md +5 -1
- package/dist/docs/guides/capabilities.md +3 -1
- package/dist/docs/guides/designing-a-game.md +85 -0
- package/dist/docs/guides/endpoints.md +57 -13
- package/dist/docs/guides/engine-testing.md +4 -13
- package/dist/docs/guides/engine.md +14 -2
- package/dist/docs/guides/file-handling.md +14 -10
- package/dist/docs/guides/games.md +2 -8
- package/dist/docs/guides/guide.md +98 -6
- package/dist/docs/guides/index.md +3 -4
- package/dist/docs/guides/internationalization.md +8 -14
- package/dist/docs/guides/llm-integration.md +19 -31
- package/dist/docs/guides/multi-team-games.md +9 -14
- package/dist/docs/guides/patterns.md +0 -6
- package/dist/docs/guides/presentation.md +6 -10
- package/dist/docs/guides/production-constraints.md +3 -10
- package/dist/docs/guides/scenario-editor.md +11 -11
- package/dist/docs/guides/scenarios.md +26 -14
- package/dist/docs/guides/session.md +32 -36
- package/dist/docs/guides/settings.md +28 -2
- package/dist/docs/guides/setup.md +2 -7
- package/dist/docs/guides/speech-generation.md +8 -17
- package/dist/docs/guides/starter-game.md +2 -1
- package/dist/docs/guides/testing.md +45 -43
- package/dist/docs/guides/theming-and-branding.md +208 -0
- package/dist/docs/guides/tick-controller.md +8 -4
- package/dist/docs/guides/type-safety.md +8 -6
- package/dist/docs/guides/ui.md +41 -62
- package/dist/docs/guides/upgrading.md +13 -3
- package/dist/docs/guides/validators.md +64 -3
- package/dist/docs/guides/waiting-room.md +3 -10
- package/dist/docs/index.md +40 -10
- package/dist/docs/recipes/adapt-ui-for-observers.md +1 -1
- package/dist/docs/recipes/call-endpoint-from-ui.md +2 -0
- package/dist/docs/recipes/create-capability.md +1 -1
- package/dist/docs/recipes/create-endpoint.md +7 -2
- package/dist/docs/recipes/create-engine.md +1 -1
- package/dist/docs/recipes/create-guide.md +4 -4
- package/dist/docs/recipes/create-hook.md +1 -1
- package/dist/docs/recipes/create-session-ui.md +1 -1
- package/dist/docs/recipes/create-settings.md +1 -1
- package/dist/docs/recipes/create-tick-controller.md +1 -1
- package/dist/docs/recipes/create-user-interface.md +1 -1
- package/dist/docs/recipes/create-validator.md +1 -1
- package/dist/docs/recipes/declare-api-uses.md +2 -2
- package/dist/docs/recipes/design-state-for-concurrent-writes.md +2 -2
- package/dist/docs/recipes/distribute-package.md +3 -3
- package/dist/docs/recipes/e2e-testing.md +11 -9
- package/dist/docs/recipes/index.md +6 -2
- package/dist/docs/recipes/make-a-guide-follow-the-scenario.md +89 -0
- package/dist/docs/recipes/make-an-endpoint-external.md +1 -1
- package/dist/docs/recipes/publish-a-package.md +1 -1
- package/dist/docs/recipes/remember-a-viewers-choice.md +1 -1
- package/dist/docs/recipes/review-a-past-day.md +4 -2
- package/dist/docs/recipes/share-assets-across-scenarios.md +3 -3
- package/dist/docs/recipes/share-logic-between-engine-and-ui.md +1 -1
- package/dist/docs/recipes/test-a-multi-role-game.md +1 -1
- package/dist/docs/recipes/test-user-interface.md +13 -2
- package/dist/docs/recipes/validate-scenarios.md +91 -0
- package/dist/docs/troubleshooting.md +44 -2
- package/dist/execution/blob-inputs.d.ts +7 -2
- package/dist/execution/config-resolver.d.ts +10 -0
- package/dist/execution/endpoint-runner.d.ts +8 -1
- package/dist/execution/executor-callbacks.d.ts +7 -0
- package/dist/execution/executor.d.ts +11 -0
- package/dist/execution/logic-calls.d.ts +8 -1
- package/dist/execution/scenario-gates.d.ts +34 -0
- package/dist/guide/effective-guide.d.ts +20 -0
- package/dist/guide/locale.d.ts +12 -0
- package/dist/guide/settings.d.ts +74 -0
- package/dist/guide/video-registry.d.ts +33 -1
- package/dist/host/host-channel.d.ts +11 -2
- package/dist/host/index.d.ts +9 -1
- package/dist/host/protocol.d.ts +49 -5
- package/dist/host/theme.d.ts +28 -2
- package/dist/host.js +11621 -15
- package/dist/runtime/index.d.ts +1 -1
- package/dist/runtime/manifest-version.d.ts +17 -0
- package/dist/runtime.js +12 -1
- package/dist/schema.json +32 -4
- package/dist/storage/blob-store.d.ts +3 -2
- package/dist/templates/endpoint/logic.test.ts.liquid +19 -1
- package/dist/templates/endpoint/logic.ts.liquid +18 -0
- package/dist/templates/hook/logic.test.ts.liquid +2 -2
- package/dist/templates/package/CLAUDE.md.template +5 -2
- package/dist/templates/package/README.md.liquid +2 -0
- package/dist/templates/package/claude/rules/workflow-create-endpoint.md +5 -4
- package/dist/templates/package/claude/rules/workflow-create-guide.md +9 -2
- package/dist/templates/presentation/src/App.tsx.liquid +5 -11
- package/dist/templates/session/src/App.test.tsx.liquid +2 -4
- package/dist/templates/session/src/theme.ts.liquid +26 -33
- package/dist/templates/settings-editor/src/theme.ts.liquid +13 -18
- package/dist/templates/starter-game/hooks/assignproducts/logic/logic.test.ts +2 -8
- package/dist/templates/starter-game/session/src/App.test.tsx +6 -10
- package/dist/templates/starter-game/session/src/theme.ts +26 -33
- package/dist/templates/starter-game/ui/src/App.tsx +2 -0
- package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +25 -0
- package/dist/templates/starter-game/ui/src/HostLogo.tsx +38 -0
- package/dist/templates/starter-game/ui/src/theme.ts +26 -33
- package/dist/templates/starter-game/validators/capacity/types.ts +2 -0
- package/dist/templates/starter-game/waiting_room/src/theme.ts +26 -33
- package/dist/templates/ui/src/App.test.tsx.liquid +7 -19
- package/dist/templates/ui/src/theme.ts.liquid +26 -33
- package/dist/templates/validator/logic.ts.liquid +4 -0
- package/dist/templates/waiting-room/src/App.test.tsx.liquid +17 -31
- package/dist/templates/waiting-room/src/theme.ts.liquid +26 -33
- package/dist/utils/error-codes.d.ts +15 -3
- package/dist/validation/ajv.d.ts +9 -5
- package/dist/validation/facilitator-guide-validator.d.ts +11 -1
- package/dist/validation/file-settings.d.ts +49 -0
- package/dist/validation/guide-settings-validator.d.ts +26 -0
- package/dist/validation/schema-validation.d.ts +12 -4
- package/package.json +6 -5
- package/dist/dev/console/assets/index-DgFglsnA.js +0 -204
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Terminology
|
|
2
2
|
|
|
3
|
-
Definitions of the terms used across the SDK, the CLI, the dev server, and these docs. Each concept has one preferred name. Where
|
|
3
|
+
Definitions of the terms used across the SDK, the CLI, the dev server, and these docs. Each concept has one preferred name. Where earlier releases used another, the entry lists it under **Also called**, so you can recognise it, and says which word to use.
|
|
4
4
|
|
|
5
5
|
**Keywords:** glossary, terminology, definitions, vocabulary, naming conventions, synonyms, preferred terms
|
|
6
6
|
|
|
@@ -34,7 +34,7 @@ A participant is **not** the same as a person. Someone who opens two browser tab
|
|
|
34
34
|
|
|
35
35
|
A game UI reads its own participant with `useUserInterfaceParticipant()` and the team roster with `useUserInterfaceParticipants()`. The session UI reads every team's participants with `useSessionUserInterfaceParticipants()`.
|
|
36
36
|
|
|
37
|
-
**Also called** 'player' in
|
|
37
|
+
**Also called** 'player' in earlier releases. Use participant. A game's own copy can call them whatever suits it.
|
|
38
38
|
|
|
39
39
|
### Facilitator
|
|
40
40
|
|
|
@@ -42,7 +42,11 @@ The person running the session, from the session UI. 'Facilitator' is a human ro
|
|
|
42
42
|
|
|
43
43
|
### Author
|
|
44
44
|
|
|
45
|
-
|
|
45
|
+
Whoever is writing a scenario: a person in the scenario editor, or an agent writing its settings directly. On the platform an author may be an end user rather than a facilitator, so a scenario-scoped endpoint sees `caller.role` as `'author'`, never `'facilitator'`.
|
|
46
|
+
|
|
47
|
+
### Draft
|
|
48
|
+
|
|
49
|
+
A scenario being written and not yet saved: the settings defaults, then the scenario it started from, then every change made since. The scenario editor and an authoring agent both change a draft, and a scenario-scoped endpoint reads one. A draft belongs to no session.
|
|
46
50
|
|
|
47
51
|
### Observer
|
|
48
52
|
|
|
@@ -73,7 +77,9 @@ Which run a call belongs to: `'session'` or `'walkthrough'`. Every call into log
|
|
|
73
77
|
|
|
74
78
|
### Game
|
|
75
79
|
|
|
76
|
-
The playable
|
|
80
|
+
The playable thing a package is: its engine, capabilities, and UIs, plus how long it runs and how it is configured. Authored as `seriousgaming.sdk.json` itself, one flat object. A game is a blueprint, describing what to run rather than the state of any run.
|
|
81
|
+
|
|
82
|
+
'Game' is the technical word these docs use for whatever you build: a serious game, a business simulation, or an experiential learning exercise are all games to the SDK.
|
|
77
83
|
|
|
78
84
|
### Resource
|
|
79
85
|
|
|
@@ -150,7 +156,7 @@ An engine that runs once per tick across all teams rather than once per team, re
|
|
|
150
156
|
|
|
151
157
|
One iteration of the game loop: the engine runs on the board the teams submitted, and that board is recorded as a snapshot. Tick N closes round N. The facilitator or a UI triggers a tick by hand (the dev drawer's **Tick**, or `requestTick`), or a tick controller triggers it automatically.
|
|
152
158
|
|
|
153
|
-
**Also called** 'day' or 'turn' in
|
|
159
|
+
**Also called** 'day' or 'turn' in earlier releases. Use tick for the runtime concept. A game's own copy calls its ticks whatever fits the story: the starter game calls them days.
|
|
154
160
|
|
|
155
161
|
### Round
|
|
156
162
|
|
|
@@ -164,7 +170,7 @@ The play between two ticks. Round N opens when tick N - 1 commits (or when the g
|
|
|
164
170
|
|
|
165
171
|
`completedTicks`, wherever it appears: on a surface (`useUserInterfaceData().completedTicks`), on each team in the session UI, in an endpoint's `session`, and in `sdk view --json`. It is the number of ticks that team has completed: `0` until the first tick commits, and `N - 1` during round N. It is always one behind the engine tick of the tick in progress, so the first `Run` of a session sees `meta.tick` of `1` while every surface still shows `0`. A surface names the round in play as `completedTicks + 1`.
|
|
166
172
|
|
|
167
|
-
**Also called** the head tick in
|
|
173
|
+
**Also called** the head tick in earlier releases. Use completed ticks.
|
|
168
174
|
|
|
169
175
|
### Snapshot N
|
|
170
176
|
|
|
@@ -212,25 +218,25 @@ The session UI, setup, the scenario editor, or the presentation. A facilitator s
|
|
|
212
218
|
|
|
213
219
|
What each participant sees and plays with during the game, in the `ui` slot. It reads and writes its team's context, can request ticks, calls endpoints, and uploads files. It also sees the team roster (`useUserInterfaceParticipants()`) and basic facts about every team (`useUserInterfaceTeams()`). The resource type is `ui`, and the SDK API keeps the `UserInterface` names (`UserInterfaceWrapper`, `useUserInterfaceData`). See [Building user interfaces](../guides/ui.md).
|
|
214
220
|
|
|
215
|
-
**Also called** 'play surface', 'player UI', 'player user interface', 'participant interface' and 'game user interface' in
|
|
221
|
+
**Also called** 'play surface', 'player UI', 'player user interface', 'participant interface' and 'game user interface' in earlier releases. Use game UI, or player surface when the waiting room UI is meant too.
|
|
216
222
|
|
|
217
223
|
### Session UI
|
|
218
224
|
|
|
219
225
|
The facilitator's whole-session screen, in the `session` slot. It reads and writes every team's context, controls ticks for one team or all of them, manages the roster, writes shared capabilities it declares, and reads the session's join links. Its game-flow callbacks take an optional `teamId` to target one team. In the dev server it is the page at `/`. See [Building session UIs](../guides/session.md).
|
|
220
226
|
|
|
221
|
-
**Also called** 'session surface', 'facilitator UI' and 'session user interface' in
|
|
227
|
+
**Also called** 'session surface', 'facilitator UI' and 'session user interface' in earlier releases. Use session UI, or facilitator surface when setup, the scenario editor and the presentation are meant too.
|
|
222
228
|
|
|
223
229
|
### Setup
|
|
224
230
|
|
|
225
231
|
The short form a facilitator fills in at session creation, in the `setup` slot. It edits the settings it lists in `configures` and writes that session's overrides only, never context. A game with a setup slot opens at its **configuration step**, which closes when the facilitator presses **Play** (or the form sends `requestPlay`). See [Building a setup screen](../guides/setup.md).
|
|
226
232
|
|
|
227
|
-
**Also called** 'quick config' and 'configuration UI' in
|
|
233
|
+
**Also called** 'quick config' and 'configuration UI' in earlier releases. Use setup.
|
|
228
234
|
|
|
229
235
|
### Scenario editor
|
|
230
236
|
|
|
231
237
|
The screen for authoring lasting scenarios, in the `scenario_editor` slot. It works at any time, with no session, and its output is a saved scenario; the host offers save-as-scenario from it and never from setup. It is optional: `customScenarios.supported` switches custom scenarios on, and an agent can author one from well-described settings schemas alone. See [Building a scenario editor](../guides/scenario-editor.md).
|
|
232
238
|
|
|
233
|
-
**Also called** 'scenario builder' and 'configuration UI' in
|
|
239
|
+
**Also called** 'scenario builder' and 'configuration UI' in earlier releases. Use scenario editor.
|
|
234
240
|
|
|
235
241
|
### Settings editor
|
|
236
242
|
|
|
@@ -240,7 +246,7 @@ Setup and the scenario editor together: the two slots that edit settings rather
|
|
|
240
246
|
|
|
241
247
|
The holding screen participants see in place of the game UI while the session's waiting room is open, in the `waiting_room` slot. The facilitator opens and closes the room for every team at once, and `waitingRoom.openOnStart` starts a session with it open. Without one, the host shows its own built-in panel. See [Building waiting room UIs](../guides/waiting-room.md).
|
|
242
248
|
|
|
243
|
-
**Also called** 'waiting room user interface' in
|
|
249
|
+
**Also called** 'waiting room user interface' in earlier releases. Use waiting room UI.
|
|
244
250
|
|
|
245
251
|
### Presentation
|
|
246
252
|
|
|
@@ -7,8 +7,11 @@ Scaffold the starter game, play it in the dev server, change one thing, and see
|
|
|
7
7
|
## Prerequisites
|
|
8
8
|
|
|
9
9
|
- Node.js 24 or later
|
|
10
|
-
- pnpm 12
|
|
10
|
+
- pnpm 12. If `pnpm --version` says otherwise, run `corepack enable`, or see [installing pnpm](https://pnpm.io/installation)
|
|
11
11
|
- A text editor, and some familiarity with TypeScript and React
|
|
12
|
+
- Two terminals: one for the dev server, which keeps running, and one for everything else
|
|
13
|
+
|
|
14
|
+
No account is needed for any of this. A platform account comes in only when you [publish](./recipes/publish-a-package.md).
|
|
12
15
|
|
|
13
16
|
## 1. Scaffold the starter game
|
|
14
17
|
|
|
@@ -20,17 +23,27 @@ cd my-game
|
|
|
20
23
|
pnpm dlx @seriousgaming/sdk-tools new package
|
|
21
24
|
```
|
|
22
25
|
|
|
23
|
-
The command asks for three things: the package identifier
|
|
26
|
+
The command asks for three things: the package identifier, reverse-domain, such as `com.example.mygame`; the game's name, such as `My Game`; and a version, such as `0.1.0`. To answer them up front instead, which is what an AI agent or a script should do, pass them as JSON:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
pnpm dlx @seriousgaming/sdk-tools new package '{"identifier":"com.example.mygame","name":"My Game","version":"0.1.0"}'
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Either way, the command then writes the package, installs its dependencies, and generates each resource's `types.ts`. There is no separate install step. If the install fails, the package is still written and the command tells you so; run `pnpm install` yourself once the cause is fixed.
|
|
24
33
|
|
|
25
34
|
What you get is a complete game rather than an empty shell. A lemonade stand, for 10 days: each morning a team decides how many lemonades, iced teas, and cookies to make. Whatever they make they pay for, whatever is left at closing is poured away, and anyone who wanted something that ran out simply leaves.
|
|
26
35
|
|
|
27
36
|
The game is copied out whole rather than rendered from templates, and it is the same game the SDK's own test suites play, so what you are handed is known to work. Pass `--empty` if you want only the package files and nothing else; [Start a game from an empty package](./recipes/start-from-an-empty-package.md) picks up from there.
|
|
28
37
|
|
|
29
|
-
## 2.
|
|
38
|
+
## 2. Play it
|
|
30
39
|
|
|
31
|
-
|
|
40
|
+
A few words come up from here on, each defined in full in the [terminology](./concepts/terminology.md):
|
|
32
41
|
|
|
33
|
-
|
|
42
|
+
- **Tick**: one round of the game. The engine runs once per tick, and this game calls a tick a day
|
|
43
|
+
- **Engine**: the game's rules, in `engine/logic.ts`, which work out what a round's decisions caused
|
|
44
|
+
- **Capability**: a named piece of a team's state, such as the `plan` a team makes or the `results` of a day
|
|
45
|
+
- **Context**: all of a team's capabilities together, which is what the engine and the screens read
|
|
46
|
+
- **Surface**: any screen the game shows: the game UI each participant plays, the session UI the facilitator runs it from, and the waiting room
|
|
34
47
|
|
|
35
48
|
Start the dev server:
|
|
36
49
|
|
|
@@ -47,7 +60,11 @@ The starter game begins with its participants held in the waiting room, which is
|
|
|
47
60
|
3. Open `http://localhost:3000/team/1/player/2` as well. Each participant is put in charge of one item on the menu, so the two tabs can change different numbers without overwriting each other
|
|
48
61
|
4. Set how many of each thing to make, then press **Open the stall**. The engine runs one tick, which this game calls a day, and **How yesterday went** shows what sold, what was poured away, and who was turned away
|
|
49
62
|
|
|
50
|
-
Press the backtick key on any page for the dev drawer: tick, undo, and reset controls, the state as JSON, and the list of surfaces. Every page takes `?bare` to hide the dev
|
|
63
|
+
Press the backtick key on any page for the dev drawer: tick, undo, and reset controls, the state as JSON, and the list of surfaces. Every page takes `?bare` to hide the dev server's own controls and show the screen as a participant sees it.
|
|
64
|
+
|
|
65
|
+
## 3. Take the tour
|
|
66
|
+
|
|
67
|
+
[A tour of the starter game](./guides/starter-game.md) walks through every directory and file of the game you just played, says what each one does, and points at the guide that goes deeper. Skim it now, or keep it open beside the next steps.
|
|
51
68
|
|
|
52
69
|
## 4. Change a setting
|
|
53
70
|
|
|
@@ -70,7 +87,7 @@ Halve it for this session:
|
|
|
70
87
|
pnpm run sdk configure '{"menu":{"Capacity":60}}'
|
|
71
88
|
```
|
|
72
89
|
|
|
73
|
-
The key is the settings identifier, `menu`, the directory name under `settings/`. `configure` validates the value against that schema and writes it to `.seriousgaming-sdk/configuration.json
|
|
90
|
+
The key is the settings identifier, `menu`, the directory name under `settings/`. `configure` validates the value against that schema and writes it to `.seriousgaming-sdk/configuration.json`. That file holds this session's overrides, which win over the scenario's and the defaults (see [Overriding settings](./guides/settings.md#overriding-settings)). The game's validator and UI read it as `settings.menu.Capacity`. Settings are fixed when play starts, so `configure` puts the running session back at tick 0 on the new value. The stall now says it can make 60 things in a day, and a plan over 60 is refused by the game's validator, the check that runs on every decision before it is saved.
|
|
74
91
|
|
|
75
92
|
To go back to the defaults, clear the overrides, which restarts the session on them:
|
|
76
93
|
|
|
@@ -96,7 +113,7 @@ spent += sold * entry.Cost;
|
|
|
96
113
|
|
|
97
114
|
Save the file and play another day. You do not need to restart anything or reset the session. The dev server watches the package, and the next tick runs the new code. What it does not do is re-run days already played, so the change shows from the next day onwards: **Spent** no longer counts what was poured away, so making too much stops costing anything.
|
|
98
115
|
|
|
99
|
-
Edits to a UI hot-reload in the browser, and edits to a `*.sdk.json` bundle or to `seriousgaming.sdk.json` are picked up without a restart too. A change to a setting, which reaches the game through `Init`, waits for you to re-initialise once a day has been played: the console says so and offers a button. The [CLI reference](./cli-reference.md#what-reloads) has the whole table.
|
|
116
|
+
Edits to a UI hot-reload in the browser, and edits to a resource's `*.sdk.json` file (its bundle) or to `seriousgaming.sdk.json` are picked up without a restart too. A change to a setting, which reaches the game through `Init`, waits for you to re-initialise, starting the session again from day one, once a day has been played: the console says so and offers a button. The [CLI reference](./cli-reference.md#what-reloads) has the whole table.
|
|
100
117
|
|
|
101
118
|
## 6. Drive it from the CLI and run its tests
|
|
102
119
|
|
|
@@ -107,7 +124,7 @@ pnpm run sdk tick --patch '[{"op":"replace","path":"/plan/Make/lemonade","value"
|
|
|
107
124
|
pnpm run sdk view
|
|
108
125
|
```
|
|
109
126
|
|
|
110
|
-
`tick --patch` writes a decision into the context, here 70 lemonades, and then runs a tick; `view` prints the session as JSON. Both reach the dev server you started in step
|
|
127
|
+
`tick --patch` writes a decision into the context, here 70 lemonades, and then runs a tick; `view` prints the session as JSON. Both reach the dev server you started in step 2, so the browser repaints as they run.
|
|
111
128
|
|
|
112
129
|
Session commands (`init`, `tick`, `view`, `patch`, `undo`, `reset`, and the rest) always talk to a dev server. If none is running, the command starts one in the background, says so on stderr, and leaves it running for the next command. Check on it or stop it with:
|
|
113
130
|
|
|
@@ -125,7 +142,7 @@ pnpm test:run
|
|
|
125
142
|
pnpm test:engine
|
|
126
143
|
```
|
|
127
144
|
|
|
128
|
-
`test:run` runs the unit tests beside each resource, and `test:engine` plays whole games in-process with
|
|
145
|
+
`test:run` runs the unit tests beside each resource, and `test:engine` plays whole games in-process with no server and no browser (through `createTestSession`, from `@seriousgaming/sdk-tools/client`). With the change from step 5 in place, one test in each suite fails: `pours away what it made and did not sell, having paid for it` in the unit tests, and `pours away what nobody wanted, having already paid for it` in the whole-game tests. That is the suite guarding the rule you just changed. Put the line back, or update the tests if the new rule is the one you want. `pnpm test:e2e` runs the browser tests with Playwright. They start a dev server of their own, and a package holds one session, so stop yours first with `sdk dev stop` or Ctrl+C.
|
|
129
146
|
|
|
130
147
|
## Working with an AI coding agent
|
|
131
148
|
|
|
@@ -134,11 +151,13 @@ A scaffolded package includes a `CLAUDE.md` and `.claude/rules/` written for cod
|
|
|
134
151
|
- Session commands print JSON, so an agent can read state with `view` and make decisions with `tick --patch`
|
|
135
152
|
- Use `pnpm run --silent` when parsing output, so pnpm's banner stays out of the JSON
|
|
136
153
|
- The dev server and the CLI share one session, so you can watch in the browser while an agent plays from the terminal
|
|
154
|
+
- An agent working alone should add `--no-server` to session commands, so nothing is left running, and leave `sdk dev` for you to start
|
|
137
155
|
|
|
138
|
-
[The CLI and the dev server](./cli-and-dev-server.md) explains how the two fit together.
|
|
156
|
+
[For AI agents](./ai-agents.md) has the whole loop an agent follows, and [The CLI and the dev server](./cli-and-dev-server.md) explains how the two fit together.
|
|
139
157
|
|
|
140
158
|
## Next steps
|
|
141
159
|
|
|
160
|
+
- [Designing a serious game](./guides/designing-a-game.md): before you replace the lemonade stand, decide what your game should teach and how its rounds teach it
|
|
142
161
|
- [Design state for concurrent writes](./recipes/design-state-for-concurrent-writes.md): the rule the starter game is built around. Keep its shape when you replace its model
|
|
143
162
|
- [Terminology](./concepts/terminology.md): the words the rest of the docs use, each with one meaning
|
|
144
163
|
- [Core concepts](./concepts/index.md): why the SDK is shaped the way it is
|
|
@@ -1,9 +1,13 @@
|
|
|
1
1
|
# Structuring a game for AI facilitation
|
|
2
2
|
|
|
3
|
-
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'.
|
|
3
|
+
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'.
|
|
4
|
+
|
|
5
|
+
This guide covers what that agent can see, what it can do, and what you as an author need to write down so it behaves.
|
|
4
6
|
|
|
5
7
|
Most of it is not new machinery. An agent acting for a facilitator is close to a facilitator's own screen: it sees what a screen declares, and it acts through endpoints. What is new is that the words you write become load-bearing, because a model reads them to decide what to do.
|
|
6
8
|
|
|
9
|
+
Write for an agent that supports the facilitator's judgement rather than replacing it: the facilitator still reads the room and decides what happens next.
|
|
10
|
+
|
|
7
11
|
## What the agent can see
|
|
8
12
|
|
|
9
13
|
A game's data lives in named capabilities. Every screen declares which ones it needs, and receives exactly those. The agent is handed data the same way, so nothing you have not declared reaches it.
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
# Capabilities
|
|
2
2
|
|
|
3
|
-
Capabilities hold your game's state
|
|
3
|
+
Capabilities hold your game's state: named groups of variables that the engine and screens read and write.
|
|
4
|
+
|
|
5
|
+
This guide explains the state model, who sees and writes each capability, and how long its values last, then covers creating capabilities and every kind of variable they hold.
|
|
4
6
|
|
|
5
7
|
## The state model
|
|
6
8
|
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# Designing a serious game
|
|
2
|
+
|
|
3
|
+
A serious game teaches by letting people act and then see what their actions caused. This guide takes you from what a game should teach to the decisions, rounds, feedback, and debrief that teach it, and then to the parts of a package each one becomes. The starter game, Lemonade Stand, is the worked example throughout.
|
|
4
|
+
|
|
5
|
+
The rest of the docs explain how to build each part. This page is about what to build, so read it before you replace the lemonade stand with your own game.
|
|
6
|
+
|
|
7
|
+
## Start from what people should take away
|
|
8
|
+
|
|
9
|
+
Write down the one or two things a participant should understand, or do differently, by the end. Everything else in the design serves them.
|
|
10
|
+
|
|
11
|
+
Lemonade Stand has one: making too much and making too little are both mistakes, they cost different amounts, and the costlier one is the one you cannot see. A good learning outcome is like that: specific enough that you can tell whether a round of play showed it.
|
|
12
|
+
|
|
13
|
+
Then ask what experience would make the point land better than being told it. A serious game earns its place when the lesson is easy to agree with and hard to act on: people nod at 'unsold stock is waste' and then over-correct after one bad day. Play lets them make that mistake, feel it, and talk about it in the debrief.
|
|
14
|
+
|
|
15
|
+
## Choose the decisions
|
|
16
|
+
|
|
17
|
+
A decision is what a team changes each round. Pick the smallest set that carries the learning outcome:
|
|
18
|
+
|
|
19
|
+
- **Few, and meaningful**: every decision should pull against another. Lemonade Stand has one per menu item, how many to make, and they all draw on the same 120 a day the stall can make
|
|
20
|
+
- **No right answer from the screen**: if the best choice can be worked out from what is shown, the game becomes arithmetic. Lemonade Stand's forecast is close to the day's demand, never exact
|
|
21
|
+
- **Something to talk about**: a decision a team can disagree on gives the facilitator something to listen for
|
|
22
|
+
|
|
23
|
+
Each decision becomes a value in a [capability](./capabilities.md), the state a team writes to. Lemonade Stand's live in `plan`, one number per item. Key them so two teammates changing two decisions never overwrite each other: see [Design state for concurrent writes](../recipes/design-state-for-concurrent-writes.md).
|
|
24
|
+
|
|
25
|
+
## Decide what each round shows
|
|
26
|
+
|
|
27
|
+
Feedback is where the learning happens during play. After each round, a team should see what their decisions caused, in terms they can act on next round:
|
|
28
|
+
|
|
29
|
+
- **Consequences, not just a score**: Lemonade Stand's 'How yesterday went' shows what sold, what was poured away, and who was turned away, not just the money
|
|
30
|
+
- **Both sides of the trade-off**: if one mistake is visible and the other is not, show the invisible one. The lemonade stand counts the people it turned away for exactly this reason
|
|
31
|
+
- **Enough to change their mind**: the round's results should suggest what to try next, without telling them
|
|
32
|
+
|
|
33
|
+
The rules that turn decisions into consequences are the [engine](./engine.md): its `Run` plays one round, and the results go into capabilities the screens read. What the screens show, and how, is the [game UI](./ui.md).
|
|
34
|
+
|
|
35
|
+
## Set the pace and the length
|
|
36
|
+
|
|
37
|
+
How many rounds, and who decides when each one ends, is a learning-design choice as much as a technical one:
|
|
38
|
+
|
|
39
|
+
- **Enough rounds to try, fail, and try again**: a lesson about adjusting needs at least three or four rounds after the first mistake. Lemonade Stand runs ten days; its Heatwave scenario runs five
|
|
40
|
+
- **Who ends the round**: when the facilitator or the team ends each round, there is time to discuss. When a [tick controller](./tick-controller.md) ends it on a timer, there is pressure, which suits a lesson about deciding with too little time
|
|
41
|
+
- **Together or apart**: in an independent game, each team plays at its own pace, as the lemonade stalls do. In a shared one, teams play the same market or the same world, and every round waits for all of them. See [Multi-team games](./multi-team-games.md)
|
|
42
|
+
|
|
43
|
+
The number of rounds is `maxTicks`, a [setting](./settings.md) a scenario or a facilitator can change.
|
|
44
|
+
|
|
45
|
+
## Make room for the facilitator
|
|
46
|
+
|
|
47
|
+
The facilitator turns play into learning. Give them what they need to do that:
|
|
48
|
+
|
|
49
|
+
- **A view of the whole room**: the [session UI](./session.md) shows every team side by side, so a facilitator can spot a team that has stopped thinking and go and talk to them
|
|
50
|
+
- **Control**: holding the room in the [waiting room](./waiting-room.md) for a briefing, undoing a round a team did not mean to play, and ending the game
|
|
51
|
+
- **A guide**: the [facilitator guide](./guide.md) is the run-sheet: timings, what to say, what to watch for, and the debrief questions. Write it alongside the game, not after
|
|
52
|
+
- **Room to adapt**: put every number a facilitator might want to change in [settings](./settings.md), and offer them a [setup screen](./setup.md) for the ones that change from group to group
|
|
53
|
+
|
|
54
|
+
Make mistakes safe. Undo, a practice round, and results that point at the decision rather than the person all help the psychological safety people need to try something they are unsure of.
|
|
55
|
+
|
|
56
|
+
## Plan the debrief
|
|
57
|
+
|
|
58
|
+
The debrief is where the experience becomes lasting learning, so design it from the start rather than adding it at the end:
|
|
59
|
+
|
|
60
|
+
- **Questions first**: write the questions you want the room to answer, such as 'which mistake did you make more often, and which cost you more?'. Then make sure the game produces the evidence for each answer
|
|
61
|
+
- **Evidence from the session**: a [presentation](./presentation.md) builds its slides from the session's own results, so the room sees its own numbers, not a generic example
|
|
62
|
+
- **Look back**: a team can [review a past round](../recipes/review-a-past-day.md) to see the moment a decision went wrong
|
|
63
|
+
|
|
64
|
+
Lemonade Stand's guide closes its debrief on the two kinds of mistake, with questions such as 'Which mistake did your stall prefer, and did you ever say so out loud?', and every stall's results show both what it poured away and whom it turned away.
|
|
65
|
+
|
|
66
|
+
## Plan for variety
|
|
67
|
+
|
|
68
|
+
One game can serve different groups and different objectives through [scenarios](./scenarios.md): named sets of settings and assets. Lemonade Stand has two, 'An ordinary week' and 'Heatwave', which teach the same outcome with different pressure. A scenario changes values, never rules, so decide early which numbers belong in settings.
|
|
69
|
+
|
|
70
|
+
## From design to package
|
|
71
|
+
|
|
72
|
+
| Design decision | Where it goes |
|
|
73
|
+
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
|
74
|
+
| What teams decide each round | A [capability](./capabilities.md) they write to, and the [game UI](./ui.md) they write from |
|
|
75
|
+
| The rules that turn decisions into results | The [engine](./engine.md) |
|
|
76
|
+
| What each round shows | A results capability the engine writes, shown in the game UI |
|
|
77
|
+
| Limits a decision must respect | A [validator](./validators.md), which refuses a decision and says why |
|
|
78
|
+
| The numbers a facilitator may vary | [Settings](./settings.md), and a [setup screen](./setup.md) if they vary per session |
|
|
79
|
+
| Different versions of the game | [Scenarios](./scenarios.md) |
|
|
80
|
+
| The round length and the game's length | `maxTicks` in the game settings, and a [tick controller](./tick-controller.md) for timed rounds |
|
|
81
|
+
| The facilitator's view and controls | The [session UI](./session.md) and the [waiting room UI](./waiting-room.md) |
|
|
82
|
+
| The run-sheet and the debrief | The [facilitator guide](./guide.md) and the [presentation](./presentation.md) |
|
|
83
|
+
| Characters, feedback, or reports that react to what a team did | [Generated text](./llm-integration.md) and [speech](./speech-generation.md) |
|
|
84
|
+
|
|
85
|
+
Then build it: [A tour of the starter game](./starter-game.md) shows each of these in Lemonade Stand, and [Start a game from an empty package](../recipes/start-from-an-empty-package.md) starts from nothing.
|
|
@@ -43,11 +43,17 @@ To scaffold one, follow [Create an endpoint](../recipes/create-endpoint.md).
|
|
|
43
43
|
|
|
44
44
|
## Scope
|
|
45
45
|
|
|
46
|
-
`scope` says what a call acts on
|
|
46
|
+
`scope` says what a call acts on, and is one of three:
|
|
47
47
|
|
|
48
|
-
|
|
48
|
+
- `team` (the default): one team. The handler receives that team's board and a `team` naming it (`teamId`, `index` and `name`), whoever calls it
|
|
49
|
+
- `session`: the session as a whole. The handler has no single team, because there is none for it to mean anything against
|
|
50
|
+
- `scenario`: a scenario being written, with no session at all. See [Scenario-scoped endpoints](#scenario-scoped-endpoints)
|
|
49
51
|
|
|
50
|
-
The
|
|
52
|
+
The surface calling an endpoint has to be able to supply what its scope needs, and the build fails when it cannot:
|
|
53
|
+
|
|
54
|
+
- A session UI or setup screen has no team of its own, so it may not list a team-scoped endpoint. The build tells you to declare it `"scope": "session"`
|
|
55
|
+
- The scenario editor writes a scenario rather than playing one, so it lists scenario-scoped endpoints alone (`EDITOR_ENDPOINT_NOT_SCENARIO`)
|
|
56
|
+
- Every other surface runs in a session, so none may list a scenario-scoped endpoint
|
|
51
57
|
|
|
52
58
|
Do not put a team in a request schema. A caller outside the game names the team it means through the platform, which hands it to your handler on `team`, so a team the caller typed can never be a team it invented.
|
|
53
59
|
|
|
@@ -116,25 +122,63 @@ The handler receives:
|
|
|
116
122
|
- `settings`: exactly the settings resources listed in `settings`, keyed by identifier, read-only
|
|
117
123
|
- `callbacks`: the callbacks named in `uses`, plus the ungated `readAsset` and `getPastState`. An undeclared gated callback throws
|
|
118
124
|
- `caller`: who is calling, issued by the host and never by the iframe (see below)
|
|
119
|
-
- `meta`: the facts true of the whole run: `meta.locale` (the session locale), `meta.seed`, `meta.runKind
|
|
125
|
+
- `meta`: the facts true of the whole run: `meta.locale` (the session locale), `meta.seed`, `meta.runKind`, `meta.now`, the instant the call started, and `meta.scenarioName`, the active scenario's name for display
|
|
120
126
|
- `participants`: a read-only copy of the roster the call covers, the addressed team's on a team-scoped endpoint and every participant on a session-scoped one
|
|
121
127
|
- `session`: where the session stands ([Acting on the session](#acting-on-the-session))
|
|
122
128
|
|
|
123
|
-
`caller` carries `role`, and, where they apply, `sessionId`, `teamId`, `playerId`, `userInterfaceIdentifier` and `principal`. `sessionId` is absent only on a call
|
|
129
|
+
`caller` carries `role`, and, where they apply, `sessionId`, `teamId`, `playerId`, `userInterfaceIdentifier` and `principal`. `sessionId` is absent only on a call to a scenario-scoped endpoint, which has no session. `role` is `'participant'`, `'observer'`, `'facilitator'`, `'author'` or `'external'`: a session UI and a setup screen report `'facilitator'`, every call to a scenario-scoped endpoint reports `'author'`, and any other caller outside the game reports `'external'` with no `userInterfaceIdentifier`. An author is whoever is creating a scenario, who on the platform may not be a facilitator, so an endpoint that trusts a facilitator further than other callers should not extend that to an author. `principal` is the platform's account of which agent or API key made an external call, so an endpoint can answer one caller differently from another.
|
|
124
130
|
|
|
125
131
|
`caller.teamId` is the caller's own team, set for a participant or an observer and absent for a facilitator, an author or an outside caller. It is not the team the call acts on: read that from `team`. A facilitator calling a team-scoped endpoint has `team` and no `caller.teamId`; a participant has both, and they are equal.
|
|
126
132
|
|
|
127
|
-
###
|
|
133
|
+
### Scenario-scoped endpoints
|
|
134
|
+
|
|
135
|
+
A scenario is written outside any session: in the scenario editor, or by an agent writing its settings directly. What is being written is a **draft**: the settings defaults, then the scenario it started from, then every change not yet saved. A scenario-scoped endpoint is your game's code working on a draft. It tells whoever is writing the scenario something they cannot work out from the settings alone, and changes nothing:
|
|
136
|
+
|
|
137
|
+
- **Work out a consequence**, such as what a round would come to at a given price under the draft. Only your game's code knows the model, so this is the most useful kind
|
|
138
|
+
- **Make a file for a setting**, such as speech for a briefing or a generated image. Call `writeBlob` or `generateSpeech` and return the `blob:` reference; the author writes it into a [file setting](./settings.md#settings-that-hold-a-file)
|
|
139
|
+
|
|
140
|
+
It does not edit settings, and it does not check a scenario (that is a validator's [`Scenario` gate](./validators.md)). The author changes the draft; an endpoint informs the change.
|
|
141
|
+
|
|
142
|
+
```json
|
|
143
|
+
{
|
|
144
|
+
"definition": {
|
|
145
|
+
"description": "Works out what one round would come to under the scenario being written, at a price and workforce you name.",
|
|
146
|
+
"scope": "scenario",
|
|
147
|
+
"visibility": "external",
|
|
148
|
+
"settings": ["engine"],
|
|
149
|
+
"requestSchema": {
|
|
150
|
+
"type": "object",
|
|
151
|
+
"properties": { "price": { "type": "number" } },
|
|
152
|
+
"required": ["price"],
|
|
153
|
+
"additionalProperties": false
|
|
154
|
+
},
|
|
155
|
+
"responseSchema": {
|
|
156
|
+
"type": "object",
|
|
157
|
+
"properties": { "profit": { "type": "number" } },
|
|
158
|
+
"required": ["profit"],
|
|
159
|
+
"additionalProperties": false
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
It runs with no session, even in a dev server running one beside it, so it may declare no `reads`, `writes`, `actions` or `roster` (`SCENARIO_ENDPOINT_STATEFUL`). Its handler receives:
|
|
166
|
+
|
|
167
|
+
- `request`, validated as any endpoint's
|
|
168
|
+
- `settings`: the settings it declares, as the draft resolves them. Declare `settings` rather than passing values in the request, so the endpoint sees the draft as it stands
|
|
169
|
+
- `callbacks`: those its `uses` admits
|
|
170
|
+
- `caller`: always `role: 'author'`, with no `sessionId`, `teamId` or `playerId`. From the scenario editor it names the editor in `userInterfaceIdentifier`; from an agent it names no surface, and may carry a `principal`
|
|
171
|
+
- `meta`: the author's locale, and as `scenarioName` the name of the scenario the draft started from, or `null`
|
|
172
|
+
|
|
173
|
+
There is no `context`, `participants`, `session`, `team` or `teams`, and the generated `Handler` type does not offer them. It returns its response alone, through `Handle`.
|
|
174
|
+
|
|
175
|
+
**Who calls it.** The scenario editor calls those it lists in `endpoints`. An agent writing a scenario calls those marked `"visibility": "external"` (see [Calling from outside the game](#calling-from-outside-the-game)), on its draft, and still as `'author'`. Mark an endpoint external when it is worth an agent's call; leave one internal to keep it to your editor screen, such as an expensive assistant.
|
|
128
176
|
|
|
129
|
-
|
|
177
|
+
**Files it makes belong to the draft.** A file a scenario-scoped call stores, through `writeBlob`, `generateSpeech` or a file input, is kept with the scenario rather than any session, whatever retention the handler asks for (see [Retention](./file-handling.md#blob-scopes)).
|
|
130
178
|
|
|
131
|
-
|
|
132
|
-
- `context`: empty, with no `team` or `teams`
|
|
133
|
-
- `participants`: empty
|
|
134
|
-
- `session`: the game's `mode` and the scenario's tick limit, with nothing played and no teams
|
|
135
|
-
- `caller`: `role: 'author'` and `userInterfaceIdentifier: 'scenario_editor'`, with no `sessionId`, `teamId` or `playerId`
|
|
179
|
+
In the dev server, try one as an agent would with `pnpm run sdk endpoint call <identifier> --draft [scenario] --external`.
|
|
136
180
|
|
|
137
|
-
The full argument and result types are in the API reference: [`EndpointBaseArgs`](../api/sdk.md#endpointbaseargs), [`EndpointCaller`](../api/sdk.md#endpointcaller) and [`EndpointSession`](../api/sdk.md#endpointsession).
|
|
181
|
+
The full argument and result types are in the API reference: [`EndpointBaseArgs`](../api/sdk.md#endpointbaseargs), [`ScenarioEndpointArgs`](../api/sdk.md#scenarioendpointargs), [`EndpointCaller`](../api/sdk.md#endpointcaller) and [`EndpointSession`](../api/sdk.md#endpointsession).
|
|
138
182
|
|
|
139
183
|
### Changing state
|
|
140
184
|
|
|
@@ -2,15 +2,6 @@
|
|
|
2
2
|
|
|
3
3
|
Test your whole game in-process: no dev server, no browser, and no LLM API key required, because service callbacks are stubbed by default.
|
|
4
4
|
|
|
5
|
-
## What you'll learn
|
|
6
|
-
|
|
7
|
-
- What `createTestSession` is and when to use it
|
|
8
|
-
- How engine tests fit alongside unit tests and Playwright tests
|
|
9
|
-
- How to write engine tests: ticking, asserting context, injecting decisions
|
|
10
|
-
- How to test hooks, validators, endpoints, undo and timers
|
|
11
|
-
- How service callbacks are stubbed, and how to override them or reach the platform
|
|
12
|
-
- How to move a test from `GameRunner`, which has been removed
|
|
13
|
-
|
|
14
5
|
## What is createTestSession?
|
|
15
6
|
|
|
16
7
|
`createTestSession` starts the session the dev server runs, inside your test process. Everything a game does is there: `Init` and `Run`, hooks when somebody joins, validators on a participant's write, endpoints, undo, independent teams ticking on their own, the configuration step, and automatic ticks. You drive it with the same commands the console, the CLI and your surfaces send, and read it with the same state `sdk view --full` prints.
|
|
@@ -471,7 +462,7 @@ Two behaviours differ, both towards what the dev server does. A tick past the li
|
|
|
471
462
|
|
|
472
463
|
## Related
|
|
473
464
|
|
|
474
|
-
- [Engine testing recipe](../recipes/test-with-engine.md)
|
|
475
|
-
- [Testing guide](./testing.md)
|
|
476
|
-
- [E2E testing with Playwright](../recipes/e2e-testing.md)
|
|
477
|
-
- [Drive a game from the CLI](../cli-simulation-testing.md)
|
|
465
|
+
- [Engine testing recipe](../recipes/test-with-engine.md): step-by-step setup for an existing project
|
|
466
|
+
- [Testing guide](./testing.md): unit tests for the engine and React components
|
|
467
|
+
- [E2E testing with Playwright](../recipes/e2e-testing.md): browser-based UI tests
|
|
468
|
+
- [Drive a game from the CLI](../cli-simulation-testing.md): test through `sdk tick` and `sdk view` against a live session
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
# Engines
|
|
2
2
|
|
|
3
|
-
The engine is the logic that moves your game forward: it sets up the board, then plays one round each tick.
|
|
3
|
+
The engine is the logic that moves your game forward: it sets up the board, then plays one round each tick.
|
|
4
|
+
|
|
5
|
+
This guide explains how an engine is shaped and why, then covers everything you write in one.
|
|
4
6
|
|
|
5
7
|
## The model
|
|
6
8
|
|
|
@@ -403,7 +405,17 @@ Two rules worth knowing before you reach for it:
|
|
|
403
405
|
1. **Variation that depends on the other teams belongs in `InitAggregate`.** `Init` runs once for each team, but sees only that team's context, so it cannot tell teams apart beyond `meta.index` or balance one against another. `InitAggregate` sees every team at once, each with its own `index`. See [Multi-team games](./multi-team-games.md)
|
|
404
406
|
2. **Freeze what later ticks depend on.** If tick 5 needs the same value tick 1 dealt, write it into context in tick 1 rather than re-deriving it from parts that may have changed
|
|
405
407
|
|
|
406
|
-
`meta` also carries `teamId` and `index`, which name the team whose context you were given (`'team-1'` in a single-team game), and `tick` (the tick being executed), `locale`, `now`, and `
|
|
408
|
+
`meta` also carries `teamId` and `index`, which name the team whose context you were given (`'team-1'` in a single-team game), and `tick` (the tick being executed), `locale`, `now`, `runKind` and `scenarioName`.
|
|
409
|
+
|
|
410
|
+
### Showing the scenario
|
|
411
|
+
|
|
412
|
+
`meta.scenarioName` is the name of the scenario the session is running, in the session's language, or `null` when it runs on the game's own settings. Use it to say which scenario a report or a debrief came from, since a facilitator may keep several copies of one scenario:
|
|
413
|
+
|
|
414
|
+
```typescript
|
|
415
|
+
const heading = meta.scenarioName ? `${meta.scenarioName} debrief` : 'Debrief';
|
|
416
|
+
```
|
|
417
|
+
|
|
418
|
+
Show it; never branch on it. A facilitator who saves their own copy of one of your scenarios gets a scenario with a new name, so logic that compared names would treat the copy as a different game. Everything a scenario changes reaches you as settings, which a copy carries over, so vary on those. A host that predates the field leaves it out, so treat a missing value as `null`. Your user interfaces read the same name as `scenarioName` from their data hooks (see [User interfaces](./ui.md)).
|
|
407
419
|
|
|
408
420
|
### Walkthroughs
|
|
409
421
|
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
# File handling (assets and blobs)
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
This guide explains the scheme, then covers uploading files at runtime, displaying them in UIs, and reading their bytes in logic.
|
|
4
6
|
|
|
5
7
|
Common uses include uploading a market research PDF in a decisions UI, displaying it in a results UI, and summarising it with an LLM inside an engine.
|
|
6
8
|
|
|
@@ -300,18 +302,19 @@ See [Take a file in an endpoint](../recipes/take-a-file-in-an-endpoint.md).
|
|
|
300
302
|
|
|
301
303
|
Every blob is stored with a retention that controls its lifetime:
|
|
302
304
|
|
|
303
|
-
| Retention | Lifetime | When to use
|
|
304
|
-
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
305
|
-
| `"game"` | Cleared on a session reset or a re-initialise | Participant-uploaded content for a specific game session
|
|
306
|
-
| `"settings"` | Survives a session reset and the automatic re-initialise after a package edit; cleared on a manual re-initialise, a reconfigure or a scenario change | Documents set up before the game starts (e.g. a
|
|
305
|
+
| Retention | Lifetime | When to use |
|
|
306
|
+
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
|
|
307
|
+
| `"game"` | Cleared on a session reset or a re-initialise | Participant-uploaded content for a specific game session |
|
|
308
|
+
| `"settings"` | Survives a session reset and the automatic re-initialise after a package edit; cleared on a manual re-initialise, a reconfigure or a scenario change | Documents set up before the game starts (e.g. a brief uploaded from setup) |
|
|
309
|
+
| `"scenario"` | Belongs to a scenario draft, not a session, so no session operation clears it; kept for as long as a saved scenario uses it | Files for a scenario being written (e.g. a client's logo for a file setting) |
|
|
307
310
|
|
|
308
|
-
Retention is a deletion-lifecycle bucket
|
|
311
|
+
Retention is a deletion-lifecycle bucket, not an access control, with one exception: a scenario draft reads `"scenario"` files, and those the scenario it started from uses, and never a session's. A scenario saved naming a session's file would lose it at that session's next reset, so a file input on a draft, or a file setting edited on one, that names a `"game"` or `"settings"` file is refused. Retention is set at upload time, and who sets it depends on the surface:
|
|
309
312
|
|
|
310
|
-
- **UIs** never choose the retention. The host assigns it from the UI type: uploads from setup
|
|
311
|
-
- **Engine / endpoint `writeBlob`** has no UI to derive from, so it takes an explicit `retention` option (default `"game"`)
|
|
312
|
-
- **CLI uploads** default to `"game"` retention but accept `--settings`
|
|
313
|
+
- **UIs** never choose the retention. The host assigns it from the UI type: uploads from setup are `"settings"`, uploads from the scenario editor are `"scenario"`, and every other UI's uploads are `"game"`. The `uploadBlob` callback takes no retention option
|
|
314
|
+
- **Engine / endpoint `writeBlob`** has no UI to derive from, so it takes an explicit `retention` option (default `"game"`). A [scenario-scoped endpoint](./endpoints.md#scenario-scoped-endpoints) works on a draft, so every file it stores is `"scenario"`, whatever it asks for
|
|
315
|
+
- **CLI uploads** default to `"game"` retention but accept `--settings` for `"settings"` and `--scenario` for `"scenario"`
|
|
313
316
|
|
|
314
|
-
A deleted blob's reference answers 404, as an unknown one does. In the dev server, `sdk init`, the console's Re-initialise and Reconfigure, and selecting a scenario clear
|
|
317
|
+
A deleted blob's reference answers 404, as an unknown one does. In the dev server, `sdk init`, the console's Re-initialise and Reconfigure, and selecting a scenario clear `"game"` and `"settings"` blobs. The automatic re-initialise after a package edit clears `"game"` blobs only. A per-team reset clears nothing, since blobs are not held per team, and neither does resetting the walkthrough. Nothing in the dev server clears `"scenario"` blobs: saving a scenario there writes its files into the package as `asset:` files. On a hosted platform a saved scenario keeps every file it references, and a draft's file no saved scenario uses may be cleared once the draft is saved or abandoned.
|
|
315
318
|
|
|
316
319
|
## Uploading a blob via CLI
|
|
317
320
|
|
|
@@ -324,6 +327,7 @@ pnpm run sdk blob upload <file-path>
|
|
|
324
327
|
**Options:**
|
|
325
328
|
|
|
326
329
|
- `--settings`: store with `'settings'` retention (survives a session reset). Default is `'game'` retention
|
|
330
|
+
- `--scenario`: store as a scenario draft's file, with `'scenario'` retention, for a [setting that holds a file](./settings.md#settings-that-hold-a-file)
|
|
327
331
|
- `--json`: print one JSON document for scripts, with the result as its `data`
|
|
328
332
|
|
|
329
333
|
**Output (default):**
|
|
@@ -1,14 +1,8 @@
|
|
|
1
1
|
# Shaping games
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Shape the game as a whole: how many rounds it runs, how teams form, which languages it speaks, and where participants wait.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
- Where a game is authored
|
|
8
|
-
- How to configure the engine and game UI it runs
|
|
9
|
-
- How to add a setup screen and a scenario editor
|
|
10
|
-
- How to set up multi-language support
|
|
11
|
-
- Where to read about goal-based games with dynamic end conditions
|
|
5
|
+
A package is a game, so all of this lives in the package's own manifest.
|
|
12
6
|
|
|
13
7
|
## Where the game lives
|
|
14
8
|
|