@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.
Files changed (165) hide show
  1. package/README.md +4 -4
  2. package/dist/brands/awkward/brand.json +16 -0
  3. package/dist/brands/awkward/logo-on-light.svg +4 -0
  4. package/dist/brands/serious-gaming/brand.json +42 -0
  5. package/dist/brands/serious-gaming/fonts/OFL-sora.txt +93 -0
  6. package/dist/brands/serious-gaming/fonts/OFL-work-sans.txt +93 -0
  7. package/dist/brands/serious-gaming/fonts/sora-latin-400-normal.woff2 +0 -0
  8. package/dist/brands/serious-gaming/fonts/sora-latin-600-normal.woff2 +0 -0
  9. package/dist/brands/serious-gaming/fonts/sora-latin-700-normal.woff2 +0 -0
  10. package/dist/brands/serious-gaming/fonts/work-sans-latin-wght-normal.woff2 +0 -0
  11. package/dist/brands/serious-gaming/icon.svg +24 -0
  12. package/dist/brands/serious-gaming/loader-on-dark.svg +25 -0
  13. package/dist/brands/serious-gaming/loader-on-light.svg +25 -0
  14. package/dist/brands/serious-gaming/logo-on-dark.svg +38 -0
  15. package/dist/brands/serious-gaming/logo-on-light.svg +42 -0
  16. package/dist/cli.js +20003 -5523
  17. package/dist/client.js +15534 -1134
  18. package/dist/core/save-scenario.d.ts +25 -0
  19. package/dist/core/session-endpoints.d.ts +12 -13
  20. package/dist/core/session-host.d.ts +9 -1
  21. package/dist/core/session-writes.d.ts +2 -2
  22. package/dist/core/session.d.ts +9 -1
  23. package/dist/dev/brand-summary.d.ts +16 -0
  24. package/dist/dev/brands.d.ts +213 -0
  25. package/dist/dev/console/assets/icon-CRaj5uhr.svg +24 -0
  26. package/dist/dev/console/assets/index-q6-lvlN3.css +1 -0
  27. package/dist/dev/console/assets/index-qxHcu9fJ.js +204 -0
  28. package/dist/dev/console/assets/sora-latin-400-normal-CRt88UEn.woff2 +0 -0
  29. package/dist/dev/console/assets/sora-latin-600-normal-Cdg4DaK0.woff2 +0 -0
  30. package/dist/dev/console/assets/sora-latin-700-normal-9waGdLWo.woff2 +0 -0
  31. package/dist/dev/console/assets/work-sans-latin-wght-normal-Bl-S9Xys.woff2 +0 -0
  32. package/dist/dev/console/index.html +3 -1
  33. package/dist/dev/routes.d.ts +9 -0
  34. package/dist/dev/shell.d.ts +14 -0
  35. package/dist/dev/view/batch.d.ts +0 -2
  36. package/dist/docs/ai-agents.md +75 -0
  37. package/dist/docs/api/deck.md +38 -0
  38. package/dist/docs/api/index.md +5 -5
  39. package/dist/docs/api/sdk-commands.md +1 -1
  40. package/dist/docs/api/sdk-e2e.md +1 -0
  41. package/dist/docs/api/sdk-projection.md +1 -0
  42. package/dist/docs/api/sdk-testing.md +52 -1
  43. package/dist/docs/api/sdk-tools-client.md +1 -0
  44. package/dist/docs/api/sdk-ui-testing.md +30 -4
  45. package/dist/docs/api/sdk-ui.md +166 -0
  46. package/dist/docs/api/sdk.md +70 -4
  47. package/dist/docs/changelog.md +64 -6
  48. package/dist/docs/cli-and-dev-server.md +2 -0
  49. package/dist/docs/cli-error-codes.md +65 -59
  50. package/dist/docs/cli-reference.md +84 -45
  51. package/dist/docs/concepts/index.md +74 -6
  52. package/dist/docs/concepts/terminology.md +17 -11
  53. package/dist/docs/getting-started.md +30 -11
  54. package/dist/docs/guides/ai-facilitation.md +5 -1
  55. package/dist/docs/guides/capabilities.md +3 -1
  56. package/dist/docs/guides/designing-a-game.md +85 -0
  57. package/dist/docs/guides/endpoints.md +57 -13
  58. package/dist/docs/guides/engine-testing.md +4 -13
  59. package/dist/docs/guides/engine.md +14 -2
  60. package/dist/docs/guides/file-handling.md +14 -10
  61. package/dist/docs/guides/games.md +2 -8
  62. package/dist/docs/guides/guide.md +64 -3
  63. package/dist/docs/guides/index.md +3 -4
  64. package/dist/docs/guides/internationalization.md +8 -14
  65. package/dist/docs/guides/llm-integration.md +19 -31
  66. package/dist/docs/guides/multi-team-games.md +9 -14
  67. package/dist/docs/guides/patterns.md +0 -6
  68. package/dist/docs/guides/presentation.md +6 -10
  69. package/dist/docs/guides/production-constraints.md +2 -9
  70. package/dist/docs/guides/scenario-editor.md +11 -11
  71. package/dist/docs/guides/scenarios.md +26 -14
  72. package/dist/docs/guides/session.md +29 -35
  73. package/dist/docs/guides/settings.md +28 -2
  74. package/dist/docs/guides/setup.md +2 -7
  75. package/dist/docs/guides/speech-generation.md +8 -17
  76. package/dist/docs/guides/starter-game.md +2 -1
  77. package/dist/docs/guides/testing.md +45 -43
  78. package/dist/docs/guides/theming-and-branding.md +194 -0
  79. package/dist/docs/guides/tick-controller.md +8 -4
  80. package/dist/docs/guides/type-safety.md +8 -6
  81. package/dist/docs/guides/ui.md +41 -62
  82. package/dist/docs/guides/upgrading.md +28 -3
  83. package/dist/docs/guides/validators.md +64 -3
  84. package/dist/docs/guides/waiting-room.md +3 -10
  85. package/dist/docs/index.md +40 -10
  86. package/dist/docs/recipes/adapt-ui-for-observers.md +1 -1
  87. package/dist/docs/recipes/call-endpoint-from-ui.md +2 -0
  88. package/dist/docs/recipes/create-capability.md +1 -1
  89. package/dist/docs/recipes/create-endpoint.md +7 -2
  90. package/dist/docs/recipes/create-engine.md +1 -1
  91. package/dist/docs/recipes/create-guide.md +2 -2
  92. package/dist/docs/recipes/create-hook.md +1 -1
  93. package/dist/docs/recipes/create-session-ui.md +1 -1
  94. package/dist/docs/recipes/create-settings.md +1 -1
  95. package/dist/docs/recipes/create-tick-controller.md +1 -1
  96. package/dist/docs/recipes/create-user-interface.md +1 -1
  97. package/dist/docs/recipes/create-validator.md +1 -1
  98. package/dist/docs/recipes/declare-api-uses.md +2 -2
  99. package/dist/docs/recipes/design-state-for-concurrent-writes.md +2 -2
  100. package/dist/docs/recipes/distribute-package.md +3 -3
  101. package/dist/docs/recipes/e2e-testing.md +11 -9
  102. package/dist/docs/recipes/index.md +6 -2
  103. package/dist/docs/recipes/make-a-guide-follow-the-scenario.md +89 -0
  104. package/dist/docs/recipes/make-an-endpoint-external.md +1 -1
  105. package/dist/docs/recipes/publish-a-package.md +1 -1
  106. package/dist/docs/recipes/remember-a-viewers-choice.md +1 -1
  107. package/dist/docs/recipes/review-a-past-day.md +4 -2
  108. package/dist/docs/recipes/share-assets-across-scenarios.md +3 -3
  109. package/dist/docs/recipes/share-logic-between-engine-and-ui.md +1 -1
  110. package/dist/docs/recipes/test-a-multi-role-game.md +1 -1
  111. package/dist/docs/recipes/test-user-interface.md +13 -2
  112. package/dist/docs/recipes/validate-scenarios.md +91 -0
  113. package/dist/docs/troubleshooting.md +44 -2
  114. package/dist/execution/blob-inputs.d.ts +7 -2
  115. package/dist/execution/config-resolver.d.ts +10 -0
  116. package/dist/execution/endpoint-runner.d.ts +8 -1
  117. package/dist/execution/executor-callbacks.d.ts +7 -0
  118. package/dist/execution/executor.d.ts +11 -0
  119. package/dist/execution/logic-calls.d.ts +8 -1
  120. package/dist/execution/scenario-gates.d.ts +34 -0
  121. package/dist/guide/effective-guide.d.ts +20 -0
  122. package/dist/guide/locale.d.ts +12 -0
  123. package/dist/guide/settings.d.ts +67 -0
  124. package/dist/host/host-channel.d.ts +11 -2
  125. package/dist/host/index.d.ts +7 -1
  126. package/dist/host/protocol.d.ts +49 -5
  127. package/dist/host/theme.d.ts +28 -2
  128. package/dist/host.js +11490 -15
  129. package/dist/runtime/index.d.ts +1 -1
  130. package/dist/runtime/manifest-version.d.ts +17 -0
  131. package/dist/runtime.js +12 -1
  132. package/dist/schema.json +32 -4
  133. package/dist/storage/blob-store.d.ts +3 -2
  134. package/dist/templates/endpoint/logic.test.ts.liquid +19 -1
  135. package/dist/templates/endpoint/logic.ts.liquid +18 -0
  136. package/dist/templates/hook/logic.test.ts.liquid +2 -2
  137. package/dist/templates/package/CLAUDE.md.template +5 -2
  138. package/dist/templates/package/README.md.liquid +2 -0
  139. package/dist/templates/package/claude/rules/workflow-create-endpoint.md +5 -4
  140. package/dist/templates/package/claude/rules/workflow-create-guide.md +1 -0
  141. package/dist/templates/presentation/src/App.tsx.liquid +5 -11
  142. package/dist/templates/session/src/App.test.tsx.liquid +2 -4
  143. package/dist/templates/session/src/theme.ts.liquid +26 -33
  144. package/dist/templates/settings-editor/src/theme.ts.liquid +13 -18
  145. package/dist/templates/starter-game/hooks/assignproducts/logic/logic.test.ts +2 -8
  146. package/dist/templates/starter-game/session/src/App.test.tsx +6 -10
  147. package/dist/templates/starter-game/session/src/theme.ts +26 -33
  148. package/dist/templates/starter-game/ui/src/App.tsx +2 -0
  149. package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +25 -0
  150. package/dist/templates/starter-game/ui/src/HostLogo.tsx +38 -0
  151. package/dist/templates/starter-game/ui/src/theme.ts +26 -33
  152. package/dist/templates/starter-game/validators/capacity/types.ts +2 -0
  153. package/dist/templates/starter-game/waiting_room/src/theme.ts +26 -33
  154. package/dist/templates/ui/src/App.test.tsx.liquid +7 -19
  155. package/dist/templates/ui/src/theme.ts.liquid +26 -33
  156. package/dist/templates/validator/logic.ts.liquid +4 -0
  157. package/dist/templates/waiting-room/src/App.test.tsx.liquid +17 -31
  158. package/dist/templates/waiting-room/src/theme.ts.liquid +26 -33
  159. package/dist/utils/error-codes.d.ts +15 -3
  160. package/dist/validation/ajv.d.ts +9 -5
  161. package/dist/validation/facilitator-guide-validator.d.ts +6 -0
  162. package/dist/validation/file-settings.d.ts +49 -0
  163. package/dist/validation/guide-settings-validator.d.ts +26 -0
  164. package/package.json +6 -5
  165. 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 older pages use another, the entry lists it under **Also called**, so you can recognise it, and says which word to use.
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 older pages. Use participant. A game's own copy can call them whatever suits it.
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
- The person creating a scenario, in the scenario editor. On the platform an author may be an end user rather than a facilitator, so an endpoint the editor calls sees `caller.role` as `'author'`, never `'facilitator'`.
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 simulation 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.
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 older pages. Use tick for the runtime concept. A game's own copy calls its ticks whatever fits the story: the starter game calls them days.
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 older pages. Use completed ticks.
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 older pages. Use game UI, or player surface when the waiting room UI is meant too.
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 older pages. Use session UI, or facilitator surface when setup, the scenario editor and the presentation are meant too.
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 older pages. Use setup.
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 older pages. Use scenario editor.
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 older pages. Use waiting room UI.
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 (reverse-domain, such as `com.example.mygame`), the game's name, and a version. It 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.
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. Take the tour
38
+ ## 2. Play it
30
39
 
