@seriousgaming/sdk-tools 1.8.0 → 1.10.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 (148) hide show
  1. package/dist/{cli-WWNTBK37.js → cli-226ZJ72R.js} +1 -1
  2. package/dist/{cli-6AGWTGTO.js → cli-25SJZI7N.js} +44 -9
  3. package/dist/{cli-EK7CGMGS.js → cli-267QJ2DS.js} +17 -17
  4. package/dist/cli-27Z5T52R.js +30 -0
  5. package/dist/{cli-3OVXQJEW.js → cli-2AH6D32V.js} +2 -2
  6. package/dist/{cli-KU4PG7ZA.js → cli-2ANX6E3A.js} +15 -15
  7. package/dist/{cli-HMEZHQBC.js → cli-2AVPNSAX.js} +17 -17
  8. package/dist/{cli-27M4PX7O.js → cli-33MZSPPK.js} +17 -17
  9. package/dist/{cli-CAX4CQTC.js → cli-35GV2F6R.js} +13 -13
  10. package/dist/{cli-NGOQWOQE.js → cli-36GABN2A.js} +15 -15
  11. package/dist/{cli-DXHPYN4N.js → cli-44CM2AH2.js} +1 -1
  12. package/dist/{cli-UYV3BDPA.js → cli-467VRXGP.js} +3 -3
  13. package/dist/{cli-F47ELAXM.js → cli-4A7RWFNO.js} +49 -49
  14. package/dist/{cli-6GDPO5VU.js → cli-4FJL3KQZ.js} +2 -2
  15. package/dist/{cli-V5K3CCYZ.js → cli-4JNF3O5N.js} +2 -2
  16. package/dist/{cli-UADUC4JD.js → cli-5DWR7RPQ.js} +2 -2
  17. package/dist/{cli-ZFY6TGU7.js → cli-5EH4WTH4.js} +4 -4
  18. package/dist/{cli-MPWTXNF6.js → cli-5M6KDNVX.js} +2 -2
  19. package/dist/{cli-J2OTL6JH.js → cli-5O7XENQY.js} +5 -5
  20. package/dist/{cli-3HZGJRQW.js → cli-5RRPUL6V.js} +11 -11
  21. package/dist/{cli-VBSF3R3L.js → cli-5SHG2M7E.js} +16 -16
  22. package/dist/{cli-72DRYVTT.js → cli-5TKPT3CY.js} +13 -13
  23. package/dist/{cli-C7YZNPWX.js → cli-5V4N4BR4.js} +11 -11
  24. package/dist/{cli-AEAFLZGY.js → cli-5VZBFMCK.js} +5 -1
  25. package/dist/cli-5XE4OMFL.js +36 -0
  26. package/dist/{cli-AGYCXRPR.js → cli-5Z4D3F6Y.js} +3 -3
  27. package/dist/{cli-SOQJHK4Q.js → cli-6BLVI2JM.js} +11 -7
  28. package/dist/{cli-G7FX7ZIU.js → cli-6CYAOUYT.js} +12 -12
  29. package/dist/{cli-3HPAKEJJ.js → cli-6O7YCK2M.js} +2 -2
  30. package/dist/{cli-IC5FOT2J.js → cli-7JUNA74L.js} +1 -1
  31. package/dist/{cli-U2EWI6H5.js → cli-7NUFHMGE.js} +11 -11
  32. package/dist/{cli-FSEDPZR5.js → cli-A3AJQZEN.js} +19 -19
  33. package/dist/{cli-2FXZZLCL.js → cli-AH6AMAIB.js} +1 -1
  34. package/dist/{cli-Q5BKFFDL.js → cli-ATWJCB2G.js} +4 -4
  35. package/dist/{cli-MN7X4UG2.js → cli-B3EFE7ZF.js} +1 -1
  36. package/dist/{cli-UTHPCZYL.js → cli-B5DWKRZ4.js} +2 -2
  37. package/dist/cli-BB6CU4ZC.js +36 -0
  38. package/dist/{cli-HJPNNORV.js → cli-BC67QHD5.js} +2 -2
  39. package/dist/{cli-C45A5VX6.js → cli-BQ36DV5C.js} +3 -3
  40. package/dist/{cli-GHIMH6JU.js → cli-C32Q5E5I.js} +1 -1
  41. package/dist/{cli-KMT235FV.js → cli-CLO7HKEQ.js} +2 -2
  42. package/dist/{cli-W7XCTGQ7.js → cli-CQ4ZR3ZQ.js} +15 -15
  43. package/dist/{cli-ME3JKMJL.js → cli-EXUPHPDJ.js} +19 -19
  44. package/dist/{cli-KFVA7DT3.js → cli-F3YJKP6D.js} +3 -3
  45. package/dist/cli-FGP6YYM7.js +36 -0
  46. package/dist/{cli-CVOLMK3Z.js → cli-G2GLW5Z4.js} +1 -1
  47. package/dist/{cli-6NBER36P.js → cli-GO64NABP.js} +1 -1
  48. package/dist/{cli-2QM63J3I.js → cli-GRSQRFRG.js} +1 -1
  49. package/dist/{cli-PO2ALWHP.js → cli-GSOV26O5.js} +13 -13
  50. package/dist/{cli-JQ6I5GGE.js → cli-HGCOEL5T.js} +3 -3
  51. package/dist/{cli-FHKRO6OU.js → cli-HHRP6FP6.js} +19 -19
  52. package/dist/{cli-3OCKRPXI.js → cli-HN442ZVK.js} +18 -18
  53. package/dist/{cli-7CW2BBJG.js → cli-HNDFANQG.js} +1 -1
  54. package/dist/{cli-PLW3TWJ7.js → cli-HNG6PZW2.js} +19 -19
  55. package/dist/cli-I3ZAZYWP.js +36 -0
  56. package/dist/{cli-2KDV2DYC.js → cli-IKSLPAZN.js} +3 -3
  57. package/dist/{cli-ESU3J563.js → cli-ILHHJR2S.js} +15 -15
  58. package/dist/{cli-HQUVSAHY.js → cli-IPTHJT3J.js} +18 -18
  59. package/dist/{cli-QDIH2G2P.js → cli-IQBY7Z7Q.js} +15 -15
  60. package/dist/{cli-BXCCODYD.js → cli-J42N4PJG.js} +20 -20
  61. package/dist/{cli-32NRB2IT.js → cli-JAVMRERQ.js} +15 -15
  62. package/dist/{cli-HC7L5DXV.js → cli-JHLWBRXB.js} +15 -15
  63. package/dist/{cli-JOXCAGM7.js → cli-JMNPMDXH.js} +19 -19
  64. package/dist/{cli-O3IMNLN2.js → cli-JXQLHJO2.js} +1 -1
  65. package/dist/{cli-7NCVUM5U.js → cli-KIZTASLL.js} +3 -3
  66. package/dist/{cli-FH4WBZHA.js → cli-KJA6GLZI.js} +14 -14
  67. package/dist/{cli-PZ7G544B.js → cli-KNXY43YV.js} +3 -3
  68. package/dist/{cli-QAI6T5FL.js → cli-L54SXUK6.js} +15 -15
  69. package/dist/{cli-3HBYH4VF.js → cli-LLJQI2QP.js} +11 -11
  70. package/dist/{cli-PEY6XZDE.js → cli-LNEZ6KDW.js} +16 -16
  71. package/dist/{cli-GFONBOJT.js → cli-M6AZFIMV.js} +26 -12
  72. package/dist/{cli-YLYB4ITF.js → cli-MDVC5ZNM.js} +13 -13
  73. package/dist/{cli-SWUAXVIJ.js → cli-MGZYQDCH.js} +15 -15
  74. package/dist/{cli-5SYPXJCB.js → cli-MUOLHQNL.js} +14 -14
  75. package/dist/{cli-ZSKP2IRP.js → cli-NAZTYKZT.js} +11 -11
  76. package/dist/{cli-L4DEEAMK.js → cli-NQSL2CIH.js} +17 -17
  77. package/dist/{cli-BC4KKNLA.js → cli-O5WYATAI.js} +1 -1
  78. package/dist/{cli-K6M6YB67.js → cli-OTBCA54D.js} +1 -1
  79. package/dist/{cli-IVZ7AHUJ.js → cli-OXLOGXT3.js} +3 -3
  80. package/dist/{cli-66AHBZRZ.js → cli-OXU6TTEN.js} +15 -15
  81. package/dist/{cli-NU4SCD5D.js → cli-P3NUTOPK.js} +1 -1
  82. package/dist/{cli-7GJGFILU.js → cli-PBSLPO6G.js} +15 -15
  83. package/dist/{cli-4EMNCU63.js → cli-PTXOKO2Y.js} +17 -17
  84. package/dist/{cli-726NJARI.js → cli-PXQYY6KM.js} +0 -0
  85. package/dist/{cli-5P66N5G6.js → cli-PYAST3G5.js} +17 -17
  86. package/dist/{cli-7V6GUIIS.js → cli-QDBYFITU.js} +2 -2
  87. package/dist/{cli-QAVLRCQ5.js → cli-QTCTWYCM.js} +3 -3
  88. package/dist/{cli-MJ65PIYI.js → cli-QW7VXL2V.js} +15 -15
  89. package/dist/cli-RFAPPYXK.js +36 -0
  90. package/dist/{cli-6BAZE75K.js → cli-RSF5R3HC.js} +18 -18
  91. package/dist/{cli-FV45UZQP.js → cli-RUEPTOWG.js} +19 -19
  92. package/dist/{cli-PPEB3ENS.js → cli-SOO6SEIS.js} +18 -18
  93. package/dist/{cli-DMKRP33X.js → cli-TCQJL2GY.js} +1 -1
  94. package/dist/{cli-DT756M3Z.js → cli-TDLIPYKT.js} +20 -20
  95. package/dist/{cli-7S4G4EKK.js → cli-UEQMK4WX.js} +1 -1
  96. package/dist/{cli-UZCQL6YP.js → cli-UQC46YSV.js} +3 -3
  97. package/dist/{cli-MPU4FLA7.js → cli-URCHZDTS.js} +4 -4
  98. package/dist/{cli-42ZUP4X3.js → cli-UULZSQBV.js} +3 -3
  99. package/dist/{cli-4B5OBHSY.js → cli-VALLLE6Y.js} +19 -19
  100. package/dist/{cli-KH6FKM5A.js → cli-VZVHS5AP.js} +15 -15
  101. package/dist/{cli-UR63LFVK.js → cli-W3RG2MRI.js} +2 -2
  102. package/dist/{cli-VQ4OJ4KE.js → cli-WG7MAOCS.js} +18 -18
  103. package/dist/{cli-W7Y7X3FX.js → cli-WLSACMYA.js} +19 -19
  104. package/dist/{cli-JA6UFTSX.js → cli-WOFYI7HZ.js} +17 -17
  105. package/dist/{cli-VTLFQHDO.js → cli-WW54THXN.js} +1 -1
  106. package/dist/cli-WZNIW6ZO.js +16 -0
  107. package/dist/{cli-OUFXSQOW.js → cli-X64BNBQH.js} +26 -4
  108. package/dist/{cli-6FVHRL3H.js → cli-XB5PI2XT.js} +19 -19
  109. package/dist/cli-XEEOJGBL.js +36 -0
  110. package/dist/{cli-D3CZRXVJ.js → cli-XKAIDYIE.js} +14 -14
  111. package/dist/{cli-SPKPDXWD.js → cli-XR3O2YTV.js} +15 -15
  112. package/dist/{cli-3VV2JLHX.js → cli-XW3JLRSA.js} +1 -1
  113. package/dist/{cli-N5K2KHPR.js → cli-YFLQ7XOO.js} +15 -15
  114. package/dist/{cli-DPFN2LIZ.js → cli-YZJBFKRI.js} +15 -15
  115. package/dist/{cli-5FRKWNVP.js → cli-Z3DITVBE.js} +19 -19
  116. package/dist/{cli-E665NKUQ.js → cli-ZJW6HQ6N.js} +5 -5
  117. package/dist/{cli-Y33ULHYO.js → cli-ZNQBF4Z3.js} +1 -1
  118. package/dist/cli.js +52 -52
  119. package/dist/client.js +84 -9
  120. package/dist/dev/console/assets/{index-CVNjiRUh.js → index-Ch6HHb2T.js} +1 -1
  121. package/dist/dev/console/index.html +1 -1
  122. package/dist/dev/surfaces.d.ts +8 -2
  123. package/dist/docs/api/sdk.md +2 -0
  124. package/dist/docs/changelog.md +20 -0
  125. package/dist/docs/cli-error-codes.md +41 -39
  126. package/dist/docs/cli-reference.md +2 -1
  127. package/dist/docs/guides/scenario-editor.md +1 -1
  128. package/dist/docs/guides/setup.md +67 -10
  129. package/dist/docs/page-index.md +5 -4
  130. package/dist/docs/recipes/create-setup.md +18 -10
  131. package/dist/docs/recipes/give-setup-a-menu.md +96 -0
  132. package/dist/docs/recipes/index.md +1 -0
  133. package/dist/docs/recipes/write-setup-notes.md +13 -14
  134. package/dist/host/protocol.d.ts +8 -5
  135. package/dist/playwright.js +84 -9
  136. package/dist/runtime/manifest-version.d.ts +1 -1
  137. package/dist/runtime.js +1 -1
  138. package/dist/schema.json +20 -0
  139. package/dist/utils/error-codes.d.ts +6 -2
  140. package/package.json +3 -3
  141. package/dist/cli-5CG6BMCY.js +0 -36
  142. package/dist/cli-BQ3FHENQ.js +0 -16
  143. package/dist/cli-C2XDL4LD.js +0 -30
  144. package/dist/cli-MM2ROZWO.js +0 -36
  145. package/dist/cli-SN7D7HTX.js +0 -36
  146. package/dist/cli-TJNLXQJ5.js +0 -36
  147. package/dist/cli-V7L3HEL4.js +0 -36
  148. package/dist/cli-XPJGW375.js +0 -36
