@seriousgaming/sdk-tools 1.6.1 → 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 (202) hide show
  1. package/dist/agent/guidance.md +1 -0
  2. package/dist/{cli-2NU2LPEE.js → cli-27M4PX7O.js} +17 -17
  3. package/dist/{cli-2BH7FX27.js → cli-2FXZZLCL.js} +1 -1
  4. package/dist/{cli-5ACDPCXI.js → cli-2KDV2DYC.js} +3 -3
  5. package/dist/{cli-OXAUOWCN.js → cli-2QM63J3I.js} +1 -1
  6. package/dist/{cli-HW53ICZC.js → cli-32NRB2IT.js} +15 -15
  7. package/dist/{cli-45OCBG53.js → cli-3HBYH4VF.js} +11 -11
  8. package/dist/{cli-4VFZHLDG.js → cli-3HPAKEJJ.js} +2 -2
  9. package/dist/{cli-R2MUZQE2.js → cli-3HZGJRQW.js} +11 -11
  10. package/dist/{cli-PGCIHPU7.js → cli-3OCKRPXI.js} +18 -18
  11. package/dist/{cli-64AB62PM.js → cli-3OVXQJEW.js} +2 -2
  12. package/dist/{cli-4UWFQNGF.js → cli-3VV2JLHX.js} +1 -1
  13. package/dist/{cli-XSLNH5PR.js → cli-42ZUP4X3.js} +141 -5
  14. package/dist/{cli-ZJFQ7EEA.js → cli-4B5OBHSY.js} +19 -19
  15. package/dist/{cli-7A6MKCUJ.js → cli-4EMNCU63.js} +27 -19
  16. package/dist/cli-5CG6BMCY.js +36 -0
  17. package/dist/{cli-XZCJIKIV.js → cli-5FRKWNVP.js} +19 -19
  18. package/dist/{cli-Y3DDNMPX.js → cli-5P66N5G6.js} +17 -17
  19. package/dist/{cli-6VNKQ3OX.js → cli-5SYPXJCB.js} +28 -16
  20. package/dist/{cli-G6CANSPL.js → cli-66AHBZRZ.js} +15 -15
  21. package/dist/{cli-BJMS3VX3.js → cli-6AGWTGTO.js} +106 -28
  22. package/dist/{cli-TTMBBEJC.js → cli-6BAZE75K.js} +18 -18
  23. package/dist/{cli-GFNDW2DL.js → cli-6FVHRL3H.js} +19 -19
  24. package/dist/{cli-QVASWX2A.js → cli-6GDPO5VU.js} +2 -2
  25. package/dist/{cli-7XLHO2FE.js → cli-6NBER36P.js} +1 -1
  26. package/dist/{cli-FQRVFGN6.js → cli-726NJARI.js} +0 -0
  27. package/dist/{cli-CD5CIJZI.js → cli-72DRYVTT.js} +13 -13
  28. package/dist/{cli-MMN4BPO4.js → cli-7CW2BBJG.js} +1 -1
  29. package/dist/{cli-XAT25PRU.js → cli-7GJGFILU.js} +15 -15
  30. package/dist/{cli-HFX3YPUL.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-KGM6RRQW.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-DOXRQ3S5.js → cli-C7YZNPWX.js} +11 -11
  41. package/dist/{cli-HOE3WLFH.js → cli-CAX4CQTC.js} +13 -13
  42. package/dist/{cli-YOTGR3NB.js → cli-CVOLMK3Z.js} +1 -1
  43. package/dist/{cli-ILFDANBR.js → cli-D3CZRXVJ.js} +63 -17
  44. package/dist/{cli-4YB3ROVR.js → cli-DMKRP33X.js} +1 -1
  45. package/dist/{cli-Y3O5F4JN.js → cli-DPFN2LIZ.js} +15 -15
  46. package/dist/{cli-6UTPHWRQ.js → cli-DT756M3Z.js} +20 -20
  47. package/dist/{cli-TIDQ4WUE.js → cli-DXHPYN4N.js} +1 -1
  48. package/dist/{cli-6K3VQQUS.js → cli-E665NKUQ.js} +5 -5
  49. package/dist/{cli-O5ABH2WK.js → cli-EK7CGMGS.js} +17 -17
  50. package/dist/{cli-6QB2VFPY.js → cli-ESU3J563.js} +15 -15
  51. package/dist/{cli-VPRRICZA.js → cli-F47ELAXM.js} +47 -47
  52. package/dist/{cli-RLEGRWFM.js → cli-FH4WBZHA.js} +14 -14
  53. package/dist/{cli-3D3ZXWOV.js → cli-FHKRO6OU.js} +19 -19
  54. package/dist/{cli-JZCLIT3O.js → cli-FSEDPZR5.js} +19 -19
  55. package/dist/{cli-XOTNXEJA.js → cli-FV45UZQP.js} +19 -19
  56. package/dist/{cli-AV2FYC5G.js → cli-G7FX7ZIU.js} +12 -12
  57. package/dist/{cli-IP4RXGHM.js → cli-GFONBOJT.js} +129 -38
  58. package/dist/{cli-C5QOJJWX.js → cli-GHIMH6JU.js} +1 -1
  59. package/dist/{cli-IDVUHGKG.js → cli-HC7L5DXV.js} +15 -15
  60. package/dist/{cli-WU43JT4T.js → cli-HJPNNORV.js} +2 -2
  61. package/dist/{cli-QY5NZAR7.js → cli-HMEZHQBC.js} +17 -17
  62. package/dist/{cli-JZOZOEZM.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-Z56ZIVA6.js → cli-JA6UFTSX.js} +17 -17
  67. package/dist/{cli-MJV47HKI.js → cli-JOXCAGM7.js} +19 -19
  68. package/dist/{cli-ZBN5KAIB.js → cli-JQ6I5GGE.js} +3 -3
  69. package/dist/{cli-TDSQSCX4.js → cli-K6M6YB67.js} +1 -1
  70. package/dist/{cli-C6ZLPK2U.js → cli-KFVA7DT3.js} +3 -3
  71. package/dist/{cli-KOGRWFN7.js → cli-KH6FKM5A.js} +15 -15
  72. package/dist/{cli-5IAW3LIF.js → cli-KMT235FV.js} +2 -2
  73. package/dist/{cli-ZDUADFBY.js → cli-KU4PG7ZA.js} +15 -15
  74. package/dist/{cli-N45DREM4.js → cli-L4DEEAMK.js} +17 -17
  75. package/dist/{cli-MU5LB43S.js → cli-ME3JKMJL.js} +19 -19
  76. package/dist/{cli-C3CMJSNL.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-4SIWLHQO.js → cli-MPU4FLA7.js} +4 -4
  80. package/dist/{cli-HCRTYQQS.js → cli-MPWTXNF6.js} +2 -2
  81. package/dist/{cli-EVI36HEM.js → cli-N5K2KHPR.js} +15 -15
  82. package/dist/{cli-RSW6EBBD.js → cli-NGOQWOQE.js} +15 -15
  83. package/dist/{cli-ZTWOE3ZT.js → cli-NU4SCD5D.js} +1 -1
  84. package/dist/{cli-BYCHKSSH.js → cli-O3IMNLN2.js} +282 -96
  85. package/dist/{cli-KGT5L7VZ.js → cli-OUFXSQOW.js} +7265 -4467
  86. package/dist/{cli-DFBTZEBX.js → cli-PEY6XZDE.js} +16 -16
  87. package/dist/{cli-QUSCIUOM.js → cli-PLW3TWJ7.js} +19 -19
  88. package/dist/{cli-JVI24FI6.js → cli-PO2ALWHP.js} +13 -13
  89. package/dist/{cli-3BRC32CP.js → cli-PPEB3ENS.js} +18 -18
  90. package/dist/{cli-ZDOTXEKL.js → cli-PZ7G544B.js} +3 -3
  91. package/dist/{cli-L7VYSXQK.js → cli-Q5BKFFDL.js} +4 -4
  92. package/dist/{cli-3ZKWV3PN.js → cli-QAI6T5FL.js} +15 -15
  93. package/dist/{cli-KSGB2ZLK.js → cli-QAVLRCQ5.js} +3 -3
  94. package/dist/{cli-VDBW23SS.js → cli-QDIH2G2P.js} +15 -15
  95. package/dist/cli-SN7D7HTX.js +36 -0
  96. package/dist/{cli-IEMKI7J7.js → cli-SOQJHK4Q.js} +6 -6
  97. package/dist/{cli-4PXNOJQX.js → cli-SPKPDXWD.js} +15 -15
  98. package/dist/{cli-MOPSZ3CS.js → cli-SWUAXVIJ.js} +15 -15
  99. package/dist/cli-TJNLXQJ5.js +36 -0
  100. package/dist/{cli-BUQI5UU4.js → cli-U2EWI6H5.js} +11 -11
  101. package/dist/{cli-TT36JCU5.js → cli-UADUC4JD.js} +2 -2
  102. package/dist/{cli-FWFRKQNE.js → cli-UR63LFVK.js} +2 -2
  103. package/dist/{cli-J4UBELKF.js → cli-UTHPCZYL.js} +2 -2
  104. package/dist/{cli-Q6ZBZYK2.js → cli-UYV3BDPA.js} +3 -3
  105. package/dist/{cli-LQOHATY2.js → cli-UZCQL6YP.js} +3 -3
  106. package/dist/{cli-HKORECAG.js → cli-V5K3CCYZ.js} +2 -2
  107. package/dist/cli-V7L3HEL4.js +36 -0
  108. package/dist/{cli-HSIHDN6K.js → cli-VBSF3R3L.js} +16 -16
  109. package/dist/{cli-NROTDF5Y.js → cli-VQ4OJ4KE.js} +18 -18
  110. package/dist/{cli-IUS2YCD3.js → cli-VTLFQHDO.js} +1 -1
  111. package/dist/{cli-JJSWBW4H.js → cli-W7XCTGQ7.js} +15 -15
  112. package/dist/{cli-UZZFNXRX.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-TTKICM5P.js → cli-YLYB4ITF.js} +13 -13
  117. package/dist/{cli-72XDEFU3.js → cli-ZFY6TGU7.js} +4 -4
  118. package/dist/{cli-6SGCYEEC.js → cli-ZSKP2IRP.js} +53 -38
  119. package/dist/cli.js +53 -51
  120. package/dist/client.js +17699 -16630
  121. package/dist/core/game-settings.d.ts +5 -3
  122. package/dist/core/save-scenario.d.ts +1 -0
  123. package/dist/core/session-roster.d.ts +10 -0
  124. package/dist/core/session-start-gate.d.ts +25 -0
  125. package/dist/core/session.d.ts +4 -0
  126. package/dist/dev/console/assets/index-CVNjiRUh.js +208 -0
  127. package/dist/dev/console/index.html +1 -1
  128. package/dist/dev/routes.d.ts +5 -2
  129. package/dist/dev/shell.d.ts +9 -1
  130. package/dist/dev/view/batch.d.ts +11 -1
  131. package/dist/dev/view/route.d.ts +18 -1
  132. package/dist/dev/view/view.d.ts +9 -0
  133. package/dist/docs/api/deck.md +1 -1
  134. package/dist/docs/api/index.md +2 -2
  135. package/dist/docs/api/sdk-commands.md +4 -0
  136. package/dist/docs/api/sdk-e2e.md +12 -6
  137. package/dist/docs/api/sdk-projection.md +1 -0
  138. package/dist/docs/api/sdk-tools-client.md +7 -1
  139. package/dist/docs/api/sdk-tools-playwright.md +1 -8
  140. package/dist/docs/api/sdk-ui-testing.md +1 -0
  141. package/dist/docs/api/sdk-ui.md +67 -63
  142. package/dist/docs/api/sdk.md +12 -1
  143. package/dist/docs/changelog.md +26 -0
  144. package/dist/docs/cli-and-dev-server.md +4 -0
  145. package/dist/docs/cli-error-codes.md +7 -1
  146. package/dist/docs/cli-reference.md +20 -2
  147. package/dist/docs/concepts/index.md +1 -0
  148. package/dist/docs/guides/engine.md +5 -0
  149. package/dist/docs/guides/file-handling.md +4 -1
  150. package/dist/docs/guides/llm-integration.md +3 -2
  151. package/dist/docs/guides/multi-team-games.md +2 -0
  152. package/dist/docs/guides/patterns.md +5 -0
  153. package/dist/docs/guides/presentation.md +11 -10
  154. package/dist/docs/guides/session-hooks.md +16 -0
  155. package/dist/docs/guides/session.md +1 -1
  156. package/dist/docs/guides/settings.md +6 -2
  157. package/dist/docs/guides/setup.md +23 -2
  158. package/dist/docs/guides/speech-generation.md +1 -0
  159. package/dist/docs/guides/testing.md +2 -0
  160. package/dist/docs/guides/tick-controller.md +2 -0
  161. package/dist/docs/guides/type-safety.md +2 -1
  162. package/dist/docs/guides/ui-files-and-llms.md +3 -1
  163. package/dist/docs/guides/upgrading.md +16 -0
  164. package/dist/docs/guides/validators.md +27 -4
  165. package/dist/docs/guides/waiting-room.md +2 -0
  166. package/dist/docs/page-index.md +12 -10
  167. package/dist/docs/recipes/call-endpoint-from-ui.md +1 -0
  168. package/dist/docs/recipes/create-scenario-editor.md +2 -1
  169. package/dist/docs/recipes/create-setup.md +2 -1
  170. package/dist/docs/recipes/declare-api-uses.md +1 -0
  171. package/dist/docs/recipes/describe-setup-with-endpoint.md +69 -0
  172. package/dist/docs/recipes/index.md +3 -1
  173. package/dist/docs/recipes/share-logic-between-engine-and-ui.md +2 -2
  174. package/dist/docs/recipes/test-user-interface.md +1 -1
  175. package/dist/docs/recipes/validate-scenarios.md +9 -3
  176. package/dist/docs/recipes/write-setup-notes.md +58 -0
  177. package/dist/docs/troubleshooting.md +2 -1
  178. package/dist/execution/executor.d.ts +12 -0
  179. package/dist/execution/scenario-gates.d.ts +40 -0
  180. package/dist/host/protocol.d.ts +10 -1
  181. package/dist/host.js +1083 -467
  182. package/dist/playwright.js +17760 -16691
  183. package/dist/runtime/manifest-version.d.ts +1 -1
  184. package/dist/runtime.js +4 -2
  185. package/dist/schema.json +10 -1
  186. package/dist/setup/setup-notes.d.ts +42 -0
  187. package/dist/templates/package/package.json.liquid +15 -15
  188. package/dist/templates/starter-game/package.json +13 -13
  189. package/dist/utils/error-codes.d.ts +13 -1
  190. package/dist/validation/package-validation.d.ts +1 -1
  191. package/package.json +22 -23
  192. package/dist/cli-2GZYGRVL.js +0 -36
  193. package/dist/cli-5SM367K7.js +0 -30
  194. package/dist/cli-DDJYUKQG.js +0 -36
  195. package/dist/cli-LK3V4RI5.js +0 -36
  196. package/dist/cli-N24OHSAN.js +0 -36
  197. package/dist/cli-OMWC75CC.js +0 -256
  198. package/dist/cli-RCIWBCXD.js +0 -36
  199. package/dist/cli-UMEBPAZQ.js +0 -16
  200. package/dist/cli-VQ6HVQW4.js +0 -4010
  201. package/dist/cli-WR3NOY74.js +0 -36
  202. package/dist/dev/console/assets/index-CuMOOH9m.js +0 -204