31
- [A tour of the starter game](./guides/starter-game.md) walks through every directory and file you now have, says what each one does, and points at the guide that goes deeper. Skim it now, or keep it open beside the next steps.
40
+ A few words come up from here on, each defined in full in the [terminology](./concepts/terminology.md):
32
41
 
33
- ## 3. Play it
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 chrome.
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`, the session-override layer, which wins over the others (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.
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 3, so the browser repaints as they run.
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 `createTestSession`, with no server and no browser. 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.
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'. 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.
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. 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.
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. A team-scoped endpoint receives that team's board and a `team` naming it (`teamId`, `index` and `name`), whoever calls it. A session-scoped one has neither, because there is no single team for them to mean anything against.
46
+ `scope` says what a call acts on, and is one of three:
47
47
 
48
- The surface calling an endpoint has to be able to supply what its scope needs. A session UI, setup screen or scenario editor has no team of its own, so one that calls a team-scoped endpoint fails the build, which tells you to declare the endpoint `"scope": "session"`.
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 scenario editor has no session either, so an endpoint it lists may declare no `reads`, `writes` or `actions`, and the build fails with `EDITOR_ENDPOINT_STATEFUL` if it does. See [Calls from the scenario editor](#calls-from-the-scenario-editor).
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` and `meta.now`, the instant the call started
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 from the scenario editor, which has no session. `role` is `'participant'`, `'observer'`, `'facilitator'`, `'author'` or `'external'`: a session UI and a setup screen report `'facilitator'`, a scenario editor reports `'author'`, and a 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.
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
- ### Calls from the scenario editor
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
- The scenario editor edits a scenario rather than a session, and runs whether or not one exists, so an endpoint it calls is answered with no session, even in a dev server running one beside it:
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
- - `settings`: the settings the endpoint declares, as the scenario being edited resolves them, with the editor's unsaved changes over it. An assistant advising on a draft sees the draft, so declare `settings` rather than passing the values in the request
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) - step-by-step setup for an existing project
475
- - [Testing guide](./testing.md) - unit tests for the engine and React components
476
- - [E2E testing with Playwright](../recipes/e2e-testing.md) - browser-based UI tests
477
- - [Drive a game from the CLI](../cli-simulation-testing.md) - Test through `sdk tick` and `sdk view` against a live session
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. This guide explains how an engine is shaped and why, then covers everything you write in one.
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 `runKind`.
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
- The SDK reads every file, whether it ships in the package or arrives at runtime, through one reference scheme. This guide explains the scheme, then covers uploading files at runtime, displaying them in UIs, and reading their bytes in logic.
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 scenario brief uploaded from a setup screen or scenario editor) |
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 only: it is not an access or visibility control. It is set at upload time, and who sets it depends on the surface:
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 or the scenario editor are `"settings"`, every other UI's uploads are `"game"`. The `uploadBlob` callback takes no retention option
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` to use `"settings"` retention
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 both retentions. The automatic re-initialise after a package edit clears `"game"` blobs only, so the scenario editor's uploads survive an edit. A per-team reset clears nothing, since blobs are not held per team, and neither does resetting the walkthrough.
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
- A package is a game. This guide shows you how to shape the one you have.
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
- ## What you'll learn
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