@@ -5,7 +5,7 @@
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
6
  <link rel="icon" type="image/svg+xml" href="/assets/icon-CRaj5uhr.svg" />
7
7
  <title>Serious Gaming</title>
8
- <script type="module" crossorigin src="/assets/index-CVNjiRUh.js"></script>
8
+ <script type="module" crossorigin src="/assets/index-Ch6HHb2T.js"></script>
9
9
  <link rel="stylesheet" crossorigin href="/assets/index-q6-lvlN3.css">
10
10
  </head>
11
11
  <body>
@@ -32,10 +32,16 @@ export interface MountableSurface {
32
32
  /** Whether it may ask for every team's roster (§6.3, §12.5). */
33
33
  crossTeamParticipants: boolean;
34
34
  /**
35
- * Settings resources it is sent (§8): those it lists in `settings`, or for
36
- * the setup UI and the scenario editor, those it `configures`.
35
+ * Settings resources it is sent (§8): those it lists in `settings`, and
36
+ * for the setup UI and the scenario editor, those it `configures` too.
37
37
  */
38
38
  settings: string[];
39
+ /**
40
+ * For the setup UI and the scenario editor, the settings resources it may
41
+ * change (§6.5), sent beside `setSettings` because what it is sent also
42
+ * holds the settings it only reads. Absent for every other surface.
43
+ */
44
+ configures?: string[];
39
45
  }