@@ -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"`
@@ -0,0 +1,58 @@
1
+ # Write setup notes for assistants
2
+
3
+ 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.
4
+
5
+ **Keywords:** setup notes, assistant, agent, AI setup, session setup, make it harder, shorter session, setting paths, setup/notes, MCP
6
+
7
+ ## What you'll build
8
+
9
+ A Markdown file at `setup/notes/en.md` that an assistant reads before changing a session's settings for a facilitator. A settings schema describes each setting on its own; the notes say how settings work together to mean what a facilitator asks for. They are for assistants: your setup screen is what a facilitator sees, and a host need not show the notes to anyone.
10
+
11
+ ## Prerequisites
12
+
13
+ - A [setup screen](create-setup.md), since the notes sit beside it and describe the settings it `configures`
14
+ - `seriousgaming.sdk.json` in your working directory
15
+
16
+ ## Steps
17
+
18
+ 1. Create `setup/notes/en.md`. Name every setting as a setting path in a code span, as `engine.BaseDemand`, so an assistant can write it back as it stands:
19
+
20
+ ```markdown
21
+ # Setting up a Factory session
22
+
23
+ Most sessions need no changes: start on the scenario the facilitator picked.
24
+
25
+ ## Worth asking about
26
+
27
+ - **Length.** `game.maxTicks` is the number of rounds, 10 by default, between 4 and 12
28
+
29
+ ## What requests mean
30
+
31
+ - **'Harder'**: lower `engine.BaseDemand` to 7,000 and raise `engine.DemandPriceModifier` to 700
32
+ - **'Shorter'**: set `game.maxTicks` to 6, and `engine.BonusTick` to 4 so the bonus still lands in play
33
+
34
+ ## Leave alone
35
+
36
+ - `engine.CostPerUnit` at £0 makes unsold stock free, which only suits a practice round
37
+ ```
38
+
39
+ 2. Keep it short: the two to five choices worth asking a facilitator about, what common requests mean as settings and values, and what to leave alone. Where a request matches one of your scenarios, say to pick that scenario instead
40
+
41
+ 3. Add a file per locale you support, such as `setup/notes/it.md`. An assistant gets the notes in its locale, or `en`, or your first supported locale
42
+
43
+ ## Verify
44
+
45
+ - `pnpm run sdk build --validate-only` passes, and `dist/setup/notes/en.md` is there after `pnpm run sdk build`
46
+ - `pnpm run sdk dev`: on the configuration step, **Notes for assistants** shows the file exactly as an assistant receives it
47
+
48
+ ## Troubleshooting
49
+
50
+ - _`SETTINGS_UNKNOWN` in `setup/notes/en.md`_: a code span names a setting your package does not declare, often a typo. Any code span starting with one of your settings identifiers is read as a setting path
51
+ - _`SETUP_NOTES_UNCONFIGURED`_: the notes name a setting your setup screen does not `configures`, so a host refuses that change. Add the settings identifier to `configures`, or leave the setting out
52
+ - _A code span that is not a setting_, such as `requires`: fine. Only spans starting with a settings identifier are checked
53
+
54
+ ## Related
55
+
56
+ - [Setup guide: notes for assistants](../guides/setup.md#notes-for-assistants)
57
+ - [Describe a setup with an endpoint](describe-setup-with-endpoint.md): let an assistant read back what a setup means
58
+ - [Validate a game's scenarios](validate-scenarios.md): refuse a session whose setup breaks your rules
@@ -723,8 +723,9 @@ Restart the dev server. The SDK merges this config automatically for both `sdk d
723
723
  3. Check the type imports:
724
724
 
725
725
  ```typescript
726
- import type { Context, Settings } from '../types';
727
726
  import { useUserInterfaceData } from '@seriousgaming/sdk/ui';
727
+
728
+ import type { Context, Settings } from '../types';
728
729
  ```
729
730
 
730
731
  4. Call the hook inside `UserInterfaceWrapper`:
@@ -297,6 +297,18 @@ export declare class GameExecutor {
297
297
  * Get the active scenario (if any)
298
298
  */
299
299
  getActiveScenario(): SDKScenario | null;
300
+ /**
301
+ * What `initialize(true, …, scenarioId)` would start a session on, read
302
+ * without changing anything: the package on disk, the scenario it would
303
+ * activate and the session-override layer it would load. So a start can be
304
+ * judged (§15.8) before the running session is torn down, and a refusal
305
+ * leaves it as it was.
306
+ */
307
+ previewStart(scenarioId?: string | null): Promise<{
308
+ config: ResolvedPackageManifest;
309
+ scenario: SDKScenario | null;
310
+ overrides: SessionSettingsOverrides;
311
+ }>;
300
312
  /** The scenario `initialize` would activate for this id, without activating it. */
301
313
  findScenario(scenarioId?: string | null): SDKScenario | null;
302
314
  /**
@@ -5,6 +5,8 @@
5
5
  * Unlike the other two gates it needs no session. It judges settings, not a
6
6
  * board, so the build can run it on a package's own scenarios and the dev
7
7
  * server on a scenario about to be saved, with only the package and a loader.
8
+ * In a package that lists `session-validation` it also judges a session's own
9
+ * settings as the session starts.
8
10
  */
9
11
  import { type ResolvedPackageManifest, type ScenarioProblem } from '@seriousgaming/sdk';
10
12
  import { LogicLoader } from './logic-loader';
@@ -13,6 +15,8 @@ import type { SessionSettingsOverrides } from './types';
13
15
  export declare const SCENARIO_VALIDATION = "scenario-validation";
14
16
  /** The `requires` feature name a package whose `Scenario` gate reads files lists (§15.8). */
15
17
  export declare const SCENARIO_FILES = "scenario-files";
18
+ /** The `requires` feature name a package whose `Scenario` gate also judges a starting session lists (§15.8). */
19
+ export declare const SESSION_VALIDATION = "session-validation";
16
20
  /**
17
21
  * Where the files of the scenario being judged resolve (§15.8): as that
18
22
  * scenario resolves them, so a gate finds exactly the files a session started
@@ -32,7 +36,38 @@ export interface ScenarioFileRoots {
32
36
  /** A problem one validator found with a scenario. */
33
37
  export interface ScenarioGateProblem extends ScenarioProblem {
34
38
  validatorIdentifier: string;
39
+ /**
40
+ * Set when the gate itself failed (it threw, overran, or returned
41
+ * something other than an array) rather than finding a problem. A failure
42
+ * blocks like an error, but only a fix to the game clears it, so it is
43
+ * reported apart from the problems a setting change would fix (§15.6).
44
+ */
45
+ failed?: true;
46
+ /**
47
+ * Set beside `failed` when the gate ran out of time rather than threw.
48
+ * The bound is real time, so a busy host can push a sound gate over it,
49
+ * and a runtime may run it again before refusing a start (§15.8).
50
+ */
51
+ overran?: true;
35
52
  }
53
+ /** Whether a problem refuses: a failed gate, or one that is not a warning. */
54
+ export declare function isBlocking(problem: ScenarioGateProblem): boolean;
55
+ /** How many more times a gate that only overran is run, before a start or a save is refused. */
56
+ export declare const OVERRUN_RETRIES = 1;
57
+ /** Whether the only thing refusing is a gate that ran out of time. */
58
+ export declare function onlyOverran(problems: ScenarioGateProblem[]): boolean;
59
+ /**
60
+ * Run `judge` again while all it refuses on is a gate that ran out of time
61
+ * (§15.8). The bound is real time, so a busy host can push a sound gate over
62
+ * it; a throw gives the same answer every time, so it is never run again. The
63
+ * build does not retry: nothing else competes for its time.
64
+ */
65
+ export declare function withOverrunRetry(judge: () => Promise<ScenarioGateProblem[]>): Promise<ScenarioGateProblem[]>;
66
+ /** The problems that refuse, and the warnings that never do. */
67
+ export declare function partitionProblems(problems: ScenarioGateProblem[]): {
68
+ blocking: ScenarioGateProblem[];
69
+ warnings: ScenarioGateProblem[];
70
+ };
36
71
  /** Whether any validator in the package gates scenarios. */
37
72
  export declare function hasScenarioGate(config: Pick<ResolvedPackageManifest, 'validators'>): boolean;
38
73
  /**
@@ -49,6 +84,11 @@ export declare function runScenarioGates(options: {
49
84
  boundMs?: number;
50
85
  /** Where the scenario's files resolve. None at all when absent: the defaults alone. */
51
86
  files?: ScenarioFileRoots;
87
+ /**
88
+ * A starting session's own overrides, applied over the scenario
89
+ * (`session-validation`). Absent for a scenario judged alone.
90
+ */
91
+ sessionOverrides?: SessionSettingsOverrides | null;
52
92
  }): Promise<ScenarioGateProblem[]>;
53
93
  /** One line per problem, naming the validator and the setting. */
54
94
  export declare function describeScenarioProblems(problems: ScenarioGateProblem[]): string[];
@@ -11,7 +11,7 @@
11
11
  * (or the reverse) is caught before either ships.
12
12
  */
13
13
  import type { ContextDeletePath, EndpointFailure, HostOverlay, Participant, PastStateEntry, PastStateQuery, ThemePreference, TimerState, ValidationRejection } from '@seriousgaming/sdk';
14
- import type { CrossTeamData, MutationOutcome, OwnTeamJoinLink, PresentationGame, PresentationSession, RunKind, SessionData, SessionHookFailure, SessionMeta, SharedState, TeamConfiguration, TeamInfo, TeamLinks, TeamState, UserInterfaceLocale, UserInterfaceTheme, ViewerRole, WalkthroughLink } from '@seriousgaming/sdk/ui';
14
+ import type { CrossTeamData, MutationOutcome, OwnTeamJoinLink, PresentationGame, PresentationSession, RunKind, SessionData, SessionHookFailure, SessionMeta, SharedState, TeamConfiguration, TeamInfo, SessionJoinLink, TeamLinks, TeamState, UserInterfaceLocale, UserInterfaceTheme, ViewerRole, WalkthroughLink } from '@seriousgaming/sdk/ui';
15
15
  /**
16
16
  * Version of the host↔iframe handshake protocol. Both ends stamp it on the
17
17
  * `ready`/`init` window messages and warn (without blocking) when the peer's
@@ -414,6 +414,15 @@ export type HostSessionPortMessage = {
414
414
  type: 'setTeamLinks';
415
415
  payload: TeamLinks[];
416
416
  }
417
+ /**
418
+ * One join link for the whole session (§12.3, §13.4), or `null` when the
419
+ * host has none or the game's `teams.sessionJoin` is false. Facilitator-
420
+ * only, and naming no team: the host places whoever follows it.
421
+ */
422
+ | {
423
+ type: 'setSessionJoinLink';
424
+ payload: SessionJoinLink | null;
425
+ }
417
426
  /**
418
427
  * Whether this session surface belongs to the game being played or to a
419
428
  * walkthrough beside it (§5.7). Sent in the initial batch and never again.