@seriousgaming/sdk-tools 1.7.0 → 1.9.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 (188) hide show
  1. package/dist/agent/guidance.md +1 -0
  2. package/dist/{cli-SOFCTQAL.js → cli-2BF7KBBJ.js} +15 -15
  3. package/dist/cli-2CSI2UU2.js +110 -0
  4. package/dist/{cli-2BH7FX27.js → cli-2FXZZLCL.js} +1 -1
  5. package/dist/{cli-H3J3ICCQ.js → cli-2I6UN6C3.js} +3 -3
  6. package/dist/{cli-MYJGGLC5.js → cli-2JEICVMA.js} +3 -3
  7. package/dist/{cli-7RYIEKMB.js → cli-2PMLR6WG.js} +15 -15
  8. package/dist/{cli-JRIIAZ33.js → cli-2UOUIVHW.js} +53 -38
  9. package/dist/{cli-OQG3Y4RU.js → cli-2VV5IPSY.js} +15 -15
  10. package/dist/{cli-ZRPWZOCW.js → cli-35K37SYY.js} +20 -16
  11. package/dist/cli-3I6AI4AA.js +36 -0
  12. package/dist/{cli-YSPZZQCP.js → cli-3RMP4HKZ.js} +2 -2
  13. package/dist/{cli-4UWFQNGF.js → cli-3VV2JLHX.js} +1 -1
  14. package/dist/cli-3YGNWZC6.js +30 -0
  15. package/dist/{cli-TPNQLYPC.js → cli-4L7S27XO.js} +1 -1
  16. package/dist/cli-4X3X4HB2.js +16 -0
  17. package/dist/{cli-TJ3PLRHF.js → cli-5BPQ73OM.js} +15 -15
  18. package/dist/{cli-UTM4QU67.js → cli-5PTCQTS6.js} +282 -96
  19. package/dist/{cli-ZTZ5H55T.js → cli-6COAU7JR.js} +17 -17
  20. package/dist/{cli-QVASWX2A.js → cli-6GDPO5VU.js} +2 -2
  21. package/dist/{cli-TFMNNVJ7.js → cli-6KL5B7EC.js} +15 -15
  22. package/dist/{cli-NOQBWJQN.js → cli-6Y4XIVQS.js} +3 -3
  23. package/dist/cli-6ZBQELF2.js +36 -0
  24. package/dist/{cli-MMN4BPO4.js → cli-7CW2BBJG.js} +1 -1
  25. package/dist/{cli-LQ4VSM5R.js → cli-7N7WFRWA.js} +0 -0
  26. package/dist/{cli-JR5AZLLK.js → cli-7OCEVQQN.js} +2 -2
  27. package/dist/{cli-Z5HWENER.js → cli-7RLZIWFP.js} +19 -19
  28. package/dist/{cli-J4DKUUTK.js → cli-7V6GUIIS.js} +2 -2
  29. package/dist/{cli-6ZSMW4HR.js → cli-A3P3PO6Z.js} +15 -15
  30. package/dist/{cli-4VZIJYKU.js → cli-A7PITFRR.js} +2 -2
  31. package/dist/{cli-4XCQUM3E.js → cli-AA5GMEUL.js} +4 -4
  32. package/dist/{cli-N6H6T2E2.js → cli-AEAFLZGY.js} +12 -0
  33. package/dist/{cli-C47GJATR.js → cli-AGYCXRPR.js} +3 -3
  34. package/dist/{cli-T4HWGMY4.js → cli-AJ5CABGJ.js} +15 -15
  35. package/dist/{cli-FZ7QAZZP.js → cli-B5LZEFLU.js} +15 -15
  36. package/dist/{cli-XSVGKI3R.js → cli-BC4KKNLA.js} +1 -1
  37. package/dist/{cli-EJVAQCMQ.js → cli-BF6L37O3.js} +114 -5
  38. package/dist/{cli-ZQ2Y3U7F.js → cli-BNN36WZJ.js} +13 -13
  39. package/dist/{cli-FXY3DKPW.js → cli-BT47H36C.js} +2 -2
  40. package/dist/{cli-XTANOFQR.js → cli-BV7MX7JE.js} +3 -3
  41. package/dist/{cli-PVA52RC2.js → cli-BYXNPBVG.js} +15 -15
  42. package/dist/{cli-MJUYJIEP.js → cli-C45A5VX6.js} +3 -3
  43. package/dist/{cli-HM7CD4VU.js → cli-CKV44U7P.js} +19 -19
  44. package/dist/{cli-LQERHJFE.js → cli-CL3KF5KS.js} +2 -2
  45. package/dist/{cli-SX3ULO5P.js → cli-CPX4YA3P.js} +11 -11
  46. package/dist/{cli-CV4JGVJR.js → cli-CQUSM3SF.js} +19 -19
  47. package/dist/cli-CUZUIYCQ.js +36 -0
  48. package/dist/{cli-YOTGR3NB.js → cli-CVOLMK3Z.js} +1 -1
  49. package/dist/{cli-TFZ53OA2.js → cli-D6AC3ZCX.js} +18 -18
  50. package/dist/{cli-PIO7NWMH.js → cli-DJCQ5XFR.js} +15 -15
  51. package/dist/{cli-4YB3ROVR.js → cli-DMKRP33X.js} +1 -1
  52. package/dist/cli-DNCJURUU.js +36 -0
  53. package/dist/{cli-TIDQ4WUE.js → cli-DXHPYN4N.js} +1 -1
  54. package/dist/{cli-FP32D3T6.js → cli-E77R7ZYB.js} +15 -15
  55. package/dist/{cli-PKQNOGBO.js → cli-EDZF5Q2E.js} +63 -17
  56. package/dist/{cli-IPP5FDCH.js → cli-G54355N5.js} +18 -18
  57. package/dist/{cli-SWZY7L7K.js → cli-G7JTIP5G.js} +6 -6
  58. package/dist/{cli-C5QOJJWX.js → cli-GHIMH6JU.js} +1 -1
  59. package/dist/{cli-LE5ICDAF.js → cli-GHQIATHP.js} +4 -4
  60. package/dist/{cli-ESA6YNPF.js → cli-GZE4V7RC.js} +19 -19
  61. package/dist/{cli-4CHKF4DQ.js → cli-H7T6E7OA.js} +2 -2
  62. package/dist/{cli-TDYKRXUA.js → cli-HCMVZXWK.js} +17 -17
  63. package/dist/{cli-WU43JT4T.js → cli-HJPNNORV.js} +2 -2
  64. package/dist/{cli-MYJGMA6U.js → cli-IC5FOT2J.js} +1 -1
  65. package/dist/{cli-VYR326C6.js → cli-ICLCA6VD.js} +19 -19
  66. package/dist/{cli-CXCL7VRK.js → cli-IJPRZSJ5.js} +20 -20
  67. package/dist/{cli-VL2P354N.js → cli-IVZ7AHUJ.js} +3 -3
  68. package/dist/{cli-B6YHEKIJ.js → cli-J2OTL6JH.js} +5 -5
  69. package/dist/{cli-SOMIB4B4.js → cli-J75EBRAJ.js} +17 -17
  70. package/dist/{cli-WAZD75KE.js → cli-JEMWAIAA.js} +15 -15
  71. package/dist/{cli-TDSQSCX4.js → cli-K6M6YB67.js} +1 -1
  72. package/dist/{cli-WG36UJRK.js → cli-KD2RQS35.js} +18 -18
  73. package/dist/{cli-GTWEGYSU.js → cli-KGJHEDR2.js} +19 -19
  74. package/dist/{cli-EDCAH2TC.js → cli-KINJAQTJ.js} +19 -19
  75. package/dist/cli-KJV3GGBA.js +1973 -0
  76. package/dist/{cli-X7E3637I.js → cli-KO26S2CL.js} +50 -26
  77. package/dist/{cli-MULKSLA4.js → cli-L5ZKQNMI.js} +15 -15
  78. package/dist/{cli-ATI6OLJU.js → cli-LFUKHLHI.js} +17 -17
  79. package/dist/{cli-GHLILDH7.js → cli-LZFUSEJT.js} +13 -13
  80. package/dist/{cli-RZITKPJX.js → cli-MN7X4UG2.js} +1 -1
  81. package/dist/{cli-HCRTYQQS.js → cli-MPWTXNF6.js} +2 -2
  82. package/dist/{cli-HHPMAV4F.js → cli-MSSJLABW.js} +3 -3
  83. package/dist/{cli-DHOWZCXT.js → cli-MTAGL3QE.js} +15 -15
  84. package/dist/{cli-JIZTQVL2.js → cli-MX7GFQ6N.js} +14 -14
  85. package/dist/{cli-7TOLC62D.js → cli-MYBDWJP7.js} +20 -20
  86. package/dist/{cli-VPON5HGB.js → cli-MZM4MW7C.js} +19 -19
  87. package/dist/{cli-UBQCSUDH.js → cli-NTI22MRE.js} +16 -16
  88. package/dist/{cli-ZTWOE3ZT.js → cli-NU4SCD5D.js} +1 -1
  89. package/dist/{cli-DEBCP7UH.js → cli-OK6XWVIN.js} +17 -17
  90. package/dist/{cli-6HB6HTC6.js → cli-OOTGO3KW.js} +47 -47
  91. package/dist/{cli-2DQJACAH.js → cli-OX3254NS.js} +17 -17
  92. package/dist/{cli-GEQUJF4L.js → cli-PJO4BKSV.js} +16 -16
  93. package/dist/{cli-R7RG2VMW.js → cli-QIHVXDMW.js} +15 -15
  94. package/dist/{cli-57V4ARER.js → cli-QK2OD24J.js} +1 -1
  95. package/dist/{cli-OANH3BTQ.js → cli-QRAYIXNE.js} +5 -5
  96. package/dist/{cli-GPAN6XK2.js → cli-QWO3XJR3.js} +4 -4
  97. package/dist/{cli-JRMHSMYT.js → cli-R6YAZP6E.js} +19 -19
  98. package/dist/{cli-FXWWYBYU.js → cli-RHYQYXE2.js} +18 -18
  99. package/dist/{cli-C3OERMIR.js → cli-RL5EBZL7.js} +3 -3
  100. package/dist/{cli-XR2XSWQN.js → cli-S3YIYAXC.js} +12 -12
  101. package/dist/{cli-NPPY557S.js → cli-S7PLSPGE.js} +15 -15
  102. package/dist/{cli-NEOLMC2P.js → cli-SBKTGFY4.js} +17 -17
  103. package/dist/{cli-BOXXMDSX.js → cli-TLRTLTGK.js} +18 -18
  104. package/dist/cli-UKC7KXWU.js +36 -0
  105. package/dist/{cli-FWFRKQNE.js → cli-UR63LFVK.js} +2 -2
  106. package/dist/{cli-ZKG3OPZ6.js → cli-USBJQAYI.js} +13 -13
  107. package/dist/{cli-M7WEAIRF.js → cli-VRGVHSXH.js} +106 -28
  108. package/dist/{cli-IUS2YCD3.js → cli-VTLFQHDO.js} +1 -1
  109. package/dist/{cli-JGFJWZFU.js → cli-W4BHSBAX.js} +3 -3
  110. package/dist/cli-WA2PDQUB.js +36 -0
  111. package/dist/{cli-HYEU3QS6.js → cli-WJO75KP7.js} +3 -3
  112. package/dist/{cli-3PIJLSRQ.js → cli-XA4IL7IM.js} +11 -11
  113. package/dist/{cli-LRQDF3ZO.js → cli-XRVH5WV6.js} +13 -13
  114. package/dist/{cli-SRHBXZCN.js → cli-Y33ULHYO.js} +1 -1
  115. package/dist/{cli-G5DQGZ2E.js → cli-YD4SBAHQ.js} +19 -19
  116. package/dist/{cli-64AA7367.js → cli-YI3WZF3C.js} +11 -11
  117. package/dist/{cli-JPAXKLVT.js → cli-ZHFHOWJI.js} +11 -11
  118. package/dist/{cli-MM3A4SPH.js → cli-ZZSPFLTK.js} +7265 -4467
  119. package/dist/cli.js +52 -52
  120. package/dist/client.js +17518 -16558
  121. package/dist/core/save-scenario.d.ts +1 -0
  122. package/dist/core/session-start-gate.d.ts +25 -0
  123. package/dist/core/session.d.ts +4 -0
  124. package/dist/dev/console/assets/{index-CnXlPeLX.js → index-CVNjiRUh.js} +31 -27
  125. package/dist/dev/console/index.html +1 -1
  126. package/dist/docs/api/deck.md +1 -1
  127. package/dist/docs/api/index.md +1 -1
  128. package/dist/docs/api/sdk-e2e.md +7 -6
  129. package/dist/docs/api/sdk-projection.md +1 -0
  130. package/dist/docs/api/sdk-tools-client.md +3 -1
  131. package/dist/docs/api/sdk-tools-playwright.md +1 -8
  132. package/dist/docs/api/sdk-ui.md +40 -64
  133. package/dist/docs/api/sdk.md +10 -1
  134. package/dist/docs/changelog.md +25 -0
  135. package/dist/docs/cli-error-codes.md +7 -1
  136. package/dist/docs/cli-reference.md +3 -0
  137. package/dist/docs/concepts/index.md +1 -0
  138. package/dist/docs/guides/engine.md +5 -0
  139. package/dist/docs/guides/file-handling.md +4 -1
  140. package/dist/docs/guides/llm-integration.md +3 -2
  141. package/dist/docs/guides/multi-team-games.md +2 -0
  142. package/dist/docs/guides/patterns.md +5 -0
  143. package/dist/docs/guides/session.md +1 -1
  144. package/dist/docs/guides/settings.md +2 -0
  145. package/dist/docs/guides/setup.md +67 -6
  146. package/dist/docs/guides/speech-generation.md +1 -0
  147. package/dist/docs/guides/testing.md +2 -0
  148. package/dist/docs/guides/tick-controller.md +2 -0
  149. package/dist/docs/guides/type-safety.md +2 -1
  150. package/dist/docs/guides/ui-files-and-llms.md +3 -1
  151. package/dist/docs/guides/upgrading.md +4 -0
  152. package/dist/docs/guides/validators.md +27 -4
  153. package/dist/docs/guides/waiting-room.md +2 -0
  154. package/dist/docs/page-index.md +10 -7
  155. package/dist/docs/recipes/call-endpoint-from-ui.md +1 -0
  156. package/dist/docs/recipes/create-scenario-editor.md +2 -1
  157. package/dist/docs/recipes/create-setup.md +19 -10
  158. package/dist/docs/recipes/declare-api-uses.md +1 -0
  159. package/dist/docs/recipes/describe-setup-with-endpoint.md +69 -0
  160. package/dist/docs/recipes/give-setup-a-menu.md +90 -0
  161. package/dist/docs/recipes/index.md +4 -1
  162. package/dist/docs/recipes/share-logic-between-engine-and-ui.md +2 -2
  163. package/dist/docs/recipes/test-user-interface.md +1 -1
  164. package/dist/docs/recipes/validate-scenarios.md +9 -3
  165. package/dist/docs/recipes/write-setup-notes.md +57 -0
  166. package/dist/docs/troubleshooting.md +2 -1
  167. package/dist/execution/executor.d.ts +12 -0
  168. package/dist/execution/scenario-gates.d.ts +40 -0
  169. package/dist/host.js +1082 -467
  170. package/dist/playwright.js +17529 -16569
  171. package/dist/runtime/manifest-version.d.ts +1 -1
  172. package/dist/runtime.js +4 -2
  173. package/dist/setup/setup-notes.d.ts +42 -0
  174. package/dist/templates/package/package.json.liquid +15 -15
  175. package/dist/templates/starter-game/package.json +13 -13
  176. package/dist/utils/error-codes.d.ts +13 -1
  177. package/dist/validation/package-validation.d.ts +1 -1
  178. package/package.json +22 -23
  179. package/dist/cli-57C72YKJ.js +0 -36
  180. package/dist/cli-5G7TZHD3.js +0 -36
  181. package/dist/cli-7MBLH4M3.js +0 -36
  182. package/dist/cli-C6G65H6S.js +0 -256
  183. package/dist/cli-L5IG7MY2.js +0 -36
  184. package/dist/cli-SPGUVL6Z.js +0 -36
  185. package/dist/cli-UY4VDI7W.js +0 -30
  186. package/dist/cli-WM6SQJ6Q.js +0 -16
  187. package/dist/cli-ZBTFLZUL.js +0 -36
  188. package/dist/cli-ZF7IFB54.js +0 -4026
