@seriousgaming/sdk-tools 1.9.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 (146) hide show
  1. package/dist/{cli-KJV3GGBA.js → cli-226ZJ72R.js} +1 -1
  2. package/dist/{cli-VRGVHSXH.js → cli-25SJZI7N.js} +44 -9
  3. package/dist/{cli-OK6XWVIN.js → cli-267QJ2DS.js} +17 -17
  4. package/dist/cli-27Z5T52R.js +30 -0
  5. package/dist/{cli-H7T6E7OA.js → cli-2AH6D32V.js} +2 -2
  6. package/dist/{cli-A3P3PO6Z.js → cli-2ANX6E3A.js} +15 -15
  7. package/dist/{cli-J75EBRAJ.js → cli-2AVPNSAX.js} +17 -17
  8. package/dist/{cli-6COAU7JR.js → cli-33MZSPPK.js} +17 -17
  9. package/dist/{cli-USBJQAYI.js → cli-35GV2F6R.js} +13 -13
  10. package/dist/{cli-BYXNPBVG.js → cli-36GABN2A.js} +15 -15
  11. package/dist/{cli-DXHPYN4N.js → cli-44CM2AH2.js} +1 -1
  12. package/dist/{cli-BV7MX7JE.js → cli-467VRXGP.js} +3 -3
  13. package/dist/{cli-OOTGO3KW.js → cli-4A7RWFNO.js} +49 -49
  14. package/dist/{cli-6GDPO5VU.js → cli-4FJL3KQZ.js} +2 -2
  15. package/dist/{cli-CL3KF5KS.js → cli-4JNF3O5N.js} +2 -2
  16. package/dist/{cli-BT47H36C.js → cli-5DWR7RPQ.js} +2 -2
  17. package/dist/{cli-AA5GMEUL.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-XA4IL7IM.js → cli-5RRPUL6V.js} +11 -11
  21. package/dist/{cli-PJO4BKSV.js → cli-5SHG2M7E.js} +16 -16
  22. package/dist/{cli-LZFUSEJT.js → cli-5TKPT3CY.js} +13 -13
  23. package/dist/{cli-YI3WZF3C.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-G7JTIP5G.js → cli-6BLVI2JM.js} +11 -7
  28. package/dist/{cli-S3YIYAXC.js → cli-6CYAOUYT.js} +12 -12
  29. package/dist/{cli-7OCEVQQN.js → cli-6O7YCK2M.js} +2 -2
  30. package/dist/{cli-IC5FOT2J.js → cli-7JUNA74L.js} +1 -1
  31. package/dist/{cli-CPX4YA3P.js → cli-7NUFHMGE.js} +11 -11
  32. package/dist/{cli-GZE4V7RC.js → cli-A3AJQZEN.js} +19 -19
  33. package/dist/{cli-2FXZZLCL.js → cli-AH6AMAIB.js} +1 -1
  34. package/dist/{cli-QWO3XJR3.js → cli-ATWJCB2G.js} +4 -4
  35. package/dist/{cli-MN7X4UG2.js → cli-B3EFE7ZF.js} +1 -1
  36. package/dist/{cli-3RMP4HKZ.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-A7PITFRR.js → cli-CLO7HKEQ.js} +2 -2
  42. package/dist/{cli-2BF7KBBJ.js → cli-CQ4ZR3ZQ.js} +15 -15
  43. package/dist/{cli-KINJAQTJ.js → cli-EXUPHPDJ.js} +19 -19
  44. package/dist/{cli-2JEICVMA.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-4L7S27XO.js → cli-GO64NABP.js} +1 -1
  48. package/dist/{cli-QK2OD24J.js → cli-GRSQRFRG.js} +1 -1
  49. package/dist/{cli-XRVH5WV6.js → cli-GSOV26O5.js} +13 -13
  50. package/dist/{cli-6Y4XIVQS.js → cli-HGCOEL5T.js} +3 -3
  51. package/dist/{cli-R6YAZP6E.js → cli-HHRP6FP6.js} +19 -19
  52. package/dist/{cli-TLRTLTGK.js → cli-HN442ZVK.js} +18 -18
  53. package/dist/{cli-7CW2BBJG.js → cli-HNDFANQG.js} +1 -1
  54. package/dist/{cli-CKV44U7P.js → cli-HNG6PZW2.js} +19 -19
  55. package/dist/cli-I3ZAZYWP.js +36 -0
  56. package/dist/{cli-MSSJLABW.js → cli-IKSLPAZN.js} +3 -3
  57. package/dist/{cli-DJCQ5XFR.js → cli-ILHHJR2S.js} +15 -15
  58. package/dist/{cli-D6AC3ZCX.js → cli-IPTHJT3J.js} +18 -18
  59. package/dist/{cli-2VV5IPSY.js → cli-IQBY7Z7Q.js} +15 -15
  60. package/dist/{cli-IJPRZSJ5.js → cli-J42N4PJG.js} +20 -20
  61. package/dist/{cli-6KL5B7EC.js → cli-JAVMRERQ.js} +15 -15
  62. package/dist/{cli-AJ5CABGJ.js → cli-JHLWBRXB.js} +15 -15
  63. package/dist/{cli-7RLZIWFP.js → cli-JMNPMDXH.js} +19 -19
  64. package/dist/{cli-5PTCQTS6.js → cli-JXQLHJO2.js} +1 -1
  65. package/dist/{cli-WJO75KP7.js → cli-KIZTASLL.js} +3 -3
  66. package/dist/{cli-MX7GFQ6N.js → cli-KJA6GLZI.js} +14 -14
  67. package/dist/{cli-RL5EBZL7.js → cli-KNXY43YV.js} +3 -3
  68. package/dist/{cli-L5ZKQNMI.js → cli-L54SXUK6.js} +15 -15
  69. package/dist/{cli-ZHFHOWJI.js → cli-LLJQI2QP.js} +11 -11
  70. package/dist/{cli-NTI22MRE.js → cli-LNEZ6KDW.js} +16 -16
  71. package/dist/{cli-KO26S2CL.js → cli-M6AZFIMV.js} +26 -12
  72. package/dist/{cli-BNN36WZJ.js → cli-MDVC5ZNM.js} +13 -13
  73. package/dist/{cli-JEMWAIAA.js → cli-MGZYQDCH.js} +15 -15
  74. package/dist/{cli-35K37SYY.js → cli-MUOLHQNL.js} +14 -14
  75. package/dist/{cli-2UOUIVHW.js → cli-NAZTYKZT.js} +11 -11
  76. package/dist/{cli-LFUKHLHI.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-5BPQ73OM.js → cli-OXU6TTEN.js} +15 -15
  81. package/dist/{cli-NU4SCD5D.js → cli-P3NUTOPK.js} +1 -1
  82. package/dist/{cli-E77R7ZYB.js → cli-PBSLPO6G.js} +15 -15
  83. package/dist/{cli-OX3254NS.js → cli-PTXOKO2Y.js} +17 -17
  84. package/dist/{cli-7N7WFRWA.js → cli-PXQYY6KM.js} +0 -0
  85. package/dist/{cli-HCMVZXWK.js → cli-PYAST3G5.js} +17 -17
  86. package/dist/{cli-7V6GUIIS.js → cli-QDBYFITU.js} +2 -2
  87. package/dist/{cli-W4BHSBAX.js → cli-QTCTWYCM.js} +3 -3
  88. package/dist/{cli-QIHVXDMW.js → cli-QW7VXL2V.js} +15 -15
  89. package/dist/cli-RFAPPYXK.js +36 -0
  90. package/dist/{cli-KD2RQS35.js → cli-RSF5R3HC.js} +18 -18
  91. package/dist/{cli-YD4SBAHQ.js → cli-RUEPTOWG.js} +19 -19
  92. package/dist/{cli-G54355N5.js → cli-SOO6SEIS.js} +18 -18
  93. package/dist/{cli-DMKRP33X.js → cli-TCQJL2GY.js} +1 -1
  94. package/dist/{cli-MYBDWJP7.js → cli-TDLIPYKT.js} +20 -20
  95. package/dist/{cli-2CSI2UU2.js → cli-UEQMK4WX.js} +1 -1
  96. package/dist/{cli-2I6UN6C3.js → cli-UQC46YSV.js} +3 -3
  97. package/dist/{cli-GHQIATHP.js → cli-URCHZDTS.js} +4 -4
  98. package/dist/{cli-BF6L37O3.js → cli-UULZSQBV.js} +3 -3
  99. package/dist/{cli-CQUSM3SF.js → cli-VALLLE6Y.js} +19 -19
  100. package/dist/{cli-MTAGL3QE.js → cli-VZVHS5AP.js} +15 -15
  101. package/dist/{cli-UR63LFVK.js → cli-W3RG2MRI.js} +2 -2
  102. package/dist/{cli-RHYQYXE2.js → cli-WG7MAOCS.js} +18 -18
  103. package/dist/{cli-KGJHEDR2.js → cli-WLSACMYA.js} +19 -19
  104. package/dist/{cli-SBKTGFY4.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-ZZSPFLTK.js → cli-X64BNBQH.js} +26 -4
  108. package/dist/{cli-MZM4MW7C.js → cli-XB5PI2XT.js} +19 -19
  109. package/dist/cli-XEEOJGBL.js +36 -0
  110. package/dist/{cli-EDZF5Q2E.js → cli-XKAIDYIE.js} +14 -14
  111. package/dist/{cli-2PMLR6WG.js → cli-XR3O2YTV.js} +15 -15
  112. package/dist/{cli-3VV2JLHX.js → cli-XW3JLRSA.js} +1 -1
  113. package/dist/{cli-S7PLSPGE.js → cli-YFLQ7XOO.js} +15 -15
  114. package/dist/{cli-B5LZEFLU.js → cli-YZJBFKRI.js} +15 -15
  115. package/dist/{cli-ICLCA6VD.js → cli-Z3DITVBE.js} +19 -19
  116. package/dist/{cli-QRAYIXNE.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 +10 -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 +22 -5
  129. package/dist/docs/page-index.md +2 -2
  130. package/dist/docs/recipes/give-setup-a-menu.md +7 -1
  131. package/dist/docs/recipes/write-setup-notes.md +2 -2
  132. package/dist/host/protocol.d.ts +8 -5
  133. package/dist/playwright.js +84 -9
  134. package/dist/runtime/manifest-version.d.ts +1 -1
  135. package/dist/runtime.js +1 -1
  136. package/dist/schema.json +20 -0
  137. package/dist/utils/error-codes.d.ts +6 -2
  138. package/package.json +3 -3
  139. package/dist/cli-3I6AI4AA.js +0 -36
  140. package/dist/cli-3YGNWZC6.js +0 -30
  141. package/dist/cli-4X3X4HB2.js +0 -16
  142. package/dist/cli-6ZBQELF2.js +0 -36
  143. package/dist/cli-CUZUIYCQ.js +0 -36
  144. package/dist/cli-DNCJURUU.js +0 -36
  145. package/dist/cli-UKC7KXWU.js +0 -36
  146. package/dist/cli-WA2PDQUB.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,16 @@ 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
+
34
44
  ## [1.9.0] — 2026-11-07
35
45
 
36
46
  ### 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/
@@ -81,20 +81,37 @@ So put the choices your setup offers in a settings resource of their own, a menu
81
81
  - **Give each a `title` and a `description`.** An assistant shows them to the facilitator when it confirms a choice
82
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
83
  - **A scenario sets the menu's defaults** by setting the menu resource, like any other setting. Add the menu to the scenario editor's `configures` to let an author choose them
84
- - **Keep what the menu offers per scenario in your other settings.** When a choice is only available in some scenarios, such as an aid a scenario may or may not allow, the list of what is allowed belongs in a settings resource setup does not configure. Say where it is in the menu setting's `description` and in your [notes for assistants](#notes-for-assistants)
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
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
86
 
87
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
88
 
89
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
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
+
91
108
  ## Building the form
92
109
 
93
110
  `useSettingsEditor()` returns three things:
94
111
 
95
- - `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
96
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
97
- - `configures`: the identifiers this screen was sent
114
+ - `configures`: the identifiers of the settings this screen may change
98
115
 
99
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.
100
117
 
@@ -201,8 +218,8 @@ An AI assistant can set a session up for a facilitator, choosing from what your
201
218
  ```
202
219
 
203
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
204
- - **Name each setting as a setting path in a code span**, such as `setup.Market`: an assistant writes it back as it stands. The build checks every code span that starts with one of your settings identifiers, failing on one that names no setting (`SETTINGS_UNKNOWN`) and warning on one your setup screen does not configure (`SETUP_NOTES_UNCONFIGURED`)
205
- - **Say what a schema cannot**: which choices are worth asking about, what common requests mean as choices, and, where what the menu offers depends on the scenario, which setting says what it offers. A host may show an assistant your other settings, read-only, for exactly this
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
206
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
207
224
  - **Locales fall back** from the assistant's locale to `en`, then your first supported locale
208
225
 
@@ -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 15k 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.
@@ -63,7 +63,13 @@ A settings resource at `settings/setup/` holding only your setup's choices, a se
63
63
 
64
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
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. 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
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
67
73
 
68
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
69
75
 
@@ -34,7 +34,7 @@ A Markdown file at `setup/notes/en.md` that an assistant reads before setting a
34
34
  - **Anything else**, such as cheaper materials: setup cannot do it. Suggest a scenario that does
35
35
  ```
36
36
 
37
- 2. Keep it short: the choices worth asking a facilitator about, what common requests mean as choices, and which requests need a scenario. Where a request matches one of your scenarios, say to pick that scenario instead. Where what the menu offers depends on the scenario, name the setting that says what it offers: an assistant may be able to read it, though not change it
37
+ 2. Keep it short: the choices worth asking a facilitator about, what common requests mean as choices, and which requests need a scenario. Where a request matches one of your scenarios, say to pick that scenario instead. Where what the menu offers depends on the scenario, name the setting that says what it offers, and list its resource in your setup's `settings`: an assistant may be able to read it, though not change it
38
38
 
39
39
  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
40
40
 
@@ -46,7 +46,7 @@ A Markdown file at `setup/notes/en.md` that an assistant reads before setting a
46
46
  ## Troubleshooting
47
47
 
48
48
  - _`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
49
- - _`SETUP_NOTES_UNCONFIGURED`_: the notes name a setting your setup screen does not `configures`, so a host refuses that change. Leave the setting out and say which scenario does the job, or, if facilitators should choose it, add it to your [menu](give-setup-a-menu.md). Adding a whole settings resource such as `engine` to `configures` hands every setting in it to the assistant
49
+ - _`SETUP_NOTES_UNCONFIGURED`_: the notes name a setting your setup screen neither `configures` nor lists in `settings`, so a host refuses that change. If the notes name it only as where the menu's offer comes from, add its resource to the setup's `settings`. Otherwise leave the setting out and say which scenario does the job, or, if facilitators should choose it, add it to your [menu](give-setup-a-menu.md). Adding a whole settings resource such as `engine` to `configures` hands every setting in it to the assistant
50
50
  - _A code span that is not a setting_, such as `requires`: fine. Only spans starting with a settings identifier are checked
51
51
 
52
52
  ## Related
@@ -689,15 +689,18 @@ export type HostSettingsEditorPortMessage = {
689
689
  type: 'ping';
690
690
  }
691
691
  /**
692
- * The **resolved** values of the settings this editor
693
- * `configures`, keyed by settings identifier (§8.3): the same message,
694
- * and the same shape, as every other surface's `setSettings`. Resolved
695
- * rather than the sparse override layer, which for a fresh session is
696
- * `{}` and would seed the form with nothing.
692
+ * The **resolved** values of the settings this editor `configures` and
693
+ * of those it lists in `settings`, keyed by settings identifier (§8.3):
694
+ * the same message, and the same payload, as every other surface's
695
+ * `setSettings`. Resolved rather than the sparse override layer, which
696
+ * for a fresh session is `{}` and would seed the form with nothing.
697
+ * `configures` names those of them the editor may change (§6.5); a host
698
+ * that predates it sends none, and then sends nothing it may not change.
697
699
  */
698
700
  | {
699
701
  type: 'setSettings';
700
702
  payload: Record<string, Record<string, unknown>>;
703
+ configures?: string[];
701
704
  } | {
702
705
  type: 'setTheme';
703
706
  payload: UserInterfaceTheme;
@@ -225,7 +225,7 @@ var BASES = [
225
225
  sites: []
226
226
  },
227
227
  // The two settings editors (§6.5): one layout, both naming the settings
228
- // they edit in `configures`. Neither ever lived under a plural directory;
228
+ // they edit in `configures` and those they only read in `settings`. Neither ever lived under a plural directory;
229
229
  // the version 2 settings editors they replace did, and the loader refuses
230
230
  // that directory with its own message.
231
231
  {
@@ -237,6 +237,7 @@ var BASES = [
237
237
  kind: "ui",
238
238
  label: "Setup user interface",
239
239
  declaresEndpoints: true,
240
+ readsSettings: true,
240
241
  sites: []
241
242
  },
242
243
  {
@@ -248,6 +249,7 @@ var BASES = [
248
249
  kind: "ui",
249
250
  label: "Scenario editor",
250
251
  declaresEndpoints: true,
252
+ readsSettings: true,
251
253
  sites: []
252
254
  },
253
255
  {
@@ -601,7 +603,11 @@ var ERROR_CODES = {
601
603
  },
602
604
  SETUP_NOTES_UNCONFIGURED: {
603
605
  category: "package",
604
- description: "A warning: the setup notes name a setting the setup UI does not `configures`, so a host refuses the change they describe."
606
+ description: "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."
607
+ },
608
+ EDITOR_SETTINGS_CONFIGURED: {
609
+ category: "package",
610
+ description: "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."
605
611
  },
606
612
  SETTINGS_UNGATED: {
607
613
  category: "package",
@@ -1565,6 +1571,16 @@ var schema_default = {
1565
1571
  uniqueItems: true,
1566
1572
  default: []
1567
1573
  },
1574
+ settings: {
1575
+ type: "array",
1576
+ description: "Identifiers of settings resources this setup user interface reads but does not edit, the built-in `game` included. It is sent their resolved values through `setSettings` beside those it configures, and a host refuses an `updateSettings` that names one. List a resource here, not in `configures`, when the screen only needs to see it, such as the list of what the scenario offers",
1577
+ items: {
1578
+ type: "string",
1579
+ pattern: "^[a-z][a-z0-9_]*$"
1580
+ },
1581
+ uniqueItems: true,
1582
+ default: []
1583
+ },
1568
1584
  endpoints: {
1569
1585
  type: "array",
1570
1586
  description: "Endpoint identifiers this setup user interface is permitted to call via `callbacks.endpoints[<identifier>]`. The host throws when this UI requests an endpoint whose identifier is not listed here.",
@@ -1598,6 +1614,16 @@ var schema_default = {
1598
1614
  uniqueItems: true,
1599
1615
  default: []
1600
1616
  },
1617
+ settings: {
1618
+ type: "array",
1619
+ description: "Identifiers of settings resources this scenario editor reads but does not edit, the built-in `game` included. It is sent their resolved values through `setSettings` beside those it configures, and a host refuses an `updateSettings` that names one. List a resource here, not in `configures`, when the screen only needs to see it, such as the list of what the scenario offers",
1620
+ items: {
1621
+ type: "string",
1622
+ pattern: "^[a-z][a-z0-9_]*$"
1623
+ },
1624
+ uniqueItems: true,
1625
+ default: []
1626
+ },
1601
1627
  endpoints: {
1602
1628
  type: "array",
1603
1629
  description: "Endpoint identifiers this scenario editor is permitted to call via `callbacks.endpoints[<identifier>]`. The host throws when this UI requests an endpoint whose identifier is not listed here.",
@@ -28830,6 +28856,16 @@ function collectUnknownSettingsReferences(config) {
28830
28856
  const resources = [
28831
28857
  { label: 'Engine "engine"', type: "engine", definition: config.engine?.definition },
28832
28858
  { label: 'User Interface "ui"', type: "ui", definition: config.ui?.definition },
28859
+ {
28860
+ label: 'Setup User Interface "setup"',
28861
+ type: "setup",
28862
+ definition: config.setup?.definition
28863
+ },
28864
+ {
28865
+ label: 'Scenario Editor "scenario_editor"',
28866
+ type: "scenario_editor",
28867
+ definition: config.scenario_editor?.definition
28868
+ },
28833
28869
  {
28834
28870
  label: 'Session User Interface "session"',
28835
28871
  type: "session",
@@ -29672,13 +29708,17 @@ var VALIDATION_DESCRIPTORS = [
29672
29708
  type: "setup",
29673
29709
  resources: (config) => slot(config.setup),
29674
29710
  identify: named2,
29675
- checks: [uiFiles, (setup, context) => setupNotesChecks(setup, context)]
29711
+ checks: [
29712
+ uiFiles,
29713
+ (setup, context) => setupNotesChecks(setup, context),
29714
+ editorSettingsChecks
29715
+ ]
29676
29716
  }),
29677
29717
  descriptor({
29678
29718
  type: "scenario_editor",
29679
29719
  resources: (config) => slot(config.scenario_editor),
29680
29720
  identify: named2,
29681
- checks: [uiFiles]
29721
+ checks: [uiFiles, editorSettingsChecks]
29682
29722
  }),
29683
29723
  descriptor({
29684
29724
  type: "tick_controller",
@@ -29962,11 +30002,32 @@ async function validateLoadedPackage(config, options) {
29962
30002
  }
29963
30003
  };
29964
30004
  }
30005
+ function editorSettingsChecks(editor) {
30006
+ const slot2 = editor.definition.identifier;
30007
+ const configures = new Set(editor.definition.configures ?? []);
30008
+ const warnings = [];
30009
+ const findings = [];
30010
+ (editor.definition.settings ?? []).forEach((identifier, index3) => {
30011
+ if (!configures.has(identifier)) return;
30012
+ const message = `${slot2} lists "${identifier}" in both \`configures\` and \`settings\`. Configuring a resource already sends it to the screen, so remove it from \`settings\`, or from \`configures\` if the screen should only read it.`;
30013
+ warnings.push(message);
30014
+ findings.push({
30015
+ severity: "warning",
30016
+ code: "EDITOR_SETTINGS_CONFIGURED",
30017
+ message,
30018
+ file: bundleFileOf(slot2, slot2),
30019
+ pointer: pointerOf("definition", "settings", index3),
30020
+ resource: { type: slot2, identifier: slot2 }
30021
+ });
30022
+ });
30023
+ return { errors: [], warnings, findings };
30024
+ }
29965
30025
  function setupNotesChecks(setup, context) {
29966
30026
  const directory = resolve8(context.workingDir, setup.rootDirectory);
29967
30027
  const schemas = settingsSchemas(context.config);
29968
30028
  const identifiers = new Set(Object.keys(schemas));
29969
30029
  const configures = new Set(setup.definition.configures ?? []);
30030
+ const reads = new Set(setup.definition.settings ?? []);
29970
30031
  const resource = { type: "setup", identifier: "setup" };
29971
30032
  const outcome = {
29972
30033
  errors: [],
@@ -29982,8 +30043,8 @@ function setupNotesChecks(setup, context) {
29982
30043
  for (const { path: path3, line } of notesSettingReferences(markdown, identifiers)) {
29983
30044
  if (!settingPathDeclared(schemas, path3)) continue;
29984
30045
  const identifier = parseSettingPath(path3)?.identifier ?? "";
29985
- if (!configures.has(identifier)) {
29986
- const message = `Setup notes ${file}, line ${line}, name \`${path3}\`, but the setup UI does not configure "${identifier}", so a host refuses that change. Add "${identifier}" to its \`configures\`, or leave the setting out of the notes.`;
30046
+ if (!configures.has(identifier) && !reads.has(identifier)) {
30047
+ const message = `Setup notes ${file}, line ${line}, name \`${path3}\`, but the setup UI neither configures nor reads "${identifier}", so a host refuses a change to it. Add "${identifier}" to its \`configures\` if setup may change it, or to its \`settings\` if the notes name it only as where the menu's offer is read from.`;
29987
30048
  outcome.warnings.push(message);
29988
30049
  outcome.findings.push({
29989
30050
  severity: "warning",
@@ -30948,7 +31009,10 @@ function toSurface(kind2, bundle, hidden) {
30948
31009
  endpoints: endpoints ?? [],
30949
31010
  crossTeamReads: visible(crossTeamReads),
30950
31011
  crossTeamParticipants: crossTeamParticipants === true,
30951
- settings: (kind2 === "setup" || kind2 === "scenario-editor" ? configures : settings) ?? []
31012
+ ...kind2 === "setup" || kind2 === "scenario-editor" ? {
31013
+ settings: [.../* @__PURE__ */ new Set([...configures ?? [], ...settings ?? []])],
31014
+ configures: configures ?? []
31015
+ } : { settings: settings ?? [] }
30952
31016
  };
30953
31017
  }
30954
31018
  var SURFACE_SLOT = {
@@ -31055,10 +31119,21 @@ function buildBatch(options) {
31055
31119
  // The two settings editors are sent the same batch (§12.3): neither is
31056
31120
  // told which slot it fills, since each is its own bundle.
31057
31121
  case "setup":
31058
- return [{ type: "setSettings", payload: settingsFor(state2, surface) }, ...common];
31122
+ return [
31123
+ {
31124
+ type: "setSettings",
31125
+ payload: settingsFor(state2, surface),
31126
+ configures: surface.configures ?? []
31127
+ },
31128
+ ...common
31129
+ ];
31059
31130
  case "scenario-editor":
31060
31131
  return [
31061
- { type: "setSettings", payload: draftSettingsFor(state2, surface, options.viewer) },
31132
+ {
31133
+ type: "setSettings",
31134
+ payload: draftSettingsFor(state2, surface, options.viewer),
31135
+ configures: surface.configures ?? []
31136
+ },
31062
31137
  ...common
31063
31138
  ];
31064
31139
  case "presentation":
@@ -26,7 +26,7 @@ export declare const MANIFEST_VERSION = 3;
26
26
  * section is stamped, it is the revision at the top of the appendix.
27
27
  * `spec-revision.test.ts` holds the two together.
28
28
  */
29
- export declare const SPEC_REVISION = "1.8";
29
+ export declare const SPEC_REVISION = "1.9";
30
30
  /**
31
31
  * Whether specification revision `revision` is later than `than`, both as
32
32
  * `major.minor`. A runtime MAY warn when a package's `builtWith.specRevision`
package/dist/runtime.js CHANGED
@@ -305,7 +305,7 @@ function readTickControllerResult(label, result) {
305
305
 
306
306
  // cli/runtime/manifest-version.ts
307
307
  var MANIFEST_VERSION = 3;
308
- var SPEC_REVISION = "1.8";
308
+ var SPEC_REVISION = "1.9";
309
309
  function isLaterSpecRevision(revision, than) {
310
310
  const [major, minor] = revision.split(".").map(Number);
311
311
  const [thanMajor, thanMinor] = than.split(".").map(Number);
package/dist/schema.json CHANGED
@@ -418,6 +418,16 @@
418
418
  "uniqueItems": true,
419
419
  "default": []
420
420
  },
421
+ "settings": {
422
+ "type": "array",
423
+ "description": "Identifiers of settings resources this setup user interface reads but does not edit, the built-in `game` included. It is sent their resolved values through `setSettings` beside those it configures, and a host refuses an `updateSettings` that names one. List a resource here, not in `configures`, when the screen only needs to see it, such as the list of what the scenario offers",
424
+ "items": {
425
+ "type": "string",
426
+ "pattern": "^[a-z][a-z0-9_]*$"
427
+ },
428
+ "uniqueItems": true,
429
+ "default": []
430
+ },
421
431
  "endpoints": {
422
432
  "type": "array",
423
433
  "description": "Endpoint identifiers this setup user interface is permitted to call via `callbacks.endpoints[<identifier>]`. The host throws when this UI requests an endpoint whose identifier is not listed here.",
@@ -451,6 +461,16 @@
451
461
  "uniqueItems": true,
452
462
  "default": []
453
463
  },
464
+ "settings": {
465
+ "type": "array",
466
+ "description": "Identifiers of settings resources this scenario editor reads but does not edit, the built-in `game` included. It is sent their resolved values through `setSettings` beside those it configures, and a host refuses an `updateSettings` that names one. List a resource here, not in `configures`, when the screen only needs to see it, such as the list of what the scenario offers",
467
+ "items": {
468
+ "type": "string",
469
+ "pattern": "^[a-z][a-z0-9_]*$"
470
+ },
471
+ "uniqueItems": true,
472
+ "default": []
473
+ },
454
474
  "endpoints": {
455
475
  "type": "array",
456
476
  "description": "Endpoint identifiers this scenario editor is permitted to call via `callbacks.endpoints[<identifier>]`. The host throws when this UI requests an endpoint whose identifier is not listed here.",