@seriousgaming/sdk-tools 1.7.0 → 1.8.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 (187) hide show
  1. package/dist/agent/guidance.md +1 -0
  2. package/dist/{cli-ZTZ5H55T.js → cli-27M4PX7O.js} +17 -17
  3. package/dist/{cli-2BH7FX27.js → cli-2FXZZLCL.js} +1 -1
  4. package/dist/{cli-HHPMAV4F.js → cli-2KDV2DYC.js} +3 -3
  5. package/dist/{cli-57V4ARER.js → cli-2QM63J3I.js} +1 -1
  6. package/dist/{cli-TFMNNVJ7.js → cli-32NRB2IT.js} +15 -15
  7. package/dist/{cli-JPAXKLVT.js → cli-3HBYH4VF.js} +11 -11
  8. package/dist/{cli-JR5AZLLK.js → cli-3HPAKEJJ.js} +2 -2
  9. package/dist/{cli-3PIJLSRQ.js → cli-3HZGJRQW.js} +11 -11
  10. package/dist/{cli-BOXXMDSX.js → cli-3OCKRPXI.js} +18 -18
  11. package/dist/{cli-4CHKF4DQ.js → cli-3OVXQJEW.js} +2 -2
  12. package/dist/{cli-4UWFQNGF.js → cli-3VV2JLHX.js} +1 -1
  13. package/dist/{cli-EJVAQCMQ.js → cli-42ZUP4X3.js} +114 -5
  14. package/dist/{cli-CV4JGVJR.js → cli-4B5OBHSY.js} +19 -19
  15. package/dist/{cli-2DQJACAH.js → cli-4EMNCU63.js} +17 -17
  16. package/dist/cli-5CG6BMCY.js +36 -0
  17. package/dist/{cli-VYR326C6.js → cli-5FRKWNVP.js} +19 -19
  18. package/dist/{cli-TDYKRXUA.js → cli-5P66N5G6.js} +17 -17
  19. package/dist/{cli-ZRPWZOCW.js → cli-5SYPXJCB.js} +20 -16
  20. package/dist/{cli-TJ3PLRHF.js → cli-66AHBZRZ.js} +15 -15
  21. package/dist/{cli-M7WEAIRF.js → cli-6AGWTGTO.js} +106 -28
  22. package/dist/{cli-WG36UJRK.js → cli-6BAZE75K.js} +18 -18
  23. package/dist/{cli-VPON5HGB.js → cli-6FVHRL3H.js} +19 -19
  24. package/dist/{cli-QVASWX2A.js → cli-6GDPO5VU.js} +2 -2
  25. package/dist/{cli-TPNQLYPC.js → cli-6NBER36P.js} +1 -1
  26. package/dist/{cli-LQ4VSM5R.js → cli-726NJARI.js} +0 -0
  27. package/dist/{cli-GHLILDH7.js → cli-72DRYVTT.js} +13 -13
  28. package/dist/{cli-MMN4BPO4.js → cli-7CW2BBJG.js} +1 -1
  29. package/dist/{cli-FP32D3T6.js → cli-7GJGFILU.js} +15 -15
  30. package/dist/{cli-HYEU3QS6.js → cli-7NCVUM5U.js} +3 -3
  31. package/dist/cli-7S4G4EKK.js +110 -0
  32. package/dist/{cli-J4DKUUTK.js → cli-7V6GUIIS.js} +2 -2
  33. package/dist/{cli-N6H6T2E2.js → cli-AEAFLZGY.js} +12 -0
  34. package/dist/{cli-C47GJATR.js → cli-AGYCXRPR.js} +3 -3
  35. package/dist/{cli-XSVGKI3R.js → cli-BC4KKNLA.js} +1 -1
  36. package/dist/cli-BQ3FHENQ.js +16 -0
  37. package/dist/{cli-CXCL7VRK.js → cli-BXCCODYD.js} +20 -20
  38. package/dist/cli-C2XDL4LD.js +30 -0
  39. package/dist/{cli-MJUYJIEP.js → cli-C45A5VX6.js} +3 -3
  40. package/dist/{cli-64AA7367.js → cli-C7YZNPWX.js} +11 -11
  41. package/dist/{cli-ZKG3OPZ6.js → cli-CAX4CQTC.js} +13 -13
  42. package/dist/{cli-YOTGR3NB.js → cli-CVOLMK3Z.js} +1 -1
  43. package/dist/{cli-PKQNOGBO.js → cli-D3CZRXVJ.js} +63 -17
  44. package/dist/{cli-4YB3ROVR.js → cli-DMKRP33X.js} +1 -1
  45. package/dist/{cli-FZ7QAZZP.js → cli-DPFN2LIZ.js} +15 -15
  46. package/dist/{cli-7TOLC62D.js → cli-DT756M3Z.js} +20 -20
  47. package/dist/{cli-TIDQ4WUE.js → cli-DXHPYN4N.js} +1 -1
  48. package/dist/{cli-OANH3BTQ.js → cli-E665NKUQ.js} +5 -5
  49. package/dist/{cli-DEBCP7UH.js → cli-EK7CGMGS.js} +17 -17
  50. package/dist/{cli-PIO7NWMH.js → cli-ESU3J563.js} +15 -15
  51. package/dist/{cli-6HB6HTC6.js → cli-F47ELAXM.js} +47 -47
  52. package/dist/{cli-JIZTQVL2.js → cli-FH4WBZHA.js} +14 -14
  53. package/dist/{cli-JRMHSMYT.js → cli-FHKRO6OU.js} +19 -19
  54. package/dist/{cli-ESA6YNPF.js → cli-FSEDPZR5.js} +19 -19
  55. package/dist/{cli-G5DQGZ2E.js → cli-FV45UZQP.js} +19 -19
  56. package/dist/{cli-XR2XSWQN.js → cli-G7FX7ZIU.js} +12 -12
  57. package/dist/{cli-X7E3637I.js → cli-GFONBOJT.js} +50 -26
  58. package/dist/{cli-C5QOJJWX.js → cli-GHIMH6JU.js} +1 -1
  59. package/dist/{cli-T4HWGMY4.js → cli-HC7L5DXV.js} +15 -15
  60. package/dist/{cli-WU43JT4T.js → cli-HJPNNORV.js} +2 -2
  61. package/dist/{cli-SOMIB4B4.js → cli-HMEZHQBC.js} +17 -17
  62. package/dist/{cli-TFZ53OA2.js → cli-HQUVSAHY.js} +18 -18
  63. package/dist/{cli-MYJGMA6U.js → cli-IC5FOT2J.js} +1 -1
  64. package/dist/{cli-VL2P354N.js → cli-IVZ7AHUJ.js} +3 -3
  65. package/dist/{cli-B6YHEKIJ.js → cli-J2OTL6JH.js} +5 -5
  66. package/dist/{cli-NEOLMC2P.js → cli-JA6UFTSX.js} +17 -17
  67. package/dist/{cli-Z5HWENER.js → cli-JOXCAGM7.js} +19 -19
  68. package/dist/{cli-NOQBWJQN.js → cli-JQ6I5GGE.js} +3 -3
  69. package/dist/{cli-TDSQSCX4.js → cli-K6M6YB67.js} +1 -1
  70. package/dist/{cli-MYJGGLC5.js → cli-KFVA7DT3.js} +3 -3
  71. package/dist/{cli-DHOWZCXT.js → cli-KH6FKM5A.js} +15 -15
  72. package/dist/{cli-4VZIJYKU.js → cli-KMT235FV.js} +2 -2
  73. package/dist/{cli-6ZSMW4HR.js → cli-KU4PG7ZA.js} +15 -15
  74. package/dist/{cli-ATI6OLJU.js → cli-L4DEEAMK.js} +17 -17
  75. package/dist/{cli-EDCAH2TC.js → cli-ME3JKMJL.js} +19 -19
  76. package/dist/{cli-R7RG2VMW.js → cli-MJ65PIYI.js} +15 -15
  77. package/dist/cli-MM2ROZWO.js +36 -0
  78. package/dist/{cli-RZITKPJX.js → cli-MN7X4UG2.js} +1 -1
  79. package/dist/{cli-LE5ICDAF.js → cli-MPU4FLA7.js} +4 -4
  80. package/dist/{cli-HCRTYQQS.js → cli-MPWTXNF6.js} +2 -2
  81. package/dist/{cli-NPPY557S.js → cli-N5K2KHPR.js} +15 -15
  82. package/dist/{cli-PVA52RC2.js → cli-NGOQWOQE.js} +15 -15
  83. package/dist/{cli-ZTWOE3ZT.js → cli-NU4SCD5D.js} +1 -1
  84. package/dist/{cli-UTM4QU67.js → cli-O3IMNLN2.js} +282 -96
  85. package/dist/{cli-MM3A4SPH.js → cli-OUFXSQOW.js} +7265 -4467
  86. package/dist/{cli-UBQCSUDH.js → cli-PEY6XZDE.js} +16 -16
  87. package/dist/{cli-HM7CD4VU.js → cli-PLW3TWJ7.js} +19 -19
  88. package/dist/{cli-LRQDF3ZO.js → cli-PO2ALWHP.js} +13 -13
  89. package/dist/{cli-IPP5FDCH.js → cli-PPEB3ENS.js} +18 -18
  90. package/dist/{cli-C3OERMIR.js → cli-PZ7G544B.js} +3 -3
  91. package/dist/{cli-GPAN6XK2.js → cli-Q5BKFFDL.js} +4 -4
  92. package/dist/{cli-MULKSLA4.js → cli-QAI6T5FL.js} +15 -15
  93. package/dist/{cli-JGFJWZFU.js → cli-QAVLRCQ5.js} +3 -3
  94. package/dist/{cli-OQG3Y4RU.js → cli-QDIH2G2P.js} +15 -15
  95. package/dist/cli-SN7D7HTX.js +36 -0
  96. package/dist/{cli-SWZY7L7K.js → cli-SOQJHK4Q.js} +6 -6
  97. package/dist/{cli-7RYIEKMB.js → cli-SPKPDXWD.js} +15 -15
  98. package/dist/{cli-WAZD75KE.js → cli-SWUAXVIJ.js} +15 -15
  99. package/dist/cli-TJNLXQJ5.js +36 -0
  100. package/dist/{cli-SX3ULO5P.js → cli-U2EWI6H5.js} +11 -11
  101. package/dist/{cli-FXY3DKPW.js → cli-UADUC4JD.js} +2 -2
  102. package/dist/{cli-FWFRKQNE.js → cli-UR63LFVK.js} +2 -2
  103. package/dist/{cli-YSPZZQCP.js → cli-UTHPCZYL.js} +2 -2
  104. package/dist/{cli-XTANOFQR.js → cli-UYV3BDPA.js} +3 -3
  105. package/dist/{cli-H3J3ICCQ.js → cli-UZCQL6YP.js} +3 -3
  106. package/dist/{cli-LQERHJFE.js → cli-V5K3CCYZ.js} +2 -2
  107. package/dist/cli-V7L3HEL4.js +36 -0
  108. package/dist/{cli-GEQUJF4L.js → cli-VBSF3R3L.js} +16 -16
  109. package/dist/{cli-FXWWYBYU.js → cli-VQ4OJ4KE.js} +18 -18
  110. package/dist/{cli-IUS2YCD3.js → cli-VTLFQHDO.js} +1 -1
  111. package/dist/{cli-SOFCTQAL.js → cli-W7XCTGQ7.js} +15 -15
  112. package/dist/{cli-GTWEGYSU.js → cli-W7Y7X3FX.js} +19 -19
  113. package/dist/cli-WWNTBK37.js +1973 -0
  114. package/dist/cli-XPJGW375.js +36 -0
  115. package/dist/{cli-SRHBXZCN.js → cli-Y33ULHYO.js} +1 -1
  116. package/dist/{cli-ZQ2Y3U7F.js → cli-YLYB4ITF.js} +13 -13
  117. package/dist/{cli-4XCQUM3E.js → cli-ZFY6TGU7.js} +4 -4
  118. package/dist/{cli-JRIIAZ33.js → cli-ZSKP2IRP.js} +53 -38
  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 +15 -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 +23 -2
  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 +8 -6
  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 +2 -1
  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/index.md +3 -1
  161. package/dist/docs/recipes/share-logic-between-engine-and-ui.md +2 -2
  162. package/dist/docs/recipes/test-user-interface.md +1 -1
  163. package/dist/docs/recipes/validate-scenarios.md +9 -3
  164. package/dist/docs/recipes/write-setup-notes.md +58 -0
  165. package/dist/docs/troubleshooting.md +2 -1
  166. package/dist/execution/executor.d.ts +12 -0
  167. package/dist/execution/scenario-gates.d.ts +40 -0
  168. package/dist/host.js +1082 -467
  169. package/dist/playwright.js +17529 -16569
  170. package/dist/runtime/manifest-version.d.ts +1 -1
  171. package/dist/runtime.js +4 -2
  172. package/dist/setup/setup-notes.d.ts +42 -0
  173. package/dist/templates/package/package.json.liquid +15 -15
  174. package/dist/templates/starter-game/package.json +13 -13
  175. package/dist/utils/error-codes.d.ts +13 -1
  176. package/dist/validation/package-validation.d.ts +1 -1
  177. package/package.json +22 -23
  178. package/dist/cli-57C72YKJ.js +0 -36
  179. package/dist/cli-5G7TZHD3.js +0 -36
  180. package/dist/cli-7MBLH4M3.js +0 -36
  181. package/dist/cli-C6G65H6S.js +0 -256
  182. package/dist/cli-L5IG7MY2.js +0 -36
  183. package/dist/cli-SPGUVL6Z.js +0 -36
  184. package/dist/cli-UY4VDI7W.js +0 -30
  185. package/dist/cli-WM6SQJ6Q.js +0 -16
  186. package/dist/cli-ZBTFLZUL.js +0 -36
  187. 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() {
@@ -62,8 +62,9 @@ setup/
62
62
  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
63
 
64
64
  ```tsx
65
- import { useSettingsEditor } from '@seriousgaming/sdk/ui';
66
65
  import { Stack, TextField } from '@mui/material';
66
+ import { useSettingsEditor } from '@seriousgaming/sdk/ui';
67
+
67
68
  import type { Settings } from '../types';
68
69
 
69
70
  function SetupForm() {
@@ -116,8 +117,8 @@ A write is also refused, as `denied` and with none of it applied, when it change
116
117
  `useSettingsEditorCallbacks()` gives the screen `requestPlay`, which leaves the configuration step exactly as the host's Play control does:
117
118
 
118
119
  ```tsx
119
- import { useSettingsEditorCallbacks } from '@seriousgaming/sdk/ui';
120
120
  import { Button } from '@mui/material';
121
+ import { useSettingsEditorCallbacks } from '@seriousgaming/sdk/ui';
121
122
 
122
123
  function StartButton() {
123
124
  const { requestPlay } = useSettingsEditorCallbacks();
@@ -150,6 +151,24 @@ Setup is embedded in the host's page, not a page of its own:
150
151
 
151
152
  The [session UI guide](./session.md#rendering-inside-the-host) covers the same ground in more detail.
152
153
 
154
+ ## Notes for assistants
155
+
156
+ An AI assistant can set a session up for a facilitator, changing the settings your setup screen `configures`. From the schemas alone it cannot tell which few settings matter, 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.
157
+
158
+ ```markdown
159
+ ## What requests mean
160
+
161
+ - **'Harder'**: lower `engine.BaseDemand` to 7,000 and raise `engine.DemandPriceModifier` to 700
162
+ - **'Shorter'**: set `game.maxTicks` to 6
163
+ ```
164
+
165
+ - **Name each setting as a setting path in a code span**, such as `engine.BaseDemand`: 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`)
166
+ - **Say what a schema cannot**: the two to five choices worth asking about, what common requests mean as settings and values, and what to leave alone. Where a request matches a scenario, say to pick that scenario
167
+ - **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
168
+ - **Locales fall back** from the assistant's locale to `en`, then your first supported locale
169
+
170
+ 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.
171
+
153
172
  ## Dev server behaviour
154
173
 
155
174
  `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.
@@ -173,6 +192,7 @@ Deleting the slot removes the configuration step: the game then starts at tick 0
173
192
 
174
193
  ```tsx
175
194
  import { renderSettingsEditor } from '@seriousgaming/sdk/ui/testing';
195
+
176
196
  import { defaultSettings } from '../defaults';
177
197
 
178
198
  renderSettingsEditor(<SetupForm />, {
@@ -188,3 +208,4 @@ See [Test a user interface](../recipes/test-user-interface.md).
188
208
  - [Settings](./settings.md): declaring, reading, and overriding settings
189
209
  - [Scenarios](./scenarios.md)
190
210
  - [Create a setup screen](../recipes/create-setup.md)
211
+ - [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 11k 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
@@ -105,6 +105,7 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
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.
@@ -129,7 +130,8 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
129
130
  - [`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
131
  - [`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
132
  - [`recipes/use-request-tick.md`](recipes/use-request-tick.md), about 3k characters: Trigger the next game tick from within your user interface, so participants submit their decisions via your own button.
132
- - [`recipes/validate-scenarios.md`](recipes/validate-scenarios.md), about 4k characters: Refuse a scenario whose settings break your game's rules, at build and when one is saved, never when a session starts.
133
+ - [`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.
134
+ - [`recipes/write-setup-notes.md`](recipes/write-setup-notes.md), about 3k characters: Tell an AI assistant setting a session up which of your game's settings matter, and what a request such as 'make it a bit harder' means in your game.
133
135
 
134
136
  ## API reference
135
137
 
@@ -143,4 +145,4 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
143
145
  - [`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
146
  - [`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
147
  - [`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.
148
+ - [`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() {
@@ -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 { useSettingsEditor, useSettingsEditorCallbacks } from '@seriousgaming/sdk/ui';
52
51
  import { Button, Stack, TextField } from '@mui/material';
52
+ import { useSettingsEditor, useSettingsEditorCallbacks } from '@seriousgaming/sdk/ui';
53
+
53
54
  import type { Settings } from '../types';
54
55
 
55
56
  function App() {
@@ -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 ({
@@ -0,0 +1,69 @@
1
+ # Describe a setup with an endpoint
2
+
3
+ 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.
4
+
5
+ **Keywords:** describe setup, summary, confirmation, assistant, agent, external endpoint, setup screen, session-scoped endpoint, settings summary
6
+
7
+ ## What you'll build
8
+
9
+ A session-scoped endpoint, `describe_setup`, that reads the settings a session would start on and answers with a sentence a facilitator recognises, such as 'six rounds, a tough market, and factories close after three losing rounds'. An assistant can read it out before asking the facilitator to confirm.
10
+
11
+ ## Prerequisites
12
+
13
+ - A [setup screen](create-setup.md)
14
+ - `seriousgaming.sdk.json` in your working directory
15
+
16
+ ## Steps
17
+
18
+ 1. Create the endpoint, session-scoped and `external` so an assistant can find it, declaring the settings it describes and no `reads`:
19
+
20
+ ```bash
21
+ pnpm run sdk new endpoint '{
22
+ "definition": {
23
+ "identifier": "describe_setup",
24
+ "scope": "session",
25
+ "visibility": "external",
26
+ "description": "Describes the settings this session would start on, in a sentence a facilitator recognises. Call it after changing settings, before asking the facilitator to confirm.",
27
+ "settings": ["engine", "game"],
28
+ "requestSchema": { "type": "object", "properties": {}, "additionalProperties": false },
29
+ "responseSchema": {
30
+ "type": "object",
31
+ "properties": { "summary": { "type": "string" } },
32
+ "required": ["summary"],
33
+ "additionalProperties": false
34
+ }
35
+ },
36
+ "logic": { "directory": "logic", "entrypoint": "logic.ts" },
37
+ "rootDirectory": "."
38
+ }'
39
+ ```
40
+
41
+ 2. Write the handler in `endpoints/describe_setup/logic/logic.ts`. During setup, `settings` already carries the session's changes:
42
+
43
+ ```typescript
44
+ import type { Handler } from '../types';
45
+
46
+ export const Handle: Handler = async ({ settings }) => {
47
+ const rounds = settings.game.maxTicks;
48
+ const length = rounds === null ? 'No round limit' : `${rounds} rounds`;
49
+ const market = settings.engine.BaseDemand < 8000 ? 'a tough market' : 'a forgiving market';
50
+ return { summary: `${length} in ${market}` };
51
+ };
52
+ ```
53
+
54
+ 3. Optionally, list it in your setup screen's `endpoints` and show the summary beside your Play button
55
+
56
+ ## Verify
57
+
58
+ - `pnpm run sdk build --validate-only` passes
59
+ - With `pnpm run sdk dev` at the configuration step, `pnpm run sdk endpoint call describe_setup --request '{}'` answers with the summary, and changes when you change a setting
60
+
61
+ ## Troubleshooting
62
+
63
+ - _The endpoint is refused during setup_: it declares `reads` or `writes`. A session in setup has no game state yet, so an endpoint called then declares neither
64
+ - _An assistant cannot find it_: give it `"visibility": "external"` and a `description` saying when to call it
65
+
66
+ ## Related
67
+
68
+ - [Endpoints guide: calling from outside the game](../guides/endpoints.md#calling-from-outside-the-game)
69
+ - [Write setup notes for assistants](write-setup-notes.md)
@@ -34,6 +34,8 @@ New to the SDK? Start with [Getting started](../getting-started.md), which plays
34
34
  - [Create a session UI](create-session-ui.md): a facilitator screen that shows every team and controls the session
35
35
  - [Create a waiting room UI](create-waiting-room-ui.md): replace the host's built-in holding screen with your own
36
36
  - [Create a setup screen](create-setup.md): a short form at session creation that sets this session's settings
37
+ - [Write setup notes for assistants](write-setup-notes.md): tell an AI assistant which settings matter and what requests such as 'harder' mean
38
+ - [Describe a setup with an endpoint](describe-setup-with-endpoint.md): let an assistant read back a session's settings in the game's own words
37
39
  - [Create a scenario editor](create-scenario-editor.md): a screen for building new scenarios for a released game
38
40
  - [Adapt a UI for observers](adapt-ui-for-observers.md): tell a facilitator observing a team from a participant with `useUserInterfaceViewerRole`
39
41
  - [Remember a viewer's choice](remember-a-viewers-choice.md): keep a tab, a collapsed panel or a sort order across a reload with `useViewerStorage`, keyed by session, surface and viewer
@@ -63,7 +65,7 @@ The full reference is the [Multi-team games](../guides/multi-team-games.md) guid
63
65
  ## Validation
64
66
 
65
67
  - [Create a validator](create-validator.md): reject UI mutations that break the game's rules
66
- - [Validate a game's scenarios](validate-scenarios.md): refuse a scenario whose settings break the game's rules, at build and on save
68
+ - [Validate a game's scenarios](validate-scenarios.md): refuse a scenario whose settings break the game's rules, at build, on save and optionally as a session starts
67
69
 
68
70
  ## Runtime callbacks
69
71
 
@@ -85,10 +85,10 @@ Writing the formula twice works right up until someone changes one copy. Then th
85
85
  4. Import the same file from your UI, and use it only to project. Never to decide:
86
86
 
87
87
  ```tsx
88
- // ui/src/App.tsx
89
- import { projectShare } from '../../shared/market';
90
88
  import { useUserInterfaceCrossTeamData, useUserInterfaceOwnTeam } from '@seriousgaming/sdk/ui';
91
89
 
90
+ // ui/src/App.tsx
91
+ import { projectShare } from '../../shared/market';
92
92
  import type { CrossTeamContext } from '../types';
93
93
 
94
94
  const ownTeam = useUserInterfaceOwnTeam();
@@ -15,8 +15,8 @@ Write and run component tests for a user interface with Vitest, React Testing Li
15
15
  2. Render through the helper for the surface, giving it only what the test cares about. Every other context value has a complete default, so never build the providers by hand:
16
16
 
17
17
  ```tsx
18
- import { fireEvent, screen } from '@testing-library/react';
19
18
  import { renderUserInterface } from '@seriousgaming/sdk/ui/testing';
19
+ import { fireEvent, screen } from '@testing-library/react';
20
20
  import { describe, expect, it, vi } from 'vitest';
21
21
 
22
22
  import { defaultContext, defaultSettings } from '../defaults';
@@ -1,8 +1,8 @@
1
1
  # Validate a game's scenarios
2
2
 
3
- Refuse a scenario whose settings break your game's rules, at build and when one is saved, never when a session starts.
3
+ 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.
4
4
 
5
- **Keywords:** validate scenario, scenario rules, settings conflict, required scenario value, empty default, Scenario gate, scenario-validation, scenario-files, missing file, custom scenario check
5
+ **Keywords:** validate scenario, scenario rules, settings conflict, required scenario value, empty default, Scenario gate, scenario-validation, scenario-files, session-validation, warning, refuse a session start, missing file, custom scenario check
6
6
 
7
7
  ## Prerequisites
8
8
 
@@ -74,6 +74,10 @@ Refuse a scenario whose settings break your game's rules, at build and when one
74
74
 
75
75
  7. Optionally, check the files the scenario names: add `"scenario-files"` to `requires`, and the gate receives `callbacks.describeAsset` and `callbacks.readAsset`, resolved against the scenario being judged. See [Checking the files a scenario names](../guides/validators.md#checking-the-files-a-scenario-names)
76
76
 
77
+ 8. Optionally, judge a session's own settings as it starts: add `"session-validation"` to `requires`, and a session whose setup breaks a rule does not start. See [When it runs](../guides/validators.md#when-it-runs)
78
+
79
+ 9. Optionally, mark a problem that is unusual but may be meant with `level: 'warning'`: it is reported, and never refuses a build, a save or a start
80
+
77
81
  ## Verify
78
82
 
79
83
  - `pnpm run sdk build --validate-only` passes
@@ -81,7 +85,9 @@ Refuse a scenario whose settings break your game's rules, at build and when one
81
85
 
82
86
  ## Troubleshooting
83
87
 
84
- - _`FEATURE_UNDECLARED` at `/requires`_: add `"scenario-validation"` to `requires`
88
+ - _`FEATURE_UNDECLARED` at `/requires`_: add `"scenario-validation"` to `requires`, beside `"session-validation"` if you list that
89
+ - _`SETTINGS_UNGATED`_: your setup UI changes settings no `Scenario` gate declares, so nothing checks them before play. Add them to the gate's validator `settings` if a change there can break play
90
+ - _'The session cannot start'_ when pressing Play: with `session-validation`, the gate found an error in what setup changed. Change the named setting; a message saying the check failed means the gate threw, which only a fix to the game clears
85
91
  - _`SCENARIO_REFUSED` for 'The defaults'_: no scenario is the default, so a session can run on the defaults alone, and they break a rule. Mark a scenario `"default": true`, or change the defaults
86
92
  - _A placeholder that is also a real choice_: the gate sees values, not where they came from, so it cannot tell a scenario that chose `0` from one that forgot. Use an obviously empty default (`""`, `[]` or `{}`)
87
93
  - _'needs the "scenario-files" feature'_: the gate called `readAsset` or `describeAsset`, which it is handed only when `requires` lists `"scenario-files"`