40
46
  /** URL prefix each surface kind is served under. */
41
47
  export declare const SURFACE_PREFIX: Record<SurfaceKind, string>;
@@ -1014,6 +1014,7 @@ Definition of the game's scenario editor: an authoring screen, used at any time
1014
1014
  interface ScenarioEditorDefinition {
1015
1015
  identifier: string;
1016
1016
  configures?: string[];
1017
+ settings?: string[];
1017
1018
  endpoints?: string[];
1018
1019
  }
1019
1020
  ```
@@ -1428,6 +1429,7 @@ Definition of the game's setup user interface: a small form shown at session cre
1428
1429
  interface SetupDefinition {
1429
1430
  identifier: string;
1430
1431
  configures?: string[];
1432
+ settings?: string[];
1431
1433
  endpoints?: string[];
1432
1434
  }
1433
1435
  ```
@@ -31,6 +31,26 @@ are in the [0.x changelog](changelog-0.x.md).
31
31
 
32
32
  ## [Unreleased]
33
33
 
34
+ ## [1.10.0] — 2026-11-07
35
+
36
+ ### Added
37
+
38
+ - **A setup screen or scenario editor can read settings it does not configure.** List them in the bundle's new `settings`, as every other resource does: the screen receives their resolved values beside the ones it configures, and cannot change them. A setup menu whose choices depend on the scenario can now show only what the scenario offers, rather than letting a facilitator choose an option that is refused at Play. `useSettingsEditor().configures` still names only what the screen may change. The build fails on a settings resource the package does not declare, and warns on one listed in both `configures` and `settings` (`EDITOR_SETTINGS_CONFIGURED`). `examples/factory`'s setup reads `engine` and `ui` to disable a market nobody would buy in. See [Read settings you do not configure](guides/setup.md#read-settings-you-do-not-configure)
39
+
40
+ ### Fixed
41
+
42
+ - **Setup notes are no longer warned for naming where the menu's offer comes from.** A setting your setup screen lists in `settings` may be named in your notes without `SETUP_NOTES_UNCONFIGURED`, which now warns only on a setting the screen neither configures nor reads
43
+
44
+ ## [1.9.0] — 2026-11-07
45
+
46
+ ### Added
47
+
48
+ - **[Give setup a menu](recipes/give-setup-a-menu.md).** Whatever your setup screen `configures`, an AI assistant setting a session up can change, every value of it, so a setup that configures `engine` to offer two choices hands over every engine setting. Put the choices in a settings resource of their own, each an `enum`, a `boolean` or an array of an `enum` with a `title` and a `description`, configure that alone, and let your logic decide what each choice means. The recipe moves an existing setup over, and the [setup guide](guides/setup.md#give-setup-a-menu-of-its-own) explains the design. `examples/factory` now does this: its setup offers the number of rounds and a `Market` choice, and no longer edits `engine` directly
49
+
50
+ ### Changed
51
+
52
+ - **Setup notes describe your menu, and nothing beyond it.** Name only settings your setup screen configures, with the values their schemas allow, and say which requests need a scenario instead, rather than translating a request such as 'harder' into settings setup cannot change. The [recipe](recipes/write-setup-notes.md) and the [setup guide](guides/setup.md#notes-for-assistants) are rewritten to match, and [Create a setup screen](recipes/create-setup.md) now builds a menu
53
+
34
54
  ## [1.8.0] — 2026-11-06
35
55
 
36
56
  ### Added
@@ -12,7 +12,7 @@ The codes are the contract: branch on the code, never on the message. A code is
12
12
  | --------- | ------------- | ------------------- | ----- |
13
13
  | 1 | `internal` | Internal error | 1 |
14
14
  | 2 | `usage` | Usage error | 16 |
15
- | 3 | `package` | Invalid package | 35 |
15
+ | 3 | `package` | Invalid package | 36 |
16
16
  | 4 | `refused` | Refused by the game | 12 |
17
17
  | 5 | `environment` | Environment | 19 |
18
18
 
@@ -49,43 +49,44 @@ A code marked as a diagnostic also appears in a failure's `diagnostics`, one fin
49
49
 
50
50
  ### Exit 3: invalid package
51
51
 
52
- | Code | When | Also a diagnostic |
53
- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
54
- | `PACKAGE_INVALID` | The package fails validation. The diagnostics say where. As a diagnostic code, a finding no finer code describes yet. | Yes |
55
- | `MANIFEST_NOT_FOUND` | There is no seriousgaming.sdk.json (or package.json) where the command looked. | |
56
- | `MANIFEST_INVALID` | seriousgaming.sdk.json or package.json cannot be read, or is not valid. | |
57
- | `BUNDLE_INVALID` | A resource's bundle file (such as engine.sdk.json) cannot be read, or is not valid. | |
58
- | `LOGIC_NODE_BUILTIN` | Game logic imports a Node built-in, which is absent in production: logic runs on the JavaScript language alone. | Yes |
59
- | `LOGIC_BUNDLE_FAILED` | A logic file does not bundle: a syntax error, or an import that does not resolve. | Yes |
60
- | `SCHEMA_INVALID` | A bundle or the manifest does not match the SDK's schema. The diagnostic's pointer names the value. | Yes |
61
- | `JSON_INVALID` | A bundle file is not valid JSON. | Yes |
62
- | `BUNDLE_MISSING` | A resource directory holds no bundle file. | Yes |
63
- | `REMOVED_FIELD` | A bundle or the manifest carries a field the SDK no longer reads. The hint says what replaced it. | Yes |
64
- | `LAYOUT_OUTDATED` | A directory or bundle file sits where an earlier version of the SDK kept it. The hint says where it goes now. | Yes |
65
- | `FEATURE_UNSUPPORTED` | The manifest's `requires` names an optional feature this version of the SDK does not support. | Yes |
66
- | `FEATURE_UNDECLARED` | The package uses an optional feature its manifest's `requires` does not list, so a runtime without the feature would run it with part of it missing. | Yes |
67
- | `REFERENCE_UNKNOWN` | A `reads`, `writes`, `settings`, `configures` or `endpoints` entry names something the package does not declare. | Yes |
68
- | `SETTINGS_UNKNOWN` | A scenario overrides a settings resource the package does not declare. | Yes |
69
- | `SETTINGS_UNKNOWN_KEY` | A scenario overrides a key that its settings resource does not declare. | Yes |
70
- | `SETTINGS_INVALID` | A scenario's override does not match its settings resource's schema. | Yes |
71
- | `SETTINGS_RESERVED` | A settings resource is named `game`, which is reserved for the built-in game settings. | Yes |
72
- | `SETTINGS_LOCKED` | A scenario overrides a setting the game locks with `readOnly`, in its settings schema or its `gameSettingsConstraints`. | Yes |
73
- | `GAME_CONSTRAINT_INVALID` | A `gameSettingsConstraints` entry widens the SDK schema for the `game` settings rather than narrowing it. | Yes |
74
- | `GAME_CONSTRAINT_VIOLATED` | The game's own value for a `game` setting breaks its `gameSettingsConstraints`. | Yes |
75
- | `LOGIC_EXPORT_MISSING` | A logic file is missing, or does not export the functions its resource needs. | Yes |
76
- | `READ_NEVER_WRITTEN` | A warning: a resource reads a capability nothing in the package writes, so it only ever holds its defaults. | Yes |
77
- | `NO_TERMINATION` | A warning: the game declares neither `maxTicks` nor a tick controller, so only its engine can end it. | Yes |
78
- | `SCENARIO_EDITOR_UNREACHABLE` | A warning: the game ships a scenario editor but does not set `customScenarios.supported`, so no host ever opens it. | Yes |
79
- | `SCENARIO_REFUSED` | A validator's `Scenario` gate found a problem with a package scenario, or with the defaults when no scenario is the default. The diagnostic points at the setting it names. | Yes |
80
- | `SCENARIO_WARNING` | A warning: a validator's `Scenario` gate marked a problem with a package scenario, or with the defaults, as a `warning`. It is reported and never fails the build. | Yes |
81
- | `SETUP_NOTES_UNCONFIGURED` | A warning: the setup notes name a setting the setup UI does not `configures`, so a host refuses the change they describe. | Yes |
82
- | `SETTINGS_UNGATED` | A warning: the setup UI `configures` a settings resource no `Scenario` gate declares, so nothing checks what a facilitator changes in it before the session starts. | Yes |
83
- | `EDITOR_ENDPOINT_NOT_SCENARIO` | The scenario editor lists an endpoint that is not scenario-scoped. It works on a scenario draft with no session, so it calls `"scope": "scenario"` endpoints alone. | Yes |
84
- | `SCENARIO_ENDPOINT_STATEFUL` | A scenario-scoped endpoint declares `reads`, `writes`, `actions` or `roster`, which need a session a scenario draft does not have. | Yes |
85
- | `EXTERNAL_REQUEST_NOT_OBJECT` | An external endpoint's `requestSchema` does not declare `"type": "object"` at the top, which a caller outside the game needs to pass named arguments. | Yes |
86
- | `ENDPOINT_UNREQUESTED` | A warning: an internal endpoint no user interface lists in its `endpoints`. | Yes |
87
- | `PLATFORM_REJECTED` | The platform refused the uploaded package as invalid. | |
88
- | `VERSION_EXISTS` | The platform already has this version of the package. Bump it and publish again. | |
52
+ | Code | When | Also a diagnostic |
53
+ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
54
+ | `PACKAGE_INVALID` | The package fails validation. The diagnostics say where. As a diagnostic code, a finding no finer code describes yet. | Yes |
55
+ | `MANIFEST_NOT_FOUND` | There is no seriousgaming.sdk.json (or package.json) where the command looked. | |
56
+ | `MANIFEST_INVALID` | seriousgaming.sdk.json or package.json cannot be read, or is not valid. | |
57
+ | `BUNDLE_INVALID` | A resource's bundle file (such as engine.sdk.json) cannot be read, or is not valid. | |
58
+ | `LOGIC_NODE_BUILTIN` | Game logic imports a Node built-in, which is absent in production: logic runs on the JavaScript language alone. | Yes |
59
+ | `LOGIC_BUNDLE_FAILED` | A logic file does not bundle: a syntax error, or an import that does not resolve. | Yes |
60
+ | `SCHEMA_INVALID` | A bundle or the manifest does not match the SDK's schema. The diagnostic's pointer names the value. | Yes |
61
+ | `JSON_INVALID` | A bundle file is not valid JSON. | Yes |
62
+ | `BUNDLE_MISSING` | A resource directory holds no bundle file. | Yes |
63
+ | `REMOVED_FIELD` | A bundle or the manifest carries a field the SDK no longer reads. The hint says what replaced it. | Yes |
64
+ | `LAYOUT_OUTDATED` | A directory or bundle file sits where an earlier version of the SDK kept it. The hint says where it goes now. | Yes |
65
+ | `FEATURE_UNSUPPORTED` | The manifest's `requires` names an optional feature this version of the SDK does not support. | Yes |
66
+ | `FEATURE_UNDECLARED` | The package uses an optional feature its manifest's `requires` does not list, so a runtime without the feature would run it with part of it missing. | Yes |
67
+ | `REFERENCE_UNKNOWN` | A `reads`, `writes`, `settings`, `configures` or `endpoints` entry names something the package does not declare. | Yes |
68
+ | `SETTINGS_UNKNOWN` | A scenario overrides a settings resource the package does not declare. | Yes |
69
+ | `SETTINGS_UNKNOWN_KEY` | A scenario overrides a key that its settings resource does not declare. | Yes |
70
+ | `SETTINGS_INVALID` | A scenario's override does not match its settings resource's schema. | Yes |
71
+ | `SETTINGS_RESERVED` | A settings resource is named `game`, which is reserved for the built-in game settings. | Yes |
72
+ | `SETTINGS_LOCKED` | A scenario overrides a setting the game locks with `readOnly`, in its settings schema or its `gameSettingsConstraints`. | Yes |
73
+ | `GAME_CONSTRAINT_INVALID` | A `gameSettingsConstraints` entry widens the SDK schema for the `game` settings rather than narrowing it. | Yes |
74
+ | `GAME_CONSTRAINT_VIOLATED` | The game's own value for a `game` setting breaks its `gameSettingsConstraints`. | Yes |
75
+ | `LOGIC_EXPORT_MISSING` | A logic file is missing, or does not export the functions its resource needs. | Yes |
76
+ | `READ_NEVER_WRITTEN` | A warning: a resource reads a capability nothing in the package writes, so it only ever holds its defaults. | Yes |
77
+ | `NO_TERMINATION` | A warning: the game declares neither `maxTicks` nor a tick controller, so only its engine can end it. | Yes |
78
+ | `SCENARIO_EDITOR_UNREACHABLE` | A warning: the game ships a scenario editor but does not set `customScenarios.supported`, so no host ever opens it. | Yes |
79
+ | `SCENARIO_REFUSED` | A validator's `Scenario` gate found a problem with a package scenario, or with the defaults when no scenario is the default. The diagnostic points at the setting it names. | Yes |
80
+ | `SCENARIO_WARNING` | A warning: a validator's `Scenario` gate marked a problem with a package scenario, or with the defaults, as a `warning`. It is reported and never fails the build. | Yes |
81
+ | `SETUP_NOTES_UNCONFIGURED` | A warning: the setup notes name a setting the setup UI neither `configures` nor lists in `settings`, so a host refuses the change they describe and the setup UI cannot see it. | Yes |
82
+ | `EDITOR_SETTINGS_CONFIGURED` | A warning: a settings editor lists a settings resource in both `configures` and `settings`. Configuring a resource already sends it, so the `settings` entry does nothing. | Yes |
83
+ | `SETTINGS_UNGATED` | A warning: the setup UI `configures` a settings resource no `Scenario` gate declares, so nothing checks what a facilitator changes in it before the session starts. | Yes |
84
+ | `EDITOR_ENDPOINT_NOT_SCENARIO` | The scenario editor lists an endpoint that is not scenario-scoped. It works on a scenario draft with no session, so it calls `"scope": "scenario"` endpoints alone. | Yes |
85
+ | `SCENARIO_ENDPOINT_STATEFUL` | A scenario-scoped endpoint declares `reads`, `writes`, `actions` or `roster`, which need a session a scenario draft does not have. | Yes |
86
+ | `EXTERNAL_REQUEST_NOT_OBJECT` | An external endpoint's `requestSchema` does not declare `"type": "object"` at the top, which a caller outside the game needs to pass named arguments. | Yes |
87
+ | `ENDPOINT_UNREQUESTED` | A warning: an internal endpoint no user interface lists in its `endpoints`. | Yes |
88
+ | `PLATFORM_REJECTED` | The platform refused the uploaded package as invalid. | |
89
+ | `VERSION_EXISTS` | The platform already has this version of the package. Bump it and publish again. | |
89
90
 
90
91
  ### Exit 4: refused by the game
91
92
 
@@ -159,7 +160,8 @@ The codes a diagnostic carries. `LOGIC_ERROR` is only ever a diagnostic: it sits
159
160
  | `SCENARIO_REFUSED` | A validator's `Scenario` gate found a problem with a package scenario, or with the defaults when no scenario is the default. The diagnostic points at the setting it names. |
160
161
  | `SCENARIO_WARNING` | A warning: a validator's `Scenario` gate marked a problem with a package scenario, or with the defaults, as a `warning`. It is reported and never fails the build. |
161
162
  | `SETTINGS_UNGATED` | A warning: the setup UI `configures` a settings resource no `Scenario` gate declares, so nothing checks what a facilitator changes in it before the session starts. |
162
- | `SETUP_NOTES_UNCONFIGURED` | A warning: the setup notes name a setting the setup UI does not `configures`, so a host refuses the change they describe. |
163
+ | `SETUP_NOTES_UNCONFIGURED` | A warning: the setup notes name a setting the setup UI neither `configures` nor lists in `settings`, so a host refuses the change they describe and the setup UI cannot see it. |
164
+ | `EDITOR_SETTINGS_CONFIGURED` | A warning: a settings editor lists a settings resource in both `configures` and `settings`. Configuring a resource already sends it, so the `settings` entry does nothing. |
163
165
  | `EDITOR_ENDPOINT_NOT_SCENARIO` | The scenario editor lists an endpoint that is not scenario-scoped. It works on a scenario draft with no session, so it calls `"scope": "scenario"` endpoints alone. |
164
166
  | `SCENARIO_ENDPOINT_STATEFUL` | A scenario-scoped endpoint declares `reads`, `writes`, `actions` or `roster`, which need a session a scenario draft does not have. |
165
167
  | `EXTERNAL_REQUEST_NOT_OBJECT` | An external endpoint's `requestSchema` does not declare `"type": "object"` at the top, which a caller outside the game needs to pass named arguments. |
@@ -237,7 +237,8 @@ Without `--json`, each diagnostic that names a file is printed under the error a
237
237
  | `SCENARIO_REFUSED` | A validator's `Scenario` gate found a problem with a package scenario, or with the defaults when no scenario is the default. The diagnostic points at the setting it names. |
238
238
  | `SCENARIO_WARNING` | A warning: a validator's `Scenario` gate marked a problem with a package scenario, or with the defaults, as a `warning`. It is reported and never fails the build. |
239
239
  | `SETTINGS_UNGATED` | A warning: the setup UI `configures` a settings resource no `Scenario` gate declares, so nothing checks what a facilitator changes in it before the session starts. |
240
- | `SETUP_NOTES_UNCONFIGURED` | A warning: the setup notes name a setting the setup UI does not `configures`, so a host refuses the change they describe. |
240
+ | `SETUP_NOTES_UNCONFIGURED` | A warning: the setup notes name a setting the setup UI neither `configures` nor lists in `settings`, so a host refuses the change they describe and the setup UI cannot see it. |
241
+ | `EDITOR_SETTINGS_CONFIGURED` | A warning: a settings editor lists a settings resource in both `configures` and `settings`. Configuring a resource already sends it, so the `settings` entry does nothing. |
241
242
  | `EDITOR_ENDPOINT_NOT_SCENARIO` | The scenario editor lists an endpoint that is not scenario-scoped. It works on a scenario draft with no session, so it calls `"scope": "scenario"` endpoints alone. |
242
243
  | `SCENARIO_ENDPOINT_STATEFUL` | A scenario-scoped endpoint declares `reads`, `writes`, `actions` or `roster`, which need a session a scenario draft does not have. |
243
244
  | `EXTERNAL_REQUEST_NOT_OBJECT` | An external endpoint's `requestSchema` does not declare `"type": "object"` at the top, which a caller outside the game needs to pass named arguments. |
@@ -67,7 +67,7 @@ pnpm run sdk new scenario_editor '{
67
67
  }'
68
68
  ```
69
69
 
70
- `configures` names the [settings resources](./settings.md) the editor edits, by identifier. It 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), and the build fails if you name a settings resource the package does not declare. Settings the editor does not configure keep the values the scenario starts from. List `game` to let the editor set the scenario's number of rounds and team settings, which it saves under the scenario's `settings.game` (see [The game settings](./settings.md#the-game-settings)). An edit that changes a setting the game locks with `readOnly`, or sets a value outside its schema's range, is refused the same way, and the draft keeps none of it. The editor is sent values, not schemas, so show a locked field as read-only, as the factory example's editor does (see [Lock a setting](./settings.md#lock-a-setting)).
70
+ `configures` names the [settings resources](./settings.md) the editor edits, by identifier. It 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), and the build fails if you name a settings resource the package does not declare. Settings the editor does not configure keep the values the scenario starts from. To show one without letting the editor change it, list it in `settings` instead: the editor receives it resolved under the scenario, read-only (see [Read settings you do not configure](./setup.md#read-settings-you-do-not-configure)). List `game` to let the editor set the scenario's number of rounds and team settings, which it saves under the scenario's `settings.game` (see [The game settings](./settings.md#the-game-settings)). An edit that changes a setting the game locks with `readOnly`, or sets a value outside its schema's range, is refused the same way, and the draft keeps none of it. The editor is sent values, not schemas, so show a locked field as read-only, as the factory example's editor does (see [Lock a setting](./settings.md#lock-a-setting)).
71
71
 
72
72
  ```
73
73
  scenario_editor/
@@ -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,13 +51,67 @@ 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. List that resource in your setup's `settings` so the screen can offer only what is allowed (see [Read settings you do not configure](#read-settings-you-do-not-configure)), and 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
+
91
+ ## Read settings you do not configure
92
+
93
+ A screen sometimes needs to see a setting it must not change, such as the scenario's list of what the menu may offer. List it in `settings`, beside `configures`:
94
+
95
+ ```json
96
+ {
97
+ "definition": {
98
+ "configures": ["game", "setup"],
99
+ "settings": ["engine", "ui"]
100
+ }
101
+ }
102
+ ```
103
+
104
+ The screen receives the resolved values of both lists in `settings` from `useSettingsEditor()`, and the generated `Settings` types them all. Only what it configures can change: an `updateSettings` call naming a resource it only reads is refused, and none of it is applied. `configures` from `useSettingsEditor()` names the resources it may change. The build fails if `settings` names a settings resource the package does not declare, and warns on one listed in both (`EDITOR_SETTINGS_CONFIGURED`), since configuring a resource already sends it.
105
+
106
+ `examples/factory`'s setup reads `engine` and `ui` and disables a market in which nobody would buy at the scenario's lowest price, using the same rule as its `Scenario` gate, so a facilitator never picks a choice that is refused at Play. The scenario editor takes `settings` the same way.
107
+
54
108
  ## Building the form
55
109
 
56
110
  `useSettingsEditor()` returns three things:
57
111
 
58
- - `settings`: the resolved values of the settings this screen configures, keyed by settings identifier
112
+ - `settings`: the resolved values of the settings this screen configures and of those it [reads](#read-settings-you-do-not-configure), keyed by settings identifier
59
113
  - `updateSettings(update)`: merges an update and sends the host only what changed. It returns a promise that rejects with a `MutationError` when the host refuses the write
60
- - `configures`: the identifiers this screen was sent
114
+ - `configures`: the identifiers of the settings this screen may change
61
115
 
62
116
  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
117
 
@@ -153,17 +207,19 @@ The [session UI guide](./session.md#rendering-inside-the-host) covers the same g
153
207
 
154
208
  ## Notes for assistants
155
209
 
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.
210
+ 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.
157
211
 
158
212
  ```markdown
159
213
  ## What requests mean
160
214
 
161
- - **'Harder'**: lower `engine.BaseDemand` to 7,000 and raise `engine.DemandPriceModifier` to 700
215
+ - **'Harder'**: set `setup.Market` to `tougher`
162
216
  - **'Shorter'**: set `game.maxTicks` to 6
217
+ - **Anything else**, such as cheaper materials: setup cannot do it. Suggest a scenario that does
163
218
  ```
164
219
 
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
220
+ - **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
221
+ - **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 neither configures nor lists in `settings` (`SETUP_NOTES_UNCONFIGURED`)
222
+ - **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. List that setting's resource in your setup's `settings`, so the build knows the notes name it to be read. A host may show an assistant your other settings, read-only, for exactly this
167
223
  - **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
224
  - **Locales fall back** from the assistant's locale to `en`, then your first supported locale
169
225
 
@@ -177,7 +233,7 @@ The build ships them as written. In the dev server, **Notes for assistants** on
177
233
 
178
234
  ```bash
179
235
  pnpm run sdk update setup '{
180
- "definition": { "configures": ["engine", "ui"] },
236
+ "definition": { "configures": ["game", "setup"] },
181
237
  "rootDirectory": ".",
182
238
  "ui": { "entrypoint": "index.html" }
183
239
  }'
@@ -208,4 +264,5 @@ See [Test a user interface](../recipes/test-user-interface.md).
208
264
  - [Settings](./settings.md): declaring, reading, and overriding settings
209
265
  - [Scenarios](./scenarios.md)
210
266
  - [Create a setup screen](../recipes/create-setup.md)
267
+ - [Give setup a menu](../recipes/give-setup-a-menu.md)
211
268
  - [Write setup notes for assistants](../recipes/write-setup-notes.md)
@@ -25,7 +25,7 @@ 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 32k characters: Every code a failed `seriousgaming-sdk` command can report.
28
+ - [`cli-error-codes.md`](cli-error-codes.md), about 33k characters: Every code a failed `seriousgaming-sdk` command can report.
29
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.
@@ -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 11k 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 16k 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.
@@ -99,7 +99,7 @@ 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.
@@ -111,6 +111,7 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
111
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.
112
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.
113
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.
114
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.
115
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.
116
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.
@@ -131,7 +132,7 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
131
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.
132
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.
133
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.
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.
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.
135
136
 
136
137
  ## API reference
137
138
 
@@ -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,7 +48,7 @@ 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, Stack, TextField } from '@mui/material';
51
+ import { Button, MenuItem, Stack, TextField } from '@mui/material';
52
52
  import { useSettingsEditor, useSettingsEditorCallbacks } from '@seriousgaming/sdk/ui';
53
53
 
54
54
  import type { Settings } from '../types';
@@ -60,15 +60,22 @@ function App() {
60
60
  return (
61
61
  <Stack spacing={2}>
62
62
  <TextField
63
- label="Base demand"
64
- type="number"
65
- value={settings.engine.BaseDemand}
63
+ select
64
+ label="Market"
65
+ value={settings.setup.Market}
66
66
  onChange={(e) =>
67
67
  void updateSettings({
68
- engine: { ...settings.engine, BaseDemand: Number(e.target.value) },
68
+ setup: {
69
+ ...settings.setup,
70
+ Market: e.target.value as Settings['setup']['Market'],
71
+ },
69
72
  })
70
73
  }
71
- />
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>
72
79
  <Button variant="contained" onClick={() => requestPlay()}>
73
80
  Start game
74
81
  </Button>
@@ -93,7 +100,7 @@ The dev server opens on `/setup`.
93
100
 
94
101
  - [ ] The form shows each setting's resolved value
95
102
  - [ ] Changing a value and pressing Start (or the host's Play) starts the session with that value
96
- - [ ] `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
97
104
 
98
105
  ## Troubleshooting
99
106
 
@@ -115,3 +122,4 @@ The configuration step exists only when the package has a `setup/setup.sdk.json`
115
122
  - [Create a scenario editor](create-scenario-editor.md)
116
123
  - [Use requestPlay in a setup screen](use-request-play.md)
117
124
  - [Create a settings resource](create-settings.md)
125
+ - [Give setup a menu](give-setup-a-menu.md)
@@ -0,0 +1,96 @@
1
+ # Give setup a menu
2
+
3
+ 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.
4
+
5
+ **Keywords:** setup menu, quick config, setup screen, configures, AI assistant, agent setup, difficulty, session setup, restrict setup, settings resource
6
+
7
+ ## What you'll build
8
+
9
+ A settings resource at `settings/setup/` holding only your setup's choices, a setup screen that configures it instead of `engine`, and an engine that works out what each choice means. Today, a setup that configures `engine` lets an assistant change every engine setting, even the ones your screen never shows. See [Give setup a menu of its own](../guides/setup.md#give-setup-a-menu-of-its-own) for the reasoning.
10
+
11
+ ## Prerequisites
12
+
13
+ - A [setup screen](create-setup.md) that configures one of your game's other settings resources, such as `engine`
14
+ - `seriousgaming.sdk.json` in your working directory
15
+
16
+ ## Steps
17
+
18
+ 1. List what your setup screen offers. For each control, decide the choice a facilitator makes rather than the value it writes: 'easier, standard or harder' rather than 'game level from 1 to 10'
19
+
20
+ 2. Create the menu. Make each choice an `enum`, a `boolean`, or an array of an `enum`, with a `title`, a `description` and a `default`:
21
+
22
+ ```bash
23
+ pnpm run sdk new settings '{
24
+ "definition": {
25
+ "identifier": "setup",
26
+ "settingsSchema": {
27
+ "type": "object",
28
+ "properties": {
29
+ "Market": {
30
+ "title": "Market",
31
+ "description": "How forgiving the market is, compared with the scenario. standard plays the scenario as written",
32
+ "type": "string",
33
+ "enum": ["gentler", "standard", "tougher"],
34
+ "default": "standard"
35
+ }
36
+ },
37
+ "additionalProperties": false
38
+ }
39
+ }
40
+ }'
41
+ ```
42
+
43
+ 3. Point setup at the menu. Keep `game` if your screen sets the number of rounds:
44
+
45
+ ```bash
46
+ pnpm run sdk update setup --patch '[{ "op": "replace", "path": "/definition/configures", "value": ["game", "setup"] }]'
47
+ ```
48
+
49
+ 4. Let the engine read the menu. Add `setup` to its `settings`, and to the `settings` of any endpoint or validator whose answer the choice changes:
50
+
51
+ ```bash
52
+ pnpm run sdk update engine --patch '[{ "op": "add", "path": "/definition/settings/-", "value": "setup" }]'
53
+ ```
54
+
55
+ 5. Work out what each choice means in the engine, relative to the scenario so the two never clash:
56
+
57
+ ```typescript
58
+ const engine =
59
+ settings.setup.Market === 'tougher'
60
+ ? { ...settings.engine, BaseDemand: Math.round(settings.engine.BaseDemand * 0.7) }
61
+ : settings.engine;
62
+ ```
63
+
64
+ 6. Rewrite the setup screen's controls to write the menu with `updateSettings({ setup: { ... } })`, and remove any control for a setting the menu does not hold
65
+
66
+ 7. Where what the menu offers depends on the scenario, such as an aid only some scenarios allow, keep that list in your other settings, where only a scenario can set it. List that resource in the setup's `settings`, so the screen can hide or disable a choice the scenario does not allow:
67
+
68
+ ```bash
69
+ pnpm run sdk update setup --patch '[{ "op": "add", "path": "/definition/settings", "value": ["ui"] }]'
70
+ ```
71
+
72
+ Say where it is in the menu setting's `description`, and refuse a choice the scenario does not allow in a [Scenario gate](validate-scenarios.md) that declares `setup` in its `settings`. List `session-validation` in `requires` so the gate runs as each session starts
73
+
74
+ 8. Rewrite your [setup notes](write-setup-notes.md), if you have them, to name the menu's settings and say which requests need a scenario instead
75
+
76
+ 9. Add `setup` to the scenario editor's `configures` if authors should choose a scenario's defaults for the menu
77
+
78
+ ## Verify
79
+
80
+ - `pnpm run generate`, then `pnpm run typecheck`: every hand-built `Settings` in your tests now needs a `setup` entry, such as `setup: defaultSettings.setup`
81
+ - `pnpm run sdk build --validate-only` passes with no `SETUP_NOTES_UNCONFIGURED` warning
82
+ - Write `{ "setup": { "Market": "tougher" } }` to `settings.json`, run `pnpm run sdk configure -f settings.json`, then `pnpm run sdk tick`: the engine acts on the choice
83
+ - `pnpm run sdk configure` still accepts an `engine` value, since the command line is your own authoring tool. On a host, an assistant setting a session up is refused one
84
+
85
+ ## Troubleshooting
86
+
87
+ - _`SETTINGS_UNGATED` on `setup`_: no `Scenario` gate reads the menu. Fine when every choice is safe on every scenario; otherwise add `setup` to the gate's `settings` and check it there
88
+ - _A scenario plays differently after the move_: the menu's default must mean 'as the scenario sets it'. Make the default choice change nothing
89
+ - _The setup screen shows no choice selected_: an old session override still names an `engine` setting. Reconfigure the session, or delete `.seriousgaming-sdk/configuration.json`
90
+
91
+ ## Related
92
+
93
+ - [Setup guide: give setup a menu of its own](../guides/setup.md#give-setup-a-menu-of-its-own)
94
+ - [Create a setup screen](create-setup.md)
95
+ - [Write setup notes for assistants](write-setup-notes.md)
96
+ - [Validate a game's scenarios](validate-scenarios.md)
@@ -34,6 +34,7 @@ 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
+ - [Give setup a menu](give-setup-a-menu.md): keep what setup can change to the choices it offers, so an assistant changes nothing else
37
38
  - [Write setup notes for assistants](write-setup-notes.md): tell an AI assistant which settings matter and what requests such as 'harder' mean
38
39
  - [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
39
40
  - [Create a scenario editor](create-scenario-editor.md): a screen for building new scenarios for a released game