@@ -198,6 +198,7 @@ The engine receives `readAsset` in its callbacks. It accepts an `asset:`, `share
198
198
 
199
199
  ```typescript
200
200
  import { decodeUtf8, getText, type RunFunction } from '@seriousgaming/sdk';
201
+
201
202
  import type { Context, Settings } from './types';
202
203
 
203
204
  export const Run: RunFunction<Context, Settings> = async ({ context, callbacks }) => {
@@ -266,6 +267,7 @@ Declare `"uses": ["extractText", "generateText"]` on the engine, and pass the ge
266
267
 
267
268
  ```typescript
268
269
  import { getText, type RunFunction } from '@seriousgaming/sdk';
270
+
269
271
  import type { Callbacks, Context, Settings } from './types';
270
272
 
271
273
  export const Run: RunFunction<Context, Settings, Callbacks> = async ({
@@ -317,8 +319,9 @@ export const Handle: Handler = async ({ request, callbacks }) => {
317
319
  The endpoint bundle declares `"uses": ["extractText"]`; the UI declares the endpoint in its `endpoints` array and calls it:
318
320
 
319
321
  ```tsx
320
- import { useState } from 'react';
321
322
  import { useUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
323
+ import { useState } from 'react';
324
+
322
325
  import type { Callbacks } from '../types';
323
326
 
324
327
  function DocumentProcessor() {
@@ -164,10 +164,10 @@ All engine functions are async and receive a `callbacks` parameter:
164
164
 
165
165
  ```typescript
166
166
  import { RunFunction } from '@seriousgaming/sdk';
167
- import type { Context, Settings } from './types';
168
-
169
167
  import { getText } from '@seriousgaming/sdk';
170
168
 
169
+ import type { Context, Settings } from './types';
170
+
171
171
  export const Run: RunFunction<Context, Settings> = async ({ context, settings, callbacks }) => {
172
172
  // Simple text generation (quick tier by default)
173
173
  const response = await callbacks.generateText('Your prompt here');
@@ -481,6 +481,7 @@ The endpoint bundle declares `"uses": ["generateText"]` and runs the LLM call se
481
481
  ```typescript
482
482
  // endpoints/chat/logic/logic.ts
483
483
  import { getText } from '@seriousgaming/sdk';
484
+
484
485
  import type { Handler } from '../types';
485
486
 
486
487
  export const Handle: Handler = async ({ request, callbacks }) => {
@@ -279,6 +279,7 @@ import {
279
279
  InitAggregateFunction,
280
280
  RunAggregateFunction,
281
281
  } from '@seriousgaming/sdk';
282
+
282
283
  import type { Context, Settings, SharedContext, TeamContext } from './types';
283
284
 
284
285
  // Per-team init: set this team's own default values
@@ -413,6 +414,7 @@ Each entry in the `teams` array is `{ teamId, index, context }`, and the array i
413
414
 
414
415
  ```typescript
415
416
  import { RunAggregateFunction } from '@seriousgaming/sdk';
417
+
416
418
  import type { Settings, SharedContext, TeamContext } from './types';
417
419
 
418
420
  // Per-team starting capital, indexed by the stable team index
@@ -64,6 +64,7 @@ pnpm run sdk new engine '{
64
64
 
65
65
  ```typescript
66
66
  import { RunFunction } from '@seriousgaming/sdk';
67
+
67
68
  import type { Context, Settings } from './types';
68
69
 
69
70
  export const Run: RunFunction<Context, Settings> = async ({ context, settings }) => {
@@ -166,6 +167,7 @@ pnpm run sdk update engine '{
166
167
 
167
168
  ```typescript
168
169
  import type { StepFunction } from '@seriousgaming/sdk';
170
+
169
171
  import type { Context, Settings } from './types';
170
172
 
171
173
  export const runInventory: StepFunction<Context, Settings> = async ({ context, settings }) => {
@@ -185,6 +187,7 @@ export const runInventory: StepFunction<Context, Settings> = async ({ context, s
185
187
 
186
188
  ```typescript
187
189
  import type { StepFunction } from '@seriousgaming/sdk';
190
+
188
191
  import type { Context, Settings } from './types';
189
192
 
190
193
  export const runSales: StepFunction<Context, Settings> = async ({ context, settings }) => {
@@ -213,6 +216,7 @@ export const runSales: StepFunction<Context, Settings> = async ({ context, setti
213
216
 
214
217
  ```typescript
215
218
  import { RunFunction } from '@seriousgaming/sdk';
219
+
216
220
  import { runInventory } from './inventory';
217
221
  import { runSales } from './sales';
218
222
  import type { Context, Settings } from './types';
@@ -385,6 +389,7 @@ export const runCosts: StepFunction<Context, Settings> = async ({ context, setti
385
389
 
386
390
  ```typescript
387
391
  import { RunFunction } from '@seriousgaming/sdk';
392
+
388
393
  import { runCosts } from './costs';
389
394
  import { runDemand } from './demand';
390
395
  import { runProduction } from './production';
@@ -406,8 +406,8 @@ Read colours from the theme hook below rather than hard-coding them, so your ses
406
406
  Edit `src/theme.ts` to use the session theme hook, and turn it into MUI theme options with `createSurfaceTheme`:
407
407
 
408
408
  ```typescript
409
- import { createSurfaceTheme, useSessionUserInterfaceTheme } from '@seriousgaming/sdk/ui';
410
409
  import { createTheme } from '@mui/material/styles';
410
+ import { createSurfaceTheme, useSessionUserInterfaceTheme } from '@seriousgaming/sdk/ui';
411
411
  import { useMemo } from 'react';
412
412
 
413
413
  export function useAppTheme() {
@@ -232,6 +232,7 @@ The engine, hooks, validators, the tick controller and endpoints receive `settin
232
232
 
233
233
  ```typescript
234
234
  import type { RunFunction } from '@seriousgaming/sdk';
235
+
235
236
  import type { Context, Settings } from './types';
236
237
 
237
238
  export const Run: RunFunction<Context, Settings> = async ({ context, settings }) => {
@@ -253,6 +254,7 @@ A game UI, session UI and waiting room UI read `settings` from their data hook:
253
254
 
254
255
  ```tsx
255
256
  import { useUserInterfaceData } from '@seriousgaming/sdk/ui';
257
+
256
258
  import type { Context, Settings } from '../types';
257
259
 
258
260
  function PricePanel() {
@@ -4,7 +4,7 @@ The `setup` slot holds the small form a facilitator fills in when they create a
4
4
 
5
5
  This guide covers creating one, building its form, and how it behaves in the dev server.
6
6
 
7
- **Keywords:** setup screen, setup form, session creation, configures, per-session settings, number of rounds, requestPlay, start play, facilitator form
7
+ **Keywords:** setup screen, setup form, session creation, configures, per-session settings, setup menu, quick config, number of rounds, requestPlay, start play, facilitator form, AI assistant
8
8
 
9
9
  ## What setup is
10
10
 
@@ -27,14 +27,14 @@ Keep it small. Setup is part of somebody creating a session on the day, often in
27
27
  ```bash
28
28
  pnpm run sdk new setup '{
29
29
  "definition": {
30
- "configures": ["engine"]
30
+ "configures": ["game", "setup"]
31
31
  },
32
32
  "rootDirectory": ".",
33
33
  "ui": { "entrypoint": "index.html" }
34
34
  }'
35
35
  ```
36
36
 
37
- `configures` names the [settings resources](./settings.md) the screen edits, by identifier: here the one at `settings/engine/`. The screen receives the resolved values of exactly those settings and can change nothing else: an `updateSettings` call naming any other settings resource is refused, and none of it is applied. The build fails if you name a settings resource the package does not declare.
37
+ `configures` names the [settings resources](./settings.md) the screen edits, by identifier: here the built-in `game` settings, for the number of rounds, and a menu at `settings/setup/` (see [Give setup a menu of its own](#give-setup-a-menu-of-its-own)). The screen receives the resolved values of exactly those settings and can change nothing else: an `updateSettings` call naming any other settings resource is refused, and none of it is applied. The build fails if you name a settings resource the package does not declare.
38
38
 
39
39
  ```
40
40
  setup/
@@ -51,6 +51,43 @@ setup/
51
51
 
52
52
  `src/main.tsx` wraps the app in `SettingsEditorWrapper`, the wrapper both settings editor slots share.
53
53
 
54
+ ## Give setup a menu of its own
55
+
56
+ Whatever setup configures can be changed for a session, and not only on your screen: an AI assistant setting a session up for a facilitator can change every value in every settings resource setup configures. A settings resource is configured whole, so a setup that configures `engine` to offer two choices hands over every engine setting, whatever the screen shows.
57
+
58
+ So put the choices your setup offers in a settings resource of their own, a menu, and configure that alone, beside `game` if setup sets the number of rounds:
59
+
60
+ ```json
61
+ {
62
+ "definition": {
63
+ "settingsSchema": {
64
+ "type": "object",
65
+ "properties": {
66
+ "Market": {
67
+ "title": "Market",
68
+ "description": "How forgiving the market is, compared with the scenario. 'standard' plays the scenario as written",
69
+ "type": "string",
70
+ "enum": ["gentler", "standard", "tougher"],
71
+ "default": "standard"
72
+ }
73
+ },
74
+ "additionalProperties": false
75
+ }
76
+ }
77
+ }
78
+ ```
79
+
80
+ - **Make each choice finite**: an `enum`, a `boolean`, or an array of an `enum`. The schema then refuses anything off the menu, whoever sends it, and an assistant can read every choice there is
81
+ - **Give each a `title` and a `description`.** An assistant shows them to the facilitator when it confirms a choice
82
+ - **Let your logic decide what a choice means.** Declare the menu in the `settings` of the engine and of any other resource it affects, and work out the values there. A choice relative to the scenario, such as 'tougher than the scenario', never clashes with what a scenario sets
83
+ - **A scenario sets the menu's defaults** by setting the menu resource, like any other setting. Add the menu to the scenario editor's `configures` to let an author choose them
84
+ - **Keep what the menu offers per scenario in your other settings.** When a choice is only available in some scenarios, such as an aid a scenario may or may not allow, the list of what is allowed belongs in a settings resource setup does not configure. Say where it is in the menu setting's `description` and in your [notes for assistants](#notes-for-assistants)
85
+ - **Refuse a choice that is wrong for the scenario** in a [Scenario gate](./validators.md#when-it-runs), with `session-validation` in `requires`: it runs as the session starts, on what setup changed
86
+
87
+ Everything else stays in the game's other settings, for scenario authors. A facilitator who wants something the menu does not offer needs a scenario that does it.
88
+
89
+ `examples/factory` does this: its setup configures `game` and a `setup` menu with one choice, `Market`; the engine applies the choice to the scenario's demand, and its `Scenario` gate refuses a market that would leave no team selling anything. See [Give setup a menu](../recipes/give-setup-a-menu.md) to move an existing setup to one.
90
+
54
91
  ## Building the form
55
92
 
56
93
  `useSettingsEditor()` returns three things:
@@ -62,8 +99,9 @@ setup/
62
99
  Spreading `settings` into an update is safe: an unchanged value is never stored as a facilitator override, so a scenario chosen later still applies to it.
63
100
 
64
101
  ```tsx
65
- import { useSettingsEditor } from '@seriousgaming/sdk/ui';
66
102
  import { Stack, TextField } from '@mui/material';
103
+ import { useSettingsEditor } from '@seriousgaming/sdk/ui';
104
+
67
105
  import type { Settings } from '../types';
68
106
 
69
107
  function SetupForm() {
@@ -116,8 +154,8 @@ A write is also refused, as `denied` and with none of it applied, when it change
116
154
  `useSettingsEditorCallbacks()` gives the screen `requestPlay`, which leaves the configuration step exactly as the host's Play control does:
117
155
 
118
156
  ```tsx
119
- import { useSettingsEditorCallbacks } from '@seriousgaming/sdk/ui';
120
157
  import { Button } from '@mui/material';
158
+ import { useSettingsEditorCallbacks } from '@seriousgaming/sdk/ui';
121
159
 
122
160
  function StartButton() {
123
161
  const { requestPlay } = useSettingsEditorCallbacks();
@@ -150,6 +188,26 @@ Setup is embedded in the host's page, not a page of its own:
150
188
 
151
189
  The [session UI guide](./session.md#rendering-inside-the-host) covers the same ground in more detail.
152
190
 
191
+ ## Notes for assistants
192
+
193
+ An AI assistant can set a session up for a facilitator, choosing from what your setup screen `configures`. From the schemas alone it cannot tell which choices matter most, or what 'make it a bit harder' means in your game. Tell it in setup notes: Markdown at `setup/notes/<locale>.md`, one file per locale.
194
+
195
+ ```markdown
196
+ ## What requests mean
197
+
198
+ - **'Harder'**: set `setup.Market` to `tougher`
199
+ - **'Shorter'**: set `game.maxTicks` to 6
200
+ - **Anything else**, such as cheaper materials: setup cannot do it. Suggest a scenario that does
201
+ ```
202
+
203
+ - **Describe your menu, and nothing beyond it.** Name only settings your setup screen configures, with values their schemas allow. A request the menu cannot meet needs a scenario, so say which, rather than naming a setting setup cannot change
204
+ - **Name each setting as a setting path in a code span**, such as `setup.Market`: an assistant writes it back as it stands. The build checks every code span that starts with one of your settings identifiers, failing on one that names no setting (`SETTINGS_UNKNOWN`) and warning on one your setup screen does not configure (`SETUP_NOTES_UNCONFIGURED`)
205
+ - **Say what a schema cannot**: which choices are worth asking about, what common requests mean as choices, and, where what the menu offers depends on the scenario, which setting says what it offers. A host may show an assistant your other settings, read-only, for exactly this
206
+ - **They are for assistants.** Your setup screen is what a facilitator sees, and a host need not show the notes to anyone. They grant nothing: an assistant is held to `configures` and to your game's [Scenario gate](./validators.md#when-it-runs) like anyone else
207
+ - **Locales fall back** from the assistant's locale to `en`, then your first supported locale
208
+
209
+ The build ships them as written. In the dev server, **Notes for assistants** on the configuration step shows them exactly as an assistant receives them. `examples/factory` has a set; see [Write setup notes for assistants](../recipes/write-setup-notes.md), and [Describe a setup with an endpoint](../recipes/describe-setup-with-endpoint.md) to let an assistant read a setup back in your game's words.
210
+
153
211
  ## Dev server behaviour
154
212
 
155
213
  `pnpm run sdk dev` opens a game with a setup slot at its configuration step, on `/setup`. Fill in the form and press Play (or your own control). Once play starts, `/setup` shows that the step has closed; **Reconfigure** in the dev drawer returns the session to it and every team to tick 0. Overrides persist in `.seriousgaming-sdk/` between runs, and `pnpm run sdk configure` sets them from the command line.
@@ -158,7 +216,7 @@ The [session UI guide](./session.md#rendering-inside-the-host) covers the same g
158
216
 
159
217
  ```bash
160
218
  pnpm run sdk update setup '{
161
- "definition": { "configures": ["engine", "ui"] },
219
+ "definition": { "configures": ["game", "setup"] },
162
220
  "rootDirectory": ".",
163
221
  "ui": { "entrypoint": "index.html" }
164
222
  }'
@@ -173,6 +231,7 @@ Deleting the slot removes the configuration step: the game then starts at tick 0
173
231
 
174
232
  ```tsx
175
233
  import { renderSettingsEditor } from '@seriousgaming/sdk/ui/testing';
234
+
176
235
  import { defaultSettings } from '../defaults';
177
236
 
178
237
  renderSettingsEditor(<SetupForm />, {
@@ -188,3 +247,5 @@ See [Test a user interface](../recipes/test-user-interface.md).
188
247
  - [Settings](./settings.md): declaring, reading, and overriding settings
189
248
  - [Scenarios](./scenarios.md)
190
249
  - [Create a setup screen](../recipes/create-setup.md)
250
+ - [Give setup a menu](../recipes/give-setup-a-menu.md)
251
+ - [Write setup notes for assistants](../recipes/write-setup-notes.md)
@@ -123,6 +123,7 @@ For ElevenLabs, the defaults are `eleven_flash_v2_5` (quick), `eleven_turbo_v2_5
123
123
 
124
124
  ```typescript
125
125
  import type { RunFunction } from '@seriousgaming/sdk';
126
+
126
127
  import type { Context, Settings, Callbacks } from '../types';
127
128
 
128
129
  export const Run: RunFunction<Context, Settings, Callbacks> = async ({
@@ -47,6 +47,7 @@ Every capability variable must declare a `default` for this to work. The build s
47
47
  // engine/logic.test.ts
48
48
  import { logicArgs } from '@seriousgaming/sdk/testing';
49
49
  import { describe, it, expect } from 'vitest';
50
+
50
51
  import { defaultSettings, defaultContext } from './defaults';
51
52
  import { Run } from './logic';
52
53
  import type { Context, Settings } from './types';
@@ -122,6 +123,7 @@ describe('Warehouse Init', () => {
122
123
 
123
124
  ```typescript
124
125
  import { logicArgs } from '@seriousgaming/sdk/testing';
126
+
125
127
  import { defaultSettings, defaultSharedContext, defaultTeamContext } from './defaults';
126
128
  import { RunAggregate } from './logic';
127
129
 
@@ -78,6 +78,7 @@ The generated `tick_controller/logic.ts` exports a `GetTickController` function.
78
78
 
79
79
  ```typescript
80
80
  import { GetTickControllerFunction, intervalTick } from '@seriousgaming/sdk';
81
+
81
82
  import type { Context, Settings } from './types';
82
83
 
83
84
  export const GetTickController: GetTickControllerFunction<Context, Settings> = async ({
@@ -444,6 +445,7 @@ The SDK provides helpers that compute the next occurrence of a daily or weekly t
444
445
 
445
446
  ```typescript
446
447
  import { GetTickControllerFunction, nextDailyAt, scheduledTick } from '@seriousgaming/sdk';
448
+
447
449
  import type { Context, Settings } from './types';
448
450
 
449
451
  export const GetTickController: GetTickControllerFunction<Context, Settings> = async ({
@@ -45,9 +45,10 @@ export const Run: RunFunction<any, any> = async ({ context, settings, callbacks
45
45
  ### ✅ CORRECT: using generated types
46
46
 
47
47
  ```typescript
48
+ import { RunFunction } from '@seriousgaming/sdk';
49
+
48
50
  // logic.ts
49
51
  import type { Context, Settings } from './types';
50
- import { RunFunction } from '@seriousgaming/sdk';
51
52
 
52
53
  // ✅ CORRECT
53
54
  export const Run: RunFunction<Context, Settings> = async ({ context, settings, callbacks }) => {
@@ -149,6 +149,7 @@ The endpoint bundle declares `"uses": ["generateText"]` and runs the LLM call:
149
149
  ```typescript
150
150
  // endpoints/chat/logic/logic.ts
151
151
  import { getText } from '@seriousgaming/sdk';
152
+
152
153
  import type { Handler } from '../types';
153
154
 
154
155
  export const Handle: Handler = async ({ request, callbacks }) => {
@@ -178,8 +179,9 @@ The UI bundle declares the endpoint in its `endpoints` array. A UI bundle has no
178
179
  Access `callbacks.endpoints` with the `useUserInterfaceCallbacks` hook. Persist the conversation in a capability so it survives across ticks:
179
180
 
180
181
  ```tsx
181
- import { useState } from 'react';
182
182
  import { useUserInterfaceCallbacks, useUserInterfaceData } from '@seriousgaming/sdk/ui';
183
+ import { useState } from 'react';
184
+
183
185
  import type { Context, Settings } from '../types';
184
186
  import type { Callbacks } from '../types';
185
187
 
@@ -152,6 +152,7 @@ grep -rn "configuration" testing scripts
152
152
 
153
153
  ```typescript
154
154
  import type { RunFunction } from '@seriousgaming/sdk';
155
+
155
156
  import type { Context, Settings } from './types';
156
157
 
157
158
  export const Run: RunFunction<Context, Settings> = async ({ context, settings }) => {
@@ -276,6 +277,7 @@ An engine that splits `Init` or `Run` into several functions typed as `RunFuncti
276
277
 
277
278
  ```typescript
278
279
  import type { RunFunction, StepFunction } from '@seriousgaming/sdk';
280
+
279
281
  import type { Context, Settings } from './types';
280
282
 
281
283
  export const runSales: StepFunction<Context, Settings> = async ({ context }) => ({
@@ -295,6 +297,7 @@ An aggregate engine split into steps works the same way. There is no step type f
295
297
 
296
298
  ```typescript
297
299
  import type { RunAggregateFunction } from '@seriousgaming/sdk';
300
+
298
301
  import type { Settings, SharedContext, TeamContext } from './types';
299
302
 
300
303
  type Board = { shared: SharedContext; teams: TeamContext[] };
@@ -550,6 +553,7 @@ Every logic call now receives `meta.now` (the operation's time in milliseconds)
550
553
 
551
554
  ```typescript
552
555
  import { logicArgs } from '@seriousgaming/sdk/testing';
556
+
553
557
  import { defaultSettings } from '../../engine/defaults';
554
558
 
555
559
  const result = await Run(logicArgs.run({ context, settings: defaultSettings }));
@@ -110,7 +110,8 @@ Each validator is told who submitted the mutation, as `actor`:
110
110
 
111
111
  ```typescript
112
112
  type ValidatorActor =
113
- { role: 'participant'; participant: Participant } | { role: 'observer'; teamId: string };
113
+ | { role: 'participant'; participant: Participant }
114
+ | { role: 'observer'; teamId: string };
114
115
  ```
115
116
 
116
117
  It is a union rather than an optional participant, because these are two callers rather than an identity and the absence of one. `participant` is unreachable until you have narrowed on `role`, so a validator cannot read an identity it has not first decided it has.
@@ -288,8 +289,30 @@ const judge = (ui: Partial<Settings['ui']>) =>
288
289
  ### When it runs
289
290
 
290
291
  - **`sdk build`** runs it on every scenario in `scenarios/`, and on the defaults alone when no scenario is the default, since a session can then run on no scenario. A problem fails the build (`SCENARIO_REFUSED`), pointing at the setting in the scenario's file
291
- - **Saving a scenario** runs it, from the scenario editor, a form the platform generates, or an agent writing settings, and a problem refuses the save with every problem listed
292
- - **Never when a session starts.** By then its scenario has passed
292
+ - **Saving a scenario** runs it, from the scenario editor, a form the platform generates, or an agent writing settings, and a problem refuses the save with every problem listed. A gate that runs out of time is run once more first, since a busy host can push a sound gate over its time limit
293
+ - **As a session starts**, when the game lists `session-validation` in `requires`. It judges the session's own settings, what setup changed over the scenario, and a session it finds an error with does not start: the facilitator, or an agent setting the session up, sees every problem and changes the setting. A session nobody changed, on a scenario the build checked, is not judged again. Without `session-validation`, a session is never refused on the gate
294
+
295
+ ```json
296
+ "requires": ["scenario-validation", "session-validation"]
297
+ ```
298
+
299
+ In the dev server, Play shows the refusal or the warnings, `pnpm run sdk play` prints the warnings, and `pnpm run sdk configure` runs the gate before it saves anything, so a refused change is never written and a running session is left as it was.
300
+
301
+ A gate that throws also stops a session starting, and is reported as a fault in the game rather than in its settings, since changing a setting will not clear it. One that runs out of time is run once more first, since a busy host can push a sound gate over its time limit, and refuses only if it overruns again. Nothing overrides it, so test your gate against the settings your setup screen can produce. The build notes each settings resource your setup UI changes that no `Scenario` gate declares in its `settings` (`SETTINGS_UNGATED`): nothing checks those changes before play.
302
+
303
+ ### Errors and warnings
304
+
305
+ A problem is an error unless you say otherwise. Give it `level: 'warning'` for something unusual that may well be meant, such as a story week outside the rounds the game plays. A warning is reported wherever an error is, by the build (`SCENARIO_WARNING`), with a saved scenario and with a session start, and never refuses any of them:
306
+
307
+ ```typescript
308
+ problems.push({
309
+ path: settingPath('engine', 'CostPerUnit'),
310
+ level: 'warning',
311
+ message: 'Making a unit costs nothing, so unsold stock never costs a team anything',
312
+ });
313
+ ```
314
+
315
+ Keep errors for what breaks play, such as a document that never arrives. With `session-validation`, an error stops a facilitator starting their session, so a borderline case is better as a warning. `examples/factory`'s `scenariocheck` validator warns on a unit cost of £0.
293
316
 
294
317
  ### It judges values, not where they came from
295
318
 
@@ -305,7 +328,7 @@ The gate is the last word, and it runs on save. A [scenario editor](./scenario-e
305
328
 
306
329
  The gate reads no game state and receives no `actor` or `meta`: there is no session or participant behind a scenario. Its only callbacks are the file reads above. It ignores the validator's `reads`, so a validator that only exports `Scenario` declares none.
307
330
 
308
- The gate runs when a scenario is saved, not each time one is used, so a scenario a facilitator saved before you added or tightened a rule has never met it. Bump `scenarioFormat` in `seriousgaming.sdk.json` when you do, and a runtime stops using those older scenarios. See [Scenario format: when to bump it](./scenarios.md#scenario-format-when-to-bump-it).
331
+ Without `session-validation`, the gate runs when a scenario is saved, not each time one is used, so a scenario a facilitator saved before you added or tightened a rule has never met it. Bump `scenarioFormat` in `seriousgaming.sdk.json` when you do, and a runtime stops using those older scenarios. See [Scenario format: when to bump it](./scenarios.md#scenario-format-when-to-bump-it).
309
332
 
310
333
  ## Settings
311
334
 
@@ -81,6 +81,7 @@ Same as any game UI. Declare the capability in `reads`, regenerate, and read it
81
81
 
82
82
  ```typescript
83
83
  import { useUserInterfaceData } from '@seriousgaming/sdk/ui';
84
+
84
85
  import type { Context, Settings } from '../types';
85
86
 
86
87
  function App() {
@@ -182,6 +183,7 @@ Opening the room pauses nothing. The decision belongs to the game, because only
182
183
 
183
184
  ```typescript
184
185
  import type { GetTickControllerFunction } from '@seriousgaming/sdk';
186
+
185
187
  import type { Context, Settings } from '../types';
186
188
 
187
189
  export const GetTickController: GetTickControllerFunction<Context, Settings> = async ({
@@ -25,8 +25,8 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
25
25
  - [`changelog-0.x.md`](changelog-0.x.md): Every release before 1.0, from 0.0.1 to 0.6.0, kept as history.
26
26
  - [`changelog.md`](changelog.md): All notable changes to the Serious Gaming SDK are recorded here.
27
27
  - [`cli-and-dev-server.md`](cli-and-dev-server.md), about 15k characters: The dev server runs your game on your own machine, with every screen in the browser, and the CLI plays and inspects the same session from the terminal.
28
- - [`cli-error-codes.md`](cli-error-codes.md), about 31k characters: Every code a failed `seriousgaming-sdk` command can report.
29
- - [`cli-reference.md`](cli-reference.md), about 162k characters: Every `seriousgaming-sdk` command and flag, in one place.
28
+ - [`cli-error-codes.md`](cli-error-codes.md), about 32k characters: Every code a failed `seriousgaming-sdk` command can report.
29
+ - [`cli-reference.md`](cli-reference.md), about 163k characters: Every `seriousgaming-sdk` command and flag, in one place.
30
30
  - [`cli-simulation-testing.md`](cli-simulation-testing.md), about 11k characters: Play a game from the terminal: configure it, start a session, make decisions, advance ticks, and read the state back as JSON.
31
31
  - [`environment-variables.md`](environment-variables.md), about 10k characters: A single reference for every environment variable the dev server and CLI read.
32
32
  - [`getting-started.md`](getting-started.md), about 11k characters: Scaffold the starter game, play it in the dev server, change one thing, and see the change.
@@ -64,7 +64,7 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
64
64
  - [`guides/session-hooks.md`](guides/session-hooks.md), about 15k characters: Every hook a session UI reads its data and callbacks from, and the messages the host sends it.
65
65
  - [`guides/session.md`](guides/session.md), about 23k characters: The session UI is the facilitator's view of the whole room: every team's position side by side, with the controls to run the session.
66
66
  - [`guides/settings.md`](guides/settings.md), about 34k characters: Settings are a game's read-only parameters: a price, a difficulty, a round length, a menu, an answer key.
67
- - [`guides/setup.md`](guides/setup.md), about 9k characters: The `setup` slot holds the small form a facilitator fills in when they create a session.
67
+ - [`guides/setup.md`](guides/setup.md), about 15k characters: The `setup` slot holds the small form a facilitator fills in when they create a session.
68
68
  - [`guides/speech-generation.md`](guides/speech-generation.md), about 10k characters: Give characters and briefings a voice: generate speech from server-side logic and play it in any UI.
69
69
  - [`guides/starter-game.md`](guides/starter-game.md), about 18k characters: `new package` hands you Lemonade Stand, a complete game rather than an empty shell.
70
70
  - [`guides/testing.md`](guides/testing.md), about 34k characters: Test your engine's logic and your user interfaces, so a broken rule or a broken screen fails on your machine rather than in front of a room.
@@ -77,7 +77,7 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
77
77
  - [`guides/ui-ticks.md`](guides/ui-ticks.md), about 15k characters: How a game UI ends a round and shows the time left: requesting a tick, awaiting a write or tick and handling a `MutationError`, and driving a countdown from the tick timer.
78
78
  - [`guides/ui.md`](guides/ui.md), about 17k characters: The game UI is what each participant sees and plays: where they read the situation, make decisions, and see what those decisions caused.
79
79
  - [`guides/upgrading.md`](guides/upgrading.md), about 68k characters: This guide takes a game package on 0.6 to 1.0, in 13 steps.
80
- - [`guides/validators.md`](guides/validators.md), about 23k characters: A validator is a read-only gate on what a participant does: a context write before it is applied, and a request for the next tick before it runs.
80
+ - [`guides/validators.md`](guides/validators.md), about 25k characters: A validator is a read-only gate on what a participant does: a context write before it is applied, and a request for the next tick before it runs.
81
81
  - [`guides/waiting-room.md`](guides/waiting-room.md), about 14k characters: The waiting room is the holding screen participants see while a session is parked, and you can replace the host's stock panel with your own.
82
82
 
83
83
  ## Recipes
@@ -99,17 +99,19 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
99
99
  - [`recipes/create-scenario.md`](recipes/create-scenario.md), about 3k characters: Bundle a game flavour with settings overrides and static assets.
100
100
  - [`recipes/create-session-ui.md`](recipes/create-session-ui.md), about 5k characters: Build the facilitator's screen: every team's state side by side, with controls to change values and run the session.
101
101
  - [`recipes/create-settings.md`](recipes/create-settings.md), about 4k characters: Give a game a read-only parameter, such as a price, a difficulty, or an answer key, that its logic and screens read and that scenarios and facilitators can change before play starts.
102
- - [`recipes/create-setup.md`](recipes/create-setup.md), about 3k characters: Give facilitators a short form at session creation that sets a few of your game's settings for that session only.
102
+ - [`recipes/create-setup.md`](recipes/create-setup.md), about 4k characters: Give facilitators a short form at session creation that sets a few of your game's settings for that session only.
103
103
  - [`recipes/create-tick-controller.md`](recipes/create-tick-controller.md), about 3k characters: Make ticks fire automatically, on an interval or a schedule your game's logic decides.
104
104
  - [`recipes/create-user-interface.md`](recipes/create-user-interface.md), about 4k characters: Build the game UI: the screen each participant sees, showing the game's state and taking their decisions.
105
105
  - [`recipes/create-validator.md`](recipes/create-validator.md), about 4k characters: Reject a participant's write that breaks the game's rules, before the runtime applies it.
106
106
  - [`recipes/create-waiting-room-ui.md`](recipes/create-waiting-room-ui.md), about 5k characters: Replace the host's stock holding screen with your own, so participants see your branding and your words while the facilitator has the waiting room open.
107
107
  - [`recipes/declare-api-uses.md`](recipes/declare-api-uses.md), about 4k characters: A logic-bearing resource (engine, hook, tick controller, endpoint) must declare the runtime callbacks it intends to call.
108
+ - [`recipes/describe-setup-with-endpoint.md`](recipes/describe-setup-with-endpoint.md), about 3k characters: Let an assistant, or your own setup screen, ask your game to describe a session's settings in the game's own words before it starts.
108
109
  - [`recipes/design-state-for-concurrent-writes.md`](recipes/design-state-for-concurrent-writes.md), about 6k characters: Shape capabilities and `setData` calls so that several participants writing at once never overwrite each other.
109
110
  - [`recipes/distribute-package.md`](recipes/distribute-package.md), about 3k characters: Wrap a built `dist/` directory into a single zip archive that a production runtime can ingest as an upload.
110
111
  - [`recipes/e2e-testing.md`](recipes/e2e-testing.md), about 6k characters: Test your game's screens in a real browser against an isolated dev server.
111
112
  - [`recipes/end-game-on-condition.md`](recipes/end-game-on-condition.md), about 5k characters: Stop a game automatically when a goal is reached, rather than after a fixed number of ticks.
112
113
  - [`recipes/fix-duplicate-packages.md`](recipes/fix-duplicate-packages.md), about 4k characters: Resolve 'Invalid hook call' and similar errors caused by multiple copies of the same package being loaded by the dev server.
114
+ - [`recipes/give-setup-a-menu.md`](recipes/give-setup-a-menu.md), about 5k characters: Move the choices your setup screen offers into a settings resource of their own, so a facilitator, or an AI assistant setting a session up for one, can change exactly those and nothing else.
113
115
  - [`recipes/make-a-guide-follow-the-scenario.md`](recipes/make-a-guide-follow-the-scenario.md), about 5k characters: Show the session's settings in the facilitator guide, and show content only to the scenarios that need it.
114
116
  - [`recipes/make-an-endpoint-external.md`](recipes/make-an-endpoint-external.md), about 5k characters: Publish one of your endpoints to callers outside the game, such as a facilitator's AI agent or a platform API, so it can be invoked by asking or by another system rather than by clicking.
115
117
  - [`recipes/negotiate-across-teams.md`](recipes/negotiate-across-teams.md), about 8k characters: Build a game where two teams propose, agree, and settle an exchange with each other, using a team-readable ledger and authoritative settlement at tick time.
@@ -129,7 +131,8 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
129
131
  - [`recipes/upload-and-display-files.md`](recipes/upload-and-display-files.md), about 6k characters: Let a participant attach a file (a PDF, CSV, or image) in the game UI, show it back, and optionally summarise it in the engine.
130
132
  - [`recipes/use-request-play.md`](recipes/use-request-play.md), about 2k characters: Leave the configuration step and start the game from within your setup screen, so operators can move to play from your own control as well as from the host's Play button.
131
133
  - [`recipes/use-request-tick.md`](recipes/use-request-tick.md), about 3k characters: Trigger the next game tick from within your user interface, so participants submit their decisions via your own button.
132
- - [`recipes/validate-scenarios.md`](recipes/validate-scenarios.md), about 4k characters: Refuse a scenario whose settings break your game's rules, at build and when one is saved, never when a session starts.
134
+ - [`recipes/validate-scenarios.md`](recipes/validate-scenarios.md), about 5k characters: Refuse a scenario whose settings break your game's rules, at build and when one is saved, and optionally a session whose setup breaks them.
135
+ - [`recipes/write-setup-notes.md`](recipes/write-setup-notes.md), about 4k characters: Tell an AI assistant setting a session up which of your setup's choices matter, and what a request such as 'make it a bit harder' means in your game.
133
136
 
134
137
  ## API reference
135
138
 
@@ -143,4 +146,4 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
143
146
  - [`api/sdk-tools-playwright.md`](api/sdk-tools-playwright.md), about 3k characters: Playwright for a game's browser tests: a dev server for each worker.
144
147
  - [`api/sdk-ui-testing.md`](api/sdk-ui-testing.md), about 8k characters: Every export of `@seriousgaming/sdk/ui/testing`, with the declaration it is published with.
145
148
  - [`api/sdk-ui.md`](api/sdk-ui.md), about 36k characters: Every export of `@seriousgaming/sdk/ui`, with the declaration it is published with.
146
- - [`api/sdk.md`](api/sdk.md), about 58k characters: Every export of `@seriousgaming/sdk`, with the declaration it is published with.
149
+ - [`api/sdk.md`](api/sdk.md), about 59k characters: Every export of `@seriousgaming/sdk`, with the declaration it is published with.
@@ -27,6 +27,7 @@ Call a server-side endpoint from any of your game's screens and handle its respo
27
27
 
28
28
  ```tsx
29
29
  import { useUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
30
+
30
31
  import type { Callbacks } from '../types';
31
32
 
32
33
  function ReportButton({ reportText }: { reportText: string }) {
@@ -44,8 +44,9 @@ This creates `scenario_editor/` with `scenario_editor.sdk.json`, `index.html`, `
44
44
  Open `scenario_editor/src/App.tsx`. It uses the same hooks as setup:
45
45
 
46
46
  ```tsx
47
- import { useSettingsEditor } from '@seriousgaming/sdk/ui';
48
47
  import { Stack, TextField } from '@mui/material';
48
+ import { useSettingsEditor } from '@seriousgaming/sdk/ui';
49
+
49
50
  import type { Settings } from '../types';
50
51
 
51
52
  function App() {
@@ -6,11 +6,11 @@ Give facilitators a short form at session creation that sets a few of your game'
6
6
 
7
7
  ## What you'll build
8
8
 
9
- A setup screen at `setup/` that edits the `engine` settings and starts play from its own button. A game with a `setup` slot opens at the configuration step: nothing runs until the facilitator presses Play. See the [setup guide](../guides/setup.md) for the full behaviour.
9
+ A setup screen at `setup/` that offers a menu of choices, held in a settings resource of its own, and starts play from its own button. A game with a `setup` slot opens at the configuration step: nothing runs until the facilitator presses Play. See the [setup guide](../guides/setup.md) for the full behaviour.
10
10
 
11
11
  ## Prerequisites
12
12
 
13
- - A settings resource for the screen to edit; see [Create a settings resource](create-settings.md)
13
+ - A menu for the screen to edit: a settings resource at `settings/setup/` holding only the choices setup offers, here a `Market` enum of `gentler`, `standard` and `tougher`. See [Give setup a menu](give-setup-a-menu.md) for why, and [Create a settings resource](create-settings.md)
14
14
  - `seriousgaming.sdk.json` in your working directory
15
15
 
16
16
  ## Steps
@@ -20,7 +20,7 @@ A setup screen at `setup/` that edits the `engine` settings and starts play from
20
20
  ```bash
21
21
  pnpm run sdk new setup '{
22
22
  "definition": {
23
- "configures": ["engine"]
23
+ "configures": ["setup"]
24
24
  },
25
25
  "rootDirectory": ".",
26
26
  "ui": { "entrypoint": "index.html" }
@@ -48,8 +48,9 @@ setup/
48
48
  Open `setup/src/App.tsx`. Read and write the settings with `useSettingsEditor`, typed by the generated `Settings`:
49
49
 
50
50
  ```tsx
51
+ import { Button, MenuItem, Stack, TextField } from '@mui/material';
51
52
  import { useSettingsEditor, useSettingsEditorCallbacks } from '@seriousgaming/sdk/ui';
52
- import { Button, Stack, TextField } from '@mui/material';
53
+
53
54
  import type { Settings } from '../types';
54
55
 
55
56
  function App() {
@@ -59,15 +60,22 @@ function App() {
59
60
  return (
60
61
  <Stack spacing={2}>
61
62
  <TextField
62
- label="Base demand"
63
- type="number"
64
- value={settings.engine.BaseDemand}
63
+ select
64
+ label="Market"
65
+ value={settings.setup.Market}
65
66
  onChange={(e) =>
66
67
  void updateSettings({
67
- engine: { ...settings.engine, BaseDemand: Number(e.target.value) },
68
+ setup: {
69
+ ...settings.setup,
70
+ Market: e.target.value as Settings['setup']['Market'],
71
+ },
68
72
  })
69
73
  }
70
- />
74
+ >
75
+ <MenuItem value="gentler">Gentler</MenuItem>
76
+ <MenuItem value="standard">As the scenario sets it</MenuItem>
77
+ <MenuItem value="tougher">Tougher</MenuItem>
78
+ </TextField>
71
79
  <Button variant="contained" onClick={() => requestPlay()}>
72
80
  Start game
73
81
  </Button>
@@ -92,7 +100,7 @@ The dev server opens on `/setup`.
92
100
 
93
101
  - [ ] The form shows each setting's resolved value
94
102
  - [ ] Changing a value and pressing Start (or the host's Play) starts the session with that value
95
- - [ ] `pnpm run sdk view` after play shows the engine acting on the new value
103
+ - [ ] `pnpm run sdk view` after play shows the engine acting on the choice, once the engine declares `setup` in its `settings` and reads it
96
104
 
97
105
  ## Troubleshooting
98
106
 
@@ -114,3 +122,4 @@ The configuration step exists only when the package has a `setup/setup.sdk.json`
114
122
  - [Create a scenario editor](create-scenario-editor.md)
115
123
  - [Use requestPlay in a setup screen](use-request-play.md)
116
124
  - [Create a settings resource](create-settings.md)
125
+ - [Give setup a menu](give-setup-a-menu.md)
@@ -30,6 +30,7 @@ A logic-bearing resource (engine, hook, tick controller, endpoint) must declare
30
30
 
31
31
  ```typescript
32
32
  import { getText, type RunFunction } from '@seriousgaming/sdk';
33
+
33
34
  import type { Context, Settings, Callbacks } from './types';
34
35
 
35
36
  export const Run: RunFunction<Context, Settings, Callbacks> = async ({