@seriousgaming/sdk-tools 1.7.0 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (188) hide show
  1. package/dist/agent/guidance.md +1 -0
  2. package/dist/{cli-SOFCTQAL.js → cli-2BF7KBBJ.js} +15 -15
  3. package/dist/cli-2CSI2UU2.js +110 -0
  4. package/dist/{cli-2BH7FX27.js → cli-2FXZZLCL.js} +1 -1
  5. package/dist/{cli-H3J3ICCQ.js → cli-2I6UN6C3.js} +3 -3
  6. package/dist/{cli-MYJGGLC5.js → cli-2JEICVMA.js} +3 -3
  7. package/dist/{cli-7RYIEKMB.js → cli-2PMLR6WG.js} +15 -15
  8. package/dist/{cli-JRIIAZ33.js → cli-2UOUIVHW.js} +53 -38
  9. package/dist/{cli-OQG3Y4RU.js → cli-2VV5IPSY.js} +15 -15
  10. package/dist/{cli-ZRPWZOCW.js → cli-35K37SYY.js} +20 -16
  11. package/dist/cli-3I6AI4AA.js +36 -0
  12. package/dist/{cli-YSPZZQCP.js → cli-3RMP4HKZ.js} +2 -2
  13. package/dist/{cli-4UWFQNGF.js → cli-3VV2JLHX.js} +1 -1
  14. package/dist/cli-3YGNWZC6.js +30 -0
  15. package/dist/{cli-TPNQLYPC.js → cli-4L7S27XO.js} +1 -1
  16. package/dist/cli-4X3X4HB2.js +16 -0
  17. package/dist/{cli-TJ3PLRHF.js → cli-5BPQ73OM.js} +15 -15
  18. package/dist/{cli-UTM4QU67.js → cli-5PTCQTS6.js} +282 -96
  19. package/dist/{cli-ZTZ5H55T.js → cli-6COAU7JR.js} +17 -17
  20. package/dist/{cli-QVASWX2A.js → cli-6GDPO5VU.js} +2 -2
  21. package/dist/{cli-TFMNNVJ7.js → cli-6KL5B7EC.js} +15 -15
  22. package/dist/{cli-NOQBWJQN.js → cli-6Y4XIVQS.js} +3 -3
  23. package/dist/cli-6ZBQELF2.js +36 -0
  24. package/dist/{cli-MMN4BPO4.js → cli-7CW2BBJG.js} +1 -1
  25. package/dist/{cli-LQ4VSM5R.js → cli-7N7WFRWA.js} +0 -0
  26. package/dist/{cli-JR5AZLLK.js → cli-7OCEVQQN.js} +2 -2
  27. package/dist/{cli-Z5HWENER.js → cli-7RLZIWFP.js} +19 -19
  28. package/dist/{cli-J4DKUUTK.js → cli-7V6GUIIS.js} +2 -2
  29. package/dist/{cli-6ZSMW4HR.js → cli-A3P3PO6Z.js} +15 -15
  30. package/dist/{cli-4VZIJYKU.js → cli-A7PITFRR.js} +2 -2
  31. package/dist/{cli-4XCQUM3E.js → cli-AA5GMEUL.js} +4 -4
  32. package/dist/{cli-N6H6T2E2.js → cli-AEAFLZGY.js} +12 -0
  33. package/dist/{cli-C47GJATR.js → cli-AGYCXRPR.js} +3 -3
  34. package/dist/{cli-T4HWGMY4.js → cli-AJ5CABGJ.js} +15 -15
  35. package/dist/{cli-FZ7QAZZP.js → cli-B5LZEFLU.js} +15 -15
  36. package/dist/{cli-XSVGKI3R.js → cli-BC4KKNLA.js} +1 -1
  37. package/dist/{cli-EJVAQCMQ.js → cli-BF6L37O3.js} +114 -5
  38. package/dist/{cli-ZQ2Y3U7F.js → cli-BNN36WZJ.js} +13 -13
  39. package/dist/{cli-FXY3DKPW.js → cli-BT47H36C.js} +2 -2
  40. package/dist/{cli-XTANOFQR.js → cli-BV7MX7JE.js} +3 -3
  41. package/dist/{cli-PVA52RC2.js → cli-BYXNPBVG.js} +15 -15
  42. package/dist/{cli-MJUYJIEP.js → cli-C45A5VX6.js} +3 -3
  43. package/dist/{cli-HM7CD4VU.js → cli-CKV44U7P.js} +19 -19
  44. package/dist/{cli-LQERHJFE.js → cli-CL3KF5KS.js} +2 -2
  45. package/dist/{cli-SX3ULO5P.js → cli-CPX4YA3P.js} +11 -11
  46. package/dist/{cli-CV4JGVJR.js → cli-CQUSM3SF.js} +19 -19
  47. package/dist/cli-CUZUIYCQ.js +36 -0
  48. package/dist/{cli-YOTGR3NB.js → cli-CVOLMK3Z.js} +1 -1
  49. package/dist/{cli-TFZ53OA2.js → cli-D6AC3ZCX.js} +18 -18
  50. package/dist/{cli-PIO7NWMH.js → cli-DJCQ5XFR.js} +15 -15
  51. package/dist/{cli-4YB3ROVR.js → cli-DMKRP33X.js} +1 -1
  52. package/dist/cli-DNCJURUU.js +36 -0
  53. package/dist/{cli-TIDQ4WUE.js → cli-DXHPYN4N.js} +1 -1
  54. package/dist/{cli-FP32D3T6.js → cli-E77R7ZYB.js} +15 -15
  55. package/dist/{cli-PKQNOGBO.js → cli-EDZF5Q2E.js} +63 -17
  56. package/dist/{cli-IPP5FDCH.js → cli-G54355N5.js} +18 -18
  57. package/dist/{cli-SWZY7L7K.js → cli-G7JTIP5G.js} +6 -6
  58. package/dist/{cli-C5QOJJWX.js → cli-GHIMH6JU.js} +1 -1
  59. package/dist/{cli-LE5ICDAF.js → cli-GHQIATHP.js} +4 -4
  60. package/dist/{cli-ESA6YNPF.js → cli-GZE4V7RC.js} +19 -19
  61. package/dist/{cli-4CHKF4DQ.js → cli-H7T6E7OA.js} +2 -2
  62. package/dist/{cli-TDYKRXUA.js → cli-HCMVZXWK.js} +17 -17
  63. package/dist/{cli-WU43JT4T.js → cli-HJPNNORV.js} +2 -2
  64. package/dist/{cli-MYJGMA6U.js → cli-IC5FOT2J.js} +1 -1
  65. package/dist/{cli-VYR326C6.js → cli-ICLCA6VD.js} +19 -19
  66. package/dist/{cli-CXCL7VRK.js → cli-IJPRZSJ5.js} +20 -20
  67. package/dist/{cli-VL2P354N.js → cli-IVZ7AHUJ.js} +3 -3
  68. package/dist/{cli-B6YHEKIJ.js → cli-J2OTL6JH.js} +5 -5
  69. package/dist/{cli-SOMIB4B4.js → cli-J75EBRAJ.js} +17 -17
  70. package/dist/{cli-WAZD75KE.js → cli-JEMWAIAA.js} +15 -15
  71. package/dist/{cli-TDSQSCX4.js → cli-K6M6YB67.js} +1 -1
  72. package/dist/{cli-WG36UJRK.js → cli-KD2RQS35.js} +18 -18
  73. package/dist/{cli-GTWEGYSU.js → cli-KGJHEDR2.js} +19 -19
  74. package/dist/{cli-EDCAH2TC.js → cli-KINJAQTJ.js} +19 -19
  75. package/dist/cli-KJV3GGBA.js +1973 -0
  76. package/dist/{cli-X7E3637I.js → cli-KO26S2CL.js} +50 -26
  77. package/dist/{cli-MULKSLA4.js → cli-L5ZKQNMI.js} +15 -15
  78. package/dist/{cli-ATI6OLJU.js → cli-LFUKHLHI.js} +17 -17
  79. package/dist/{cli-GHLILDH7.js → cli-LZFUSEJT.js} +13 -13
  80. package/dist/{cli-RZITKPJX.js → cli-MN7X4UG2.js} +1 -1
  81. package/dist/{cli-HCRTYQQS.js → cli-MPWTXNF6.js} +2 -2
  82. package/dist/{cli-HHPMAV4F.js → cli-MSSJLABW.js} +3 -3
  83. package/dist/{cli-DHOWZCXT.js → cli-MTAGL3QE.js} +15 -15
  84. package/dist/{cli-JIZTQVL2.js → cli-MX7GFQ6N.js} +14 -14
  85. package/dist/{cli-7TOLC62D.js → cli-MYBDWJP7.js} +20 -20
  86. package/dist/{cli-VPON5HGB.js → cli-MZM4MW7C.js} +19 -19
  87. package/dist/{cli-UBQCSUDH.js → cli-NTI22MRE.js} +16 -16
  88. package/dist/{cli-ZTWOE3ZT.js → cli-NU4SCD5D.js} +1 -1
  89. package/dist/{cli-DEBCP7UH.js → cli-OK6XWVIN.js} +17 -17
  90. package/dist/{cli-6HB6HTC6.js → cli-OOTGO3KW.js} +47 -47
  91. package/dist/{cli-2DQJACAH.js → cli-OX3254NS.js} +17 -17
  92. package/dist/{cli-GEQUJF4L.js → cli-PJO4BKSV.js} +16 -16
  93. package/dist/{cli-R7RG2VMW.js → cli-QIHVXDMW.js} +15 -15
  94. package/dist/{cli-57V4ARER.js → cli-QK2OD24J.js} +1 -1
  95. package/dist/{cli-OANH3BTQ.js → cli-QRAYIXNE.js} +5 -5
  96. package/dist/{cli-GPAN6XK2.js → cli-QWO3XJR3.js} +4 -4
  97. package/dist/{cli-JRMHSMYT.js → cli-R6YAZP6E.js} +19 -19
  98. package/dist/{cli-FXWWYBYU.js → cli-RHYQYXE2.js} +18 -18
  99. package/dist/{cli-C3OERMIR.js → cli-RL5EBZL7.js} +3 -3
  100. package/dist/{cli-XR2XSWQN.js → cli-S3YIYAXC.js} +12 -12
  101. package/dist/{cli-NPPY557S.js → cli-S7PLSPGE.js} +15 -15
  102. package/dist/{cli-NEOLMC2P.js → cli-SBKTGFY4.js} +17 -17
  103. package/dist/{cli-BOXXMDSX.js → cli-TLRTLTGK.js} +18 -18
  104. package/dist/cli-UKC7KXWU.js +36 -0
  105. package/dist/{cli-FWFRKQNE.js → cli-UR63LFVK.js} +2 -2
  106. package/dist/{cli-ZKG3OPZ6.js → cli-USBJQAYI.js} +13 -13
  107. package/dist/{cli-M7WEAIRF.js → cli-VRGVHSXH.js} +106 -28
  108. package/dist/{cli-IUS2YCD3.js → cli-VTLFQHDO.js} +1 -1
  109. package/dist/{cli-JGFJWZFU.js → cli-W4BHSBAX.js} +3 -3
  110. package/dist/cli-WA2PDQUB.js +36 -0
  111. package/dist/{cli-HYEU3QS6.js → cli-WJO75KP7.js} +3 -3
  112. package/dist/{cli-3PIJLSRQ.js → cli-XA4IL7IM.js} +11 -11
  113. package/dist/{cli-LRQDF3ZO.js → cli-XRVH5WV6.js} +13 -13
  114. package/dist/{cli-SRHBXZCN.js → cli-Y33ULHYO.js} +1 -1
  115. package/dist/{cli-G5DQGZ2E.js → cli-YD4SBAHQ.js} +19 -19
  116. package/dist/{cli-64AA7367.js → cli-YI3WZF3C.js} +11 -11
  117. package/dist/{cli-JPAXKLVT.js → cli-ZHFHOWJI.js} +11 -11
  118. package/dist/{cli-MM3A4SPH.js → cli-ZZSPFLTK.js} +7265 -4467
  119. package/dist/cli.js +52 -52
  120. package/dist/client.js +17518 -16558
  121. package/dist/core/save-scenario.d.ts +1 -0
  122. package/dist/core/session-start-gate.d.ts +25 -0
  123. package/dist/core/session.d.ts +4 -0
  124. package/dist/dev/console/assets/{index-CnXlPeLX.js → index-CVNjiRUh.js} +31 -27
  125. package/dist/dev/console/index.html +1 -1
  126. package/dist/docs/api/deck.md +1 -1
  127. package/dist/docs/api/index.md +1 -1
  128. package/dist/docs/api/sdk-e2e.md +7 -6
  129. package/dist/docs/api/sdk-projection.md +1 -0
  130. package/dist/docs/api/sdk-tools-client.md +3 -1
  131. package/dist/docs/api/sdk-tools-playwright.md +1 -8
  132. package/dist/docs/api/sdk-ui.md +40 -64
  133. package/dist/docs/api/sdk.md +10 -1
  134. package/dist/docs/changelog.md +25 -0
  135. package/dist/docs/cli-error-codes.md +7 -1
  136. package/dist/docs/cli-reference.md +3 -0
  137. package/dist/docs/concepts/index.md +1 -0
  138. package/dist/docs/guides/engine.md +5 -0
  139. package/dist/docs/guides/file-handling.md +4 -1
  140. package/dist/docs/guides/llm-integration.md +3 -2
  141. package/dist/docs/guides/multi-team-games.md +2 -0
  142. package/dist/docs/guides/patterns.md +5 -0
  143. package/dist/docs/guides/session.md +1 -1
  144. package/dist/docs/guides/settings.md +2 -0
  145. package/dist/docs/guides/setup.md +67 -6
  146. package/dist/docs/guides/speech-generation.md +1 -0
  147. package/dist/docs/guides/testing.md +2 -0
  148. package/dist/docs/guides/tick-controller.md +2 -0
  149. package/dist/docs/guides/type-safety.md +2 -1
  150. package/dist/docs/guides/ui-files-and-llms.md +3 -1
  151. package/dist/docs/guides/upgrading.md +4 -0
  152. package/dist/docs/guides/validators.md +27 -4
  153. package/dist/docs/guides/waiting-room.md +2 -0
  154. package/dist/docs/page-index.md +10 -7
  155. package/dist/docs/recipes/call-endpoint-from-ui.md +1 -0
  156. package/dist/docs/recipes/create-scenario-editor.md +2 -1
  157. package/dist/docs/recipes/create-setup.md +19 -10
  158. package/dist/docs/recipes/declare-api-uses.md +1 -0
  159. package/dist/docs/recipes/describe-setup-with-endpoint.md +69 -0
  160. package/dist/docs/recipes/give-setup-a-menu.md +90 -0
  161. package/dist/docs/recipes/index.md +4 -1
  162. package/dist/docs/recipes/share-logic-between-engine-and-ui.md +2 -2
  163. package/dist/docs/recipes/test-user-interface.md +1 -1
  164. package/dist/docs/recipes/validate-scenarios.md +9 -3
  165. package/dist/docs/recipes/write-setup-notes.md +57 -0
  166. package/dist/docs/troubleshooting.md +2 -1
  167. package/dist/execution/executor.d.ts +12 -0
  168. package/dist/execution/scenario-gates.d.ts +40 -0
  169. package/dist/host.js +1082 -467
  170. package/dist/playwright.js +17529 -16569
  171. package/dist/runtime/manifest-version.d.ts +1 -1
  172. package/dist/runtime.js +4 -2
  173. package/dist/setup/setup-notes.d.ts +42 -0
  174. package/dist/templates/package/package.json.liquid +15 -15
  175. package/dist/templates/starter-game/package.json +13 -13
  176. package/dist/utils/error-codes.d.ts +13 -1
  177. package/dist/validation/package-validation.d.ts +1 -1
  178. package/package.json +22 -23
  179. package/dist/cli-57C72YKJ.js +0 -36
  180. package/dist/cli-5G7TZHD3.js +0 -36
  181. package/dist/cli-7MBLH4M3.js +0 -36
  182. package/dist/cli-C6G65H6S.js +0 -256
  183. package/dist/cli-L5IG7MY2.js +0 -36
  184. package/dist/cli-SPGUVL6Z.js +0 -36
  185. package/dist/cli-UY4VDI7W.js +0 -30
  186. package/dist/cli-WM6SQJ6Q.js +0 -16
  187. package/dist/cli-ZBTFLZUL.js +0 -36
  188. package/dist/cli-ZF7IFB54.js +0 -4026
@@ -1,4026 +0,0 @@
1
- #!/usr/bin/env node
2
- import {
3
- resourceExample
4
- } from "./cli-F2D4GGUA.js";
5
- import {
6
- logger
7
- } from "./cli-4YB3ROVR.js";
8
- import {
9
- CliError
10
- } from "./cli-N6H6T2E2.js";
11
-
12
- // ../schema.json
13
- var schema_default = {
14
- $schema: "https://json-schema.org/draft/2020-12/schema",
15
- $defs: {
16
- PackageDefinition: {
17
- type: "object",
18
- description: "Definition of a package",
19
- properties: {
20
- identifier: {
21
- type: "string",
22
- description: "Namespace-style identifier for the package",
23
- pattern: "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$"
24
- },
25
- name: {
26
- type: "string",
27
- description: "Name of the package"
28
- },
29
- version: {
30
- type: "string",
31
- description: "Semantic version of the package",
32
- pattern: "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$"
33
- }
34
- },
35
- required: ["identifier", "name", "version"],
36
- additionalProperties: false
37
- },
38
- EndpointActionType: {
39
- type: "string",
40
- description: "A session action an endpoint may return for the runtime to carry out after its write. Each is the operation a facilitator's session surface can perform, held to the same rules; an endpoint may return only the actions it declares.",
41
- enum: [
42
- "tick",
43
- "setWaitingRoom",
44
- "pauseTimer",
45
- "resumeTimer",
46
- "extendTick",
47
- "renameTeam",
48
- "moveParticipant",
49
- "addTeam",
50
- "setLocale"
51
- ]
52
- },
53
- RequiredFeatures: {
54
- type: "array",
55
- description: "Optional runtime features the game depends on, by name. A runtime that does not support every listed feature refuses the package at load, naming the feature, rather than running it half-working. This is how a feature arrives within a manifest version without a new one. Absent or empty means the game needs nothing beyond its manifest version.",
56
- items: { type: "string", pattern: "^[a-z][a-z0-9-]*$" },
57
- uniqueItems: true
58
- },
59
- ScenarioFormat: {
60
- type: "integer",
61
- minimum: 1,
62
- default: 1,
63
- description: "The format of the game's scenarios, which the author bumps whenever a custom scenario saved against an earlier value may no longer be correct: a setting removed, renamed or reshaped, a change in what a value means, or a change in how the game loads scenario assets. A purely additive change, such as a new setting with a default, needs no bump. A runtime stores it with each custom scenario it persists and refuses to apply a saved scenario whose format differs from the package's. Absent means 1."
64
- },
65
- BuiltWith: {
66
- type: "object",
67
- description: "What built the package, written by the build and never authored. Informational: a runtime MAY warn when specRevision is later than the revision it implements, naming both, and MUST NOT refuse a package for it. requires stays the one gate.",
68
- properties: {
69
- sdk: {
70
- type: "string",
71
- minLength: 1,
72
- description: "The version of the SDK tooling that ran the build"
73
- },
74
- specRevision: {
75
- type: "string",
76
- pattern: "^[0-9]+\\.[0-9]+$",
77
- description: "The specification revision that SDK implements, as major.minor"
78
- }
79
- },
80
- required: ["sdk", "specRevision"],
81
- additionalProperties: false
82
- },
83
- ApiUse: {
84
- type: "string",
85
- description: "Runtime callback API (a service) a logic-bearing resource is permitted to invoke. A declared API is always present for that resource, and a runtime that cannot provide one a package declares refuses the package at load. Calling an undeclared API throws at runtime, in both dev and production. Resources that omit `uses` (or declare an empty array) cannot call any callbacks.",
86
- enum: ["generateText", "extractText", "generateSpeech", "writeBlob"]
87
- },
88
- GlobalSettings: {
89
- type: "object",
90
- description: "User-owned global settings file (~/.seriousgaming-sdk/config.json). Stores API keys and defaults once so every project picks them up. This is the lowest-priority configuration source: .env files, environment variables, and CLI flags all override it. The file is plaintext and must not be committed to git.",
91
- properties: {
92
- elevenLabs: {
93
- type: "object",
94
- description: "ElevenLabs integration settings.",
95
- properties: {
96
- apiKey: {
97
- type: "string",
98
- description: "ElevenLabs API key."
99
- }
100
- },
101
- additionalProperties: false
102
- },
103
- platform: {
104
- type: "object",
105
- description: "Serious Gaming platform settings used by `package publish` and LLM text generation.",
106
- properties: {
107
- apiHost: {
108
- type: "string",
109
- description: "Serious Gaming platform API host."
110
- },
111
- apiKey: {
112
- type: "string",
113
- description: "Serious Gaming platform API key."
114
- },
115
- defaultPublisher: {
116
- type: "string",
117
- description: "Default publisher identifier used when publishing packages."
118
- }
119
- },
120
- additionalProperties: false
121
- }
122
- },
123
- additionalProperties: false
124
- },
125
- EngineDefinition: {
126
- type: "object",
127
- description: "Definition of a game's engine: the logic that computes each tick",
128
- properties: {
129
- identifier: {
130
- type: "string",
131
- description: "Identifier for the engine. A game holds one, in the `engine` slot, and the slot is the identifier.",
132
- pattern: "^[a-z][a-z0-9_]*$"
133
- },
134
- reads: {
135
- type: "array",
136
- description: "Identifiers of the capabilities this engine reads",
137
- items: {
138
- type: "string",
139
- pattern: "^[a-z][a-z0-9_]*$"
140
- },
141
- uniqueItems: true
142
- },
143
- writes: {
144
- type: "array",
145
- description: "Identifiers of the capabilities this engine writes",
146
- items: {
147
- type: "string",
148
- pattern: "^[a-z][a-z0-9_]*$"
149
- },
150
- uniqueItems: true
151
- },
152
- uses: {
153
- type: "array",
154
- description: "Runtime callback APIs this engine is permitted to invoke. The runtime throws when this engine calls a callback whose name is not listed here.",
155
- items: { $ref: "#/$defs/ApiUse" },
156
- uniqueItems: true,
157
- default: []
158
- },
159
- settings: {
160
- type: "array",
161
- description: "Identifiers of the settings resources this engine reads. It receives exactly these, read-only, as settings.<identifier>",
162
- items: {
163
- type: "string",
164
- pattern: "^[a-z][a-z0-9_]*$"
165
- },
166
- uniqueItems: true
167
- },
168
- aggregate: {
169
- type: "boolean",
170
- description: "Generated, not authored. True when the engine's logic exports InitAggregate and RunAggregate, in which case it runs once across all teams rather than per-team via Run, and may write to shared capabilities. The build derives this from the exports and writes it into the bundled manifest; authoring it in engine.sdk.json is an error.",
171
- default: false
172
- }
173
- },
174
- required: ["identifier"],
175
- additionalProperties: false
176
- },
177
- CapabilityDefinition: {
178
- type: "object",
179
- description: "Definition of a capability",
180
- properties: {
181
- identifier: {
182
- type: "string",
183
- description: "Namespace-style identifier for the capability",
184
- pattern: "^[a-z][a-z0-9_]*$"
185
- },
186
- variablesSchema: {
187
- type: "object",
188
- description: "JSON Schema describing the variables provided by this capability",
189
- $comment: "This should be a valid JSON Schema object defining properties, types, required fields, etc."
190
- },
191
- scope: {
192
- type: "string",
193
- enum: ["team", "team-readable", "shared", "private"],
194
- description: "Visibility of this capability's state. 'team' (default): per team, delivered to that team's surfaces. 'team-readable': each team writes only its own copy, but user interfaces on other teams may observe every team's value live in shared-state games. 'shared': one value for all teams, written by an aggregate engine, a facilitator's shared write or a session-scoped endpoint, and synchronised between teams by the production coordinator. 'private': per team like 'team', but never delivered to any user interface, never included in session data or cross-team data; for engine bookkeeping no surface should depend on. A user interface declaring one in reads or writes fails the build."
195
- },
196
- lifetime: {
197
- type: "string",
198
- enum: ["tick", "session"],
199
- description: "How long a value lasts. 'tick' (default): part of each tick snapshot, so undo and reset rewind it with the round. 'session': kept out of tick snapshots, so neither undo nor reset touches it; seeded from its defaults once, when the session (or a team added later) is created, and persisted across restarts. For facilitator state such as setup completed, pacing gates, or an announcement. Read and written by surfaces, endpoints, hooks and validators; the build refuses one in the engine's reads or writes, because a tick must be replayable from its snapshot"
200
- }
201
- },
202
- required: ["identifier", "variablesSchema"],
203
- additionalProperties: false
204
- },
205
- SettingsDefinition: {
206
- type: "object",
207
- description: "Definition of a settings resource: named, read-only parameters a game declares once and any resource may read by listing it in its settings. Overridden only by the active scenario and by the session's setup step, and fixed when play starts.",
208
- properties: {
209
- identifier: {
210
- type: "string",
211
- description: "Namespace-style identifier for the settings resource",
212
- pattern: "^[a-z][a-z0-9_]*$"
213
- },
214
- settingsSchema: {
215
- type: "object",
216
- description: "JSON Schema describing these settings. A full object schema, and every property MUST declare a default. `readOnly: true` on a property, at any depth, fixes it and everything under it at the default: no scenario or session may change it",
217
- $comment: "This should be a valid JSON Schema object defining properties, types, and a default for each."
218
- }
219
- },
220
- required: ["identifier", "settingsSchema"],
221
- additionalProperties: false
222
- },
223
- SDKSettings: {
224
- type: "object",
225
- description: "Bundle containing a settings definition",
226
- properties: {
227
- definition: {
228
- $ref: "#/$defs/SettingsDefinition"
229
- }
230
- },
231
- required: ["definition"],
232
- additionalProperties: false
233
- },
234
- UserInterfaceDefinition: {
235
- type: "object",
236
- description: "Definition of a user interface with internationalization support",
237
- properties: {
238
- identifier: {
239
- type: "string",
240
- description: "Namespace-style identifier for the user interface",
241
- pattern: "^[a-z][a-z0-9_]*$"
242
- },
243
- reads: {
244
- type: "array",
245
- description: "Identifiers of the capabilities this user interface reads",
246
- items: {
247
- type: "string",
248
- pattern: "^[a-z][a-z0-9_]*$"
249
- },
250
- uniqueItems: true
251
- },
252
- crossTeamReads: {
253
- type: "array",
254
- description: "Identifiers of the capabilities this user interface receives every team's value of, live, rather than its own team's alone. Every entry MUST also appear in `reads`, and MUST name a capability with scope 'team-readable'. Only meaningful in shared-state games.",
255
- items: {
256
- type: "string",
257
- pattern: "^[a-z][a-z0-9_]*$"
258
- },
259
- uniqueItems: true,
260
- default: []
261
- },
262
- writes: {
263
- type: "array",
264
- description: "Identifiers of the capabilities this user interface writes",
265
- items: {
266
- type: "string",
267
- pattern: "^[a-z][a-z0-9_]*$"
268
- },
269
- uniqueItems: true
270
- },
271
- endpoints: {
272
- type: "array",
273
- description: "Endpoint identifiers this 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.",
274
- items: {
275
- type: "string",
276
- pattern: "^[a-z][a-z0-9_]*$"
277
- },
278
- uniqueItems: true,
279
- default: []
280
- },
281
- crossTeamParticipants: {
282
- type: "boolean",
283
- description: "If true, this user interface may read the participant roster of every team via `callbacks.getAllTeamsParticipants()`, not just its own team. Only meaningful in shared-state games; a game that is not shared-state and references a UI declaring this MUST fail the build.",
284
- default: false
285
- },
286
- settings: {
287
- type: "array",
288
- description: "Identifiers of the settings resources this user interface reads. It receives exactly these, read-only, as settings.<identifier>",
289
- items: {
290
- type: "string",
291
- pattern: "^[a-z][a-z0-9_]*$"
292
- },
293
- uniqueItems: true
294
- }
295
- },
296
- required: ["identifier"],
297
- additionalProperties: false
298
- },
299
- SessionUserInterfaceDefinition: {
300
- type: "object",
301
- description: "Definition of a session user interface with internationalization support",
302
- properties: {
303
- identifier: {
304
- type: "string",
305
- description: "Namespace-style identifier for the session user interface",
306
- pattern: "^[a-z][a-z0-9_]*$"
307
- },
308
- reads: {
309
- type: "array",
310
- description: "Identifiers of the capabilities this session user interface reads",
311
- items: {
312
- type: "string",
313
- pattern: "^[a-z][a-z0-9_]*$"
314
- },
315
- uniqueItems: true
316
- },
317
- writes: {
318
- type: "array",
319
- description: "Identifiers of the capabilities this session user interface writes",
320
- items: {
321
- type: "string",
322
- pattern: "^[a-z][a-z0-9_]*$"
323
- },
324
- uniqueItems: true
325
- },
326
- endpoints: {
327
- type: "array",
328
- description: "Endpoint identifiers this session 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.",
329
- items: {
330
- type: "string",
331
- pattern: "^[a-z][a-z0-9_]*$"
332
- },
333
- uniqueItems: true,
334
- default: []
335
- },
336
- settings: {
337
- type: "array",
338
- description: "Identifiers of the settings resources this session user interface reads. It receives exactly these, read-only, as settings.<identifier>",
339
- items: {
340
- type: "string",
341
- pattern: "^[a-z][a-z0-9_]*$"
342
- },
343
- uniqueItems: true
344
- }
345
- },
346
- required: ["identifier"],
347
- additionalProperties: false
348
- },
349
- WaitingRoomUserInterfaceDefinition: {
350
- type: "object",
351
- description: "Definition of a waiting room user interface (the holding screen shown to players while the session's waiting room is open)",
352
- properties: {
353
- identifier: {
354
- type: "string",
355
- description: "Namespace-style identifier for the waiting room user interface",
356
- pattern: "^[a-z][a-z0-9_]*$"
357
- },
358
- reads: {
359
- type: "array",
360
- description: "Identifiers of the capabilities this waiting room user interface reads",
361
- items: {
362
- type: "string",
363
- pattern: "^[a-z][a-z0-9_]*$"
364
- },
365
- uniqueItems: true
366
- },
367
- crossTeamReads: {
368
- type: "array",
369
- description: "Identifiers of the capabilities this waiting room user interface receives every team's value of, live, rather than its own team's alone. Every entry MUST also appear in `reads`, and MUST name a capability with scope 'team-readable'. Only meaningful in shared-state games.",
370
- items: {
371
- type: "string",
372
- pattern: "^[a-z][a-z0-9_]*$"
373
- },
374
- uniqueItems: true,
375
- default: []
376
- },
377
- writes: {
378
- type: "array",
379
- description: "Identifiers of the capabilities this waiting room user interface writes",
380
- items: {
381
- type: "string",
382
- pattern: "^[a-z][a-z0-9_]*$"
383
- },
384
- uniqueItems: true
385
- },
386
- endpoints: {
387
- type: "array",
388
- description: "Endpoint identifiers this waiting room 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.",
389
- items: {
390
- type: "string",
391
- pattern: "^[a-z][a-z0-9_]*$"
392
- },
393
- uniqueItems: true,
394
- default: []
395
- },
396
- crossTeamParticipants: {
397
- type: "boolean",
398
- description: "If true, this waiting room user interface may read the participant roster of every team via `callbacks.getAllTeamsParticipants()`, not just its own team. Only meaningful in shared-state games; a game that is not shared-state and references a UI declaring this MUST fail the build.",
399
- default: false
400
- },
401
- settings: {
402
- type: "array",
403
- description: "Identifiers of the settings resources this waiting room user interface reads. It receives exactly these, read-only, as settings.<identifier>",
404
- items: {
405
- type: "string",
406
- pattern: "^[a-z][a-z0-9_]*$"
407
- },
408
- uniqueItems: true
409
- }
410
- },
411
- required: ["identifier"],
412
- additionalProperties: false
413
- },
414
- SetupDefinition: {
415
- type: "object",
416
- description: "Definition of the game's setup user interface: a small form shown at session creation, whose changes become session overrides for that session only (\xA78.2, \xA78.3). Its presence is what gives a session its configuration step",
417
- properties: {
418
- identifier: {
419
- type: "string",
420
- description: "The slot, `setup`. A game holds one setup user interface, so it carries no name of its own",
421
- pattern: "^[a-z][a-z0-9_]*$"
422
- },
423
- configures: {
424
- type: "array",
425
- description: "Identifiers of the settings resources this setup user interface edits, the built-in `game` included. It is sent their resolved values through `setSettings`, keyed by identifier, and writes changes to them through `updateSettings`",
426
- items: {
427
- type: "string",
428
- pattern: "^[a-z][a-z0-9_]*$"
429
- },
430
- uniqueItems: true,
431
- default: []
432
- },
433
- endpoints: {
434
- type: "array",
435
- 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.",
436
- items: {
437
- type: "string",
438
- pattern: "^[a-z][a-z0-9_]*$"
439
- },
440
- uniqueItems: true,
441
- default: []
442
- }
443
- },
444
- required: ["identifier"],
445
- additionalProperties: false
446
- },
447
- ScenarioEditorDefinition: {
448
- type: "object",
449
- description: "Definition of the game's scenario editor: an authoring screen, used at any time and with no session, whose output is a lasting scenario (\xA76.7.1). Optional: `customScenarios.supported` is what switches custom scenarios on",
450
- properties: {
451
- identifier: {
452
- type: "string",
453
- description: "The slot, `scenario_editor`. A game holds one scenario editor, so it carries no name of its own",
454
- pattern: "^[a-z][a-z0-9_]*$"
455
- },
456
- configures: {
457
- type: "array",
458
- description: "Identifiers of the settings resources this scenario editor edits, the built-in `game` included. It is sent their resolved values through `setSettings`, keyed by identifier, and writes changes to them through `updateSettings`",
459
- items: {
460
- type: "string",
461
- pattern: "^[a-z][a-z0-9_]*$"
462
- },
463
- uniqueItems: true,
464
- default: []
465
- },
466
- endpoints: {
467
- type: "array",
468
- 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.",
469
- items: {
470
- type: "string",
471
- pattern: "^[a-z][a-z0-9_]*$"
472
- },
473
- uniqueItems: true,
474
- default: []
475
- }
476
- },
477
- required: ["identifier"],
478
- additionalProperties: false
479
- },
480
- ScenarioDefinition: {
481
- type: "object",
482
- description: "Definition of a scenario \u2014 a named flavour of a game bundling settings overrides and static assets",
483
- properties: {
484
- identifier: {
485
- type: "string",
486
- description: "Namespace-style identifier for the scenario",
487
- pattern: "^[a-z][a-z0-9_]*$"
488
- },
489
- locales: {
490
- type: "object",
491
- description: "Localized scenario fields with one entry per supported locale",
492
- patternProperties: {
493
- "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": {
494
- type: "object",
495
- description: "Localized fields for this locale",
496
- properties: {
497
- name: {
498
- type: "string",
499
- description: "Display name for this locale"
500
- },
501
- description: {
502
- type: "string",
503
- description: "Short description for this locale"
504
- }
505
- },
506
- required: ["name"],
507
- additionalProperties: false
508
- }
509
- },
510
- minProperties: 1,
511
- additionalProperties: false
512
- },
513
- default: {
514
- type: "boolean",
515
- description: "If true, this scenario is selected when no explicit scenario is chosen at init time. At most one scenario per package should set it.",
516
- default: false
517
- },
518
- restricted: {
519
- type: "boolean",
520
- description: "If true, this scenario is built for a particular audience and a runtime must not offer, list, resolve or serve it to a caller it has not granted it to. The package never names that audience. Cannot be combined with `default`.",
521
- default: false
522
- },
523
- settings: {
524
- type: "object",
525
- description: "Settings overrides applied when this scenario is selected, keyed by settings identifier. Each value is a partial object of that settings resource's properties. The game-level settings (the number of rounds, the team bounds and names, and whether the waiting room opens with the session) are the built-in `game` settings resource, overridden here under `game` like any other.",
526
- additionalProperties: {
527
- type: "object"
528
- }
529
- }
530
- },
531
- required: ["identifier", "locales"],
532
- additionalProperties: false
533
- },
534
- FacilitatorGuideDefinition: {
535
- type: "object",
536
- description: "Definition of a facilitator guide \u2014 bundled markdown content rendered natively by the host on the facilitator's page",
537
- properties: {
538
- identifier: {
539
- type: "string",
540
- description: "Namespace-style identifier for the facilitator guide",
541
- pattern: "^[a-z][a-z0-9_]*$"
542
- },
543
- locales: {
544
- type: "object",
545
- description: "Localized facilitator guide fields with one entry per supported locale. Each declared locale must have a matching content/<locale>/ directory.",
546
- patternProperties: {
547
- "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": {
548
- type: "object",
549
- description: "Localized fields for this locale",
550
- properties: {
551
- name: {
552
- type: "string",
553
- description: "Display name for this locale, shown as the guide's title"
554
- }
555
- },
556
- required: ["name"],
557
- additionalProperties: false
558
- }
559
- },
560
- minProperties: 1,
561
- additionalProperties: false
562
- },
563
- settings: {
564
- type: "array",
565
- description: "Identifiers of the settings resources this guide reads. Its chapters may show their values with :setting[identifier.path] and show or hide content on them with :::when, resolved as for every other resource that reads settings",
566
- items: {
567
- type: "string",
568
- pattern: "^[a-z][a-z0-9_]*$"
569
- },
570
- uniqueItems: true
571
- }
572
- },
573
- required: ["identifier", "locales"],
574
- additionalProperties: false
575
- },
576
- GameDefinition: {
577
- type: "object",
578
- description: "Definition of a game with internationalization support",
579
- properties: {
580
- identifier: {
581
- type: "string",
582
- description: "Namespace-style identifier for the game",
583
- pattern: "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$"
584
- },
585
- supportedLocales: { $ref: "#/$defs/GameSupportedLocales" },
586
- locales: { $ref: "#/$defs/GameLocales" },
587
- customScenarios: { $ref: "#/$defs/GameCustomScenarios" },
588
- teams: {
589
- type: "object",
590
- description: "The game's interaction mode, fixed at authoring time. The team bounds, participant guidance and default names are game settings, in the built-in `game` settings resource.",
591
- properties: {
592
- mode: { $ref: "#/$defs/GameTeamMode" }
593
- },
594
- additionalProperties: false
595
- }
596
- },
597
- required: ["identifier", "supportedLocales", "locales"],
598
- additionalProperties: false
599
- },
600
- GameSupportedLocales: {
601
- type: "array",
602
- description: "List of locales supported by this game (e.g., ['en', 'es', 'fr'])",
603
- items: {
604
- type: "string",
605
- pattern: "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$"
606
- },
607
- minItems: 1,
608
- uniqueItems: true
609
- },
610
- GameLocales: {
611
- type: "object",
612
- description: "Localized game fields with one entry per supported locale",
613
- patternProperties: {
614
- "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": {
615
- type: "object",
616
- description: "Localized fields for this locale",
617
- properties: {
618
- name: {
619
- type: "string",
620
- description: "Display name for this locale"
621
- }
622
- },
623
- required: ["name"],
624
- additionalProperties: false
625
- }
626
- },
627
- minProperties: 1,
628
- additionalProperties: false
629
- },
630
- GameCustomScenarios: {
631
- type: "object",
632
- description: "Production-policy signal opting in to facilitator-authored, runtime-persisted scenarios. When supported is true, runtime hosts offer 'save as scenario' from the game's scenario editor, or through whatever other authoring route they provide, such as an agent editing the settings schemas directly, and list the resulting scenarios alongside built-in ones at init time. The scenario editor is optional: this flag, not the editor, is what switches custom scenarios on. Author-time hosts (e.g. the SDK dev server) surface their own save affordance regardless.",
633
- properties: {
634
- supported: {
635
- type: "boolean",
636
- description: "If true, the runtime MAY persist scenarios authored at session time."
637
- }
638
- },
639
- required: ["supported"],
640
- additionalProperties: false
641
- },
642
- GameTeams: {
643
- type: "object",
644
- description: "Team configuration: the interaction mode, fixed at authoring time, and the game's own values for the team settings, which are the defaults of the built-in `game` settings resource. All fields are optional.",
645
- properties: {
646
- mode: { $ref: "#/$defs/GameTeamMode" },
647
- min: {
648
- type: "integer",
649
- description: "Minimum number of teams this game is designed for. The default for the `game` settings' `teams.min`",
650
- minimum: 1
651
- },
652
- max: {
653
- type: "integer",
654
- description: "Maximum number of teams this game is designed for. The default for the `game` settings' `teams.max`",
655
- minimum: 1
656
- },
657
- perTeam: {
658
- type: "object",
659
- description: "Per-team participant guidance. The default for the `game` settings' `teams.perTeam`",
660
- properties: {
661
- minParticipants: {
662
- type: "integer",
663
- description: "Minimum participants per team",
664
- minimum: 1
665
- },
666
- maxParticipants: {
667
- type: "integer",
668
- description: "Maximum participants per team",
669
- minimum: 1
670
- }
671
- },
672
- additionalProperties: false
673
- },
674
- defaultNames: {
675
- type: "array",
676
- description: "Ordered, localised default names for teams. Entry N seeds the default name for the Nth team (team-1, team-2, \u2026). Advisory: operators may rename teams at session setup, and teams beyond the list fall back to the runtime default. The default for the `game` settings' `teams.defaultNames`",
677
- items: {
678
- type: "object",
679
- description: "Localised default name for one team, with one entry per supported locale",
680
- patternProperties: {
681
- "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": {
682
- type: "object",
683
- description: "Localised fields for this locale",
684
- properties: {
685
- name: {
686
- type: "string",
687
- description: "Display name for this locale"
688
- }
689
- },
690
- required: ["name"],
691
- additionalProperties: false
692
- }
693
- },
694
- minProperties: 1,
695
- additionalProperties: false
696
- }
697
- },
698
- sessionJoin: {
699
- type: "boolean",
700
- description: "Whether a session may offer one join link for the whole session, through which the host places each person in a team of its choosing. Defaults to true. Set it false when a game depends on who is in which team, such as one role per team, and hand out team links instead. The default for the `game` settings' `teams.sessionJoin`"
701
- }
702
- },
703
- additionalProperties: false
704
- },
705
- GameTeamMode: {
706
- type: "string",
707
- description: "Interaction mode this game runs in. 'independent' = teams are isolated with independent tick progression. 'shared-state' = teams interact via shared capabilities with synchronized ticks. If omitted, defaults to 'independent'. Fixed at authoring time: no scenario or session varies it.",
708
- enum: ["independent", "shared-state"]
709
- },
710
- GameSettingConstraint: {
711
- type: "object",
712
- description: "How a game narrows one of its `game` settings. Each keyword may only narrow the SDK's schema: a `minimum` or `maximum` applies to a number and also rules out null, an `enum` lists values the SDK's schema accepts, and `readOnly` fixes the value at the game's own, so no scenario or session may change it.",
713
- properties: {
714
- minimum: {
715
- type: "number",
716
- description: "The smallest value a scenario or session may set. At or above the SDK's own minimum"
717
- },
718
- maximum: {
719
- type: "number",
720
- description: "The largest value a scenario or session may set. At or below the SDK's own maximum"
721
- },
722
- enum: {
723
- type: "array",
724
- minItems: 1,
725
- description: "The only values a scenario or session may set, each one the SDK's schema accepts"
726
- },
727
- readOnly: {
728
- type: "boolean",
729
- description: "True fixes the value at the game's own: a scenario or session that sets it is refused"
730
- }
731
- },
732
- minProperties: 1,
733
- additionalProperties: false
734
- },
735
- GameSettingsConstraints: {
736
- type: "object",
737
- description: "Narrowing for the built-in `game` settings, in their shape. The build merges each constraint into the `game` settings schema it emits, so a runtime sees one ordinary schema. Adding a constraint is a scenario-format change.",
738
- properties: {
739
- maxTicks: { $ref: "#/$defs/GameSettingConstraint" },
740
- teams: {
741
- type: "object",
742
- properties: {
743
- min: { $ref: "#/$defs/GameSettingConstraint" },
744
- max: { $ref: "#/$defs/GameSettingConstraint" },
745
- perTeam: {
746
- type: "object",
747
- properties: {
748
- minParticipants: { $ref: "#/$defs/GameSettingConstraint" },
749
- maxParticipants: { $ref: "#/$defs/GameSettingConstraint" }
750
- },
751
- additionalProperties: false
752
- },
753
- defaultNames: { $ref: "#/$defs/GameSettingConstraint" },
754
- sessionJoin: { $ref: "#/$defs/GameSettingConstraint" }
755
- },
756
- additionalProperties: false
757
- },
758
- waitingRoom: {
759
- type: "object",
760
- properties: {
761
- openOnStart: { $ref: "#/$defs/GameSettingConstraint" }
762
- },
763
- additionalProperties: false
764
- }
765
- },
766
- additionalProperties: false
767
- },
768
- GameSettings: {
769
- type: "object",
770
- description: "The values of the built-in `game` settings resource: the game-level settings every game has. Its schema is the SDK's, not the game's: a game sets its own values in its manifest, which become this resource's defaults, and a scenario or a session overrides them under the identifier `game` like any other settings resource. Null means 'no limit' or 'no guidance'. A new game-level setting joins as a new optional property with a default.",
771
- properties: {
772
- maxTicks: {
773
- type: ["integer", "null"],
774
- minimum: 1,
775
- description: "The number of ticks the game plays before it is complete. Null means no fixed limit: the game ends by its tick controller or its engine"
776
- },
777
- teams: {
778
- type: "object",
779
- description: "How many teams a session may hold, how many participants each is meant for, and what the teams are called to begin with",
780
- properties: {
781
- min: {
782
- type: ["integer", "null"],
783
- minimum: 1,
784
- description: "The fewest teams a session may start play with. Null means no minimum"
785
- },
786
- max: {
787
- type: ["integer", "null"],
788
- minimum: 1,
789
- description: "The most teams a session may hold at any point. Null means no maximum beyond the runtime's own ceiling"
790
- },
791
- perTeam: {
792
- type: "object",
793
- description: "Advisory guidance on how many participants each team is meant for, shown to the facilitator. Never a gate on joining",
794
- properties: {
795
- minParticipants: {
796
- type: ["integer", "null"],
797
- minimum: 1,
798
- description: "The fewest participants a team is meant for. Null means no guidance"
799
- },
800
- maxParticipants: {
801
- type: ["integer", "null"],
802
- minimum: 1,
803
- description: "The most participants a team is meant for. Null means no guidance"
804
- }
805
- },
806
- additionalProperties: false
807
- },
808
- defaultNames: {
809
- type: "array",
810
- description: "Ordered, localised default names for teams. Entry N names the team whose index is N; a team beyond the list is named by position. A facilitator or the team's players may rename it",
811
- items: {
812
- type: "object",
813
- description: "Localised default name for one team, with one entry per supported locale",
814
- patternProperties: {
815
- "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": {
816
- type: "object",
817
- description: "Localised fields for this locale",
818
- properties: {
819
- name: {
820
- type: "string",
821
- description: "Display name for this locale"
822
- }
823
- },
824
- required: ["name"],
825
- additionalProperties: false
826
- }
827
- },
828
- minProperties: 1,
829
- additionalProperties: false
830
- }
831
- },
832
- sessionJoin: {
833
- type: "boolean",
834
- description: "Whether the host may offer one join link for the whole session, placing each person in a team of its choosing. Read once as the session is created, so only the game and its scenarios set it"
835
- }
836
- },
837
- additionalProperties: false
838
- },
839
- waitingRoom: {
840
- type: "object",
841
- description: "How the waiting room starts",
842
- properties: {
843
- openOnStart: {
844
- type: "boolean",
845
- description: "Whether a new session starts with the waiting room open. Seeds the session flag at creation, before any setup step, so only the game and its scenarios set it"
846
- }
847
- },
848
- additionalProperties: false
849
- }
850
- },
851
- additionalProperties: false
852
- },
853
- GameWaitingRoomOpenOnStart: {
854
- type: "boolean",
855
- description: "Whether a new session starts with the waiting room open, holding participants on this screen until the facilitator closes it. Seeds the session flag at creation only: the facilitator owns it from then on, and neither a reset nor a restart reapplies it.",
856
- default: false
857
- },
858
- GameWaitingRoomSettings: {
859
- type: "object",
860
- description: "Waiting room settings. Which user interface fills the waiting room is the package's waiting room user interface; only its settings are authored.",
861
- properties: {
862
- openOnStart: { $ref: "#/$defs/GameWaitingRoomOpenOnStart" }
863
- },
864
- additionalProperties: false
865
- },
866
- HookSignal: {
867
- type: "string",
868
- description: "Lifecycle signal a hook subscribes to. Hooks fire on out-of-tick events emitted by the runtime, after the runtime applies the change.",
869
- enum: ["participantJoin", "participantMove"]
870
- },
871
- HookDefinition: {
872
- type: "object",
873
- description: "Definition of a hook \u2014 a single-signal handler that runs in response to an out-of-tick lifecycle event",
874
- properties: {
875
- identifier: {
876
- type: "string",
877
- description: "Namespace-style identifier for the hook",
878
- pattern: "^[a-z][a-z0-9_]*$"
879
- },
880
- signal: {
881
- $ref: "#/$defs/HookSignal",
882
- description: "Lifecycle signal this hook fires on"
883
- },
884
- reads: {
885
- type: "array",
886
- description: "Identifiers of the capabilities this hook reads",
887
- items: {
888
- type: "string",
889
- pattern: "^[a-z][a-z0-9_]*$"
890
- },
891
- uniqueItems: true
892
- },
893
- writes: {
894
- type: "array",
895
- description: "Identifiers of the capabilities this hook writes",
896
- items: {
897
- type: "string",
898
- pattern: "^[a-z][a-z0-9_]*$"
899
- },
900
- uniqueItems: true
901
- },
902
- uses: {
903
- type: "array",
904
- description: "Runtime callback APIs this hook is permitted to invoke. The runtime throws when this hook calls a callback whose name is not listed here.",
905
- items: { $ref: "#/$defs/ApiUse" },
906
- uniqueItems: true,
907
- default: []
908
- },
909
- settings: {
910
- type: "array",
911
- description: "Identifiers of the settings resources this hook reads. It receives exactly these, read-only, as settings.<identifier>",
912
- items: {
913
- type: "string",
914
- pattern: "^[a-z][a-z0-9_]*$"
915
- },
916
- uniqueItems: true
917
- }
918
- },
919
- required: ["identifier", "signal"],
920
- additionalProperties: false
921
- },
922
- TickControllerDefinition: {
923
- type: "object",
924
- description: "Definition of a tick controller that determines automatic tick timing",
925
- properties: {
926
- identifier: {
927
- type: "string",
928
- description: "Namespace-style identifier for the tick controller",
929
- pattern: "^[a-z][a-z0-9_]*$"
930
- },
931
- reads: {
932
- type: "array",
933
- description: "Identifiers of the capabilities this tick controller reads",
934
- items: {
935
- type: "string",
936
- pattern: "^[a-z][a-z0-9_]*$"
937
- },
938
- uniqueItems: true
939
- },
940
- uses: {
941
- type: "array",
942
- description: "Runtime callback APIs this tick controller is permitted to invoke. The runtime throws when this tick controller calls a callback whose name is not listed here.",
943
- items: { $ref: "#/$defs/ApiUse" },
944
- uniqueItems: true,
945
- default: []
946
- },
947
- settings: {
948
- type: "array",
949
- description: "Identifiers of the settings resources this tick controller reads. It receives exactly these, read-only, as settings.<identifier>",
950
- items: {
951
- type: "string",
952
- pattern: "^[a-z][a-z0-9_]*$"
953
- },
954
- uniqueItems: true
955
- }
956
- },
957
- required: ["identifier"],
958
- additionalProperties: false
959
- },
960
- SDKTickController: {
961
- type: "object",
962
- description: "Bundle containing a tick controller definition and its logic layout",
963
- properties: {
964
- definition: { $ref: "#/$defs/TickControllerDefinition" },
965
- logic: { $ref: "#/$defs/LogicLayout" },
966
- rootDirectory: {
967
- type: "string",
968
- description: "Directory containing this resource's files, relative to the bundle file. Must use forward slashes, not Windows separators",
969
- pattern: "^[^\\\\]+$"
970
- }
971
- },
972
- required: ["definition", "logic", "rootDirectory"],
973
- additionalProperties: false
974
- },
975
- SDKHook: {
976
- type: "object",
977
- description: "Bundle containing a hook definition and its logic layout",
978
- properties: {
979
- definition: { $ref: "#/$defs/HookDefinition" },
980
- logic: { $ref: "#/$defs/LogicLayout" },
981
- rootDirectory: {
982
- type: "string",
983
- description: "Directory containing this resource's files, relative to the bundle file. Must use forward slashes, not Windows separators",
984
- pattern: "^[^\\\\]+$"
985
- }
986
- },
987
- required: ["definition", "logic", "rootDirectory"],
988
- additionalProperties: false
989
- },
990
- ValidatorGate: {
991
- type: "string",
992
- description: "What a validator can gate: a participant's context write, a participant's request for the next tick, or a scenario (a package scenario at build, a custom scenario when it is saved)",
993
- enum: ["updateData", "requestTick", "scenario"]
994
- },
995
- ValidatorDefinition: {
996
- type: "object",
997
- description: "Definition of a validator \u2014 a standalone, read-only gate on what a participant does from a player surface: a context write, or a request for the next tick. Reject-only; never modifies state.",
998
- properties: {
999
- identifier: {
1000
- type: "string",
1001
- description: "Namespace-style identifier for the validator",
1002
- pattern: "^[a-z][a-z0-9_]*$"
1003
- },
1004
- reads: {
1005
- type: "array",
1006
- description: "Identifiers of the capabilities this validator reads. Also its trigger set: a validator runs when a mutation changes one of them, and one declaring none runs on every mutation",
1007
- items: {
1008
- type: "string",
1009
- pattern: "^[a-z][a-z0-9_]*$"
1010
- },
1011
- uniqueItems: true
1012
- },
1013
- gates: {
1014
- type: "array",
1015
- description: "Generated, not authored. The participant actions this validator gates, one per gate function its logic exports: 'updateData' for an UpdateData export (a context write), 'requestTick' for a RequestTick export (a request for the next tick). The build derives this from the exports and writes it into the bundled manifest, and a runtime calls only these; authoring it in validator.sdk.json is an error",
1016
- items: { $ref: "#/$defs/ValidatorGate" },
1017
- uniqueItems: true
1018
- },
1019
- settings: {
1020
- type: "array",
1021
- description: "Identifiers of the settings resources this validator reads. It receives exactly these, read-only, as settings.<identifier>",
1022
- items: {
1023
- type: "string",
1024
- pattern: "^[a-z][a-z0-9_]*$"
1025
- },
1026
- uniqueItems: true
1027
- }
1028
- },
1029
- required: ["identifier"],
1030
- additionalProperties: false
1031
- },
1032
- SDKValidator: {
1033
- type: "object",
1034
- description: "Bundle containing a validator definition and its logic layout",
1035
- properties: {
1036
- definition: { $ref: "#/$defs/ValidatorDefinition" },
1037
- logic: { $ref: "#/$defs/LogicLayout" },
1038
- rootDirectory: {
1039
- type: "string",
1040
- description: "Directory containing this resource's files, relative to the bundle file. Must use forward slashes, not Windows separators",
1041
- pattern: "^[^\\\\]+$"
1042
- }
1043
- },
1044
- required: ["definition", "logic", "rootDirectory"],
1045
- additionalProperties: false
1046
- },
1047
- EndpointDefinition: {
1048
- type: "object",
1049
- description: "Definition of an endpoint \u2014 a named, server-side handler that user interfaces, and callers outside the game when its visibility is external, invoke by identifier. Endpoints validate structured requests and responses against declared schemas, and operate strictly within the bounds of their declared `reads`, `writes` and `uses`.",
1050
- properties: {
1051
- identifier: {
1052
- type: "string",
1053
- description: "Namespace-style identifier for the endpoint",
1054
- pattern: "^[a-z][a-z0-9_]*$"
1055
- },
1056
- displayName: {
1057
- type: "string",
1058
- description: "Human-readable name for author-time tools"
1059
- },
1060
- description: {
1061
- type: "string",
1062
- description: "Short description of what this endpoint does, surfaced in author-time tools. Required when `visibility` is `external`, where it is also the text an outside caller, such as a facilitator's AI agent, reads to decide whether to call this endpoint."
1063
- },
1064
- scope: {
1065
- type: "string",
1066
- enum: ["session", "team", "scenario"],
1067
- description: "What this endpoint acts on: one team, the session as a whole, or a scenario being written. A team-scoped endpoint receives that team's context and a `team` naming it, whoever calls it; a session-scoped one has neither. A scenario-scoped endpoint runs on a scenario draft with no session: it receives the draft's settings and nothing of game state, declares no `reads`, `writes` or `actions`, and only the scenario editor, or an authoring agent when it is `external`, may call it. Absent means `team`.",
1068
- default: "team"
1069
- },
1070
- requestSchema: {
1071
- type: "object",
1072
- description: "JSON Schema describing the request payload accepted by this endpoint",
1073
- $comment: "This should be a valid JSON Schema object defining properties, types, required fields, etc."
1074
- },
1075
- responseSchema: {
1076
- type: "object",
1077
- description: "JSON Schema describing the response payload returned by this endpoint",
1078
- $comment: "This should be a valid JSON Schema object defining properties, types, required fields, etc."
1079
- },
1080
- reads: {
1081
- type: "array",
1082
- description: "Identifiers of the capabilities this endpoint reads. The handler receives a scoped snapshot of these capabilities under `context`.",
1083
- items: {
1084
- type: "string",
1085
- pattern: "^[a-z][a-z0-9_]*$"
1086
- },
1087
- uniqueItems: true
1088
- },
1089
- settings: {
1090
- type: "array",
1091
- description: "Identifiers of the settings resources this endpoint reads. It receives exactly these, read-only, as settings.<identifier>",
1092
- items: {
1093
- type: "string",
1094
- pattern: "^[a-z][a-z0-9_]*$"
1095
- },
1096
- uniqueItems: true
1097
- },
1098
- writes: {
1099
- type: "array",
1100
- description: "Identifiers of the capabilities this endpoint may change. The context patch a handler returns is held to this list, and an endpoint declaring none cannot change state at all.",
1101
- items: {
1102
- type: "string",
1103
- pattern: "^[a-z][a-z0-9_]*$"
1104
- },
1105
- uniqueItems: true
1106
- },
1107
- uses: {
1108
- type: "array",
1109
- description: "Runtime callback APIs this endpoint is permitted to invoke. The runtime throws when this endpoint calls a callback whose name is not listed here.",
1110
- items: { $ref: "#/$defs/ApiUse" },
1111
- uniqueItems: true,
1112
- default: []
1113
- },
1114
- actions: {
1115
- type: "array",
1116
- description: "Session actions this endpoint may return beside its response, such as closing the waiting room or advancing a tick. The runtime carries them out, in order, after the endpoint's write.",
1117
- items: { $ref: "#/$defs/EndpointActionType" },
1118
- uniqueItems: true
1119
- },
1120
- responds: {
1121
- type: "boolean",
1122
- description: "Generated, not authored. Whether the endpoint answers in two phases: its logic exports `Plan`, which returns the effects alone, and `Respond`, which the runtime calls once they have been applied to write the response from the state they left. An endpoint that answers in one exports `Handle`. The build derives this from the exports and writes it into the bundled manifest; authoring it in endpoint.sdk.json is an error"
1123
- },
1124
- roster: {
1125
- type: "boolean",
1126
- description: "Whether the handler's `session` argument lists each team's participants. Off by default, because the list grows with the cohort and most endpoints do not need it.",
1127
- default: false
1128
- },
1129
- visibility: {
1130
- type: "string",
1131
- enum: ["internal", "external"],
1132
- description: "Who may invoke this endpoint. `internal` endpoints are reached only by the game's own user interfaces; `external` ones may also be invoked by callers outside the game, such as a facilitator's AI agent or a platform API, subject to the platform's own authorisation. Absent means `internal`, so an endpoint written for a game's own screens is never published unless its author says so.",
1133
- default: "internal"
1134
- }
1135
- },
1136
- required: ["identifier", "requestSchema", "responseSchema"],
1137
- additionalProperties: false
1138
- },
1139
- SDKEndpoint: {
1140
- type: "object",
1141
- description: "Bundle containing an endpoint definition and its logic layout",
1142
- properties: {
1143
- definition: { $ref: "#/$defs/EndpointDefinition" },
1144
- logic: { $ref: "#/$defs/LogicLayout" },
1145
- rootDirectory: {
1146
- type: "string",
1147
- description: "Directory containing this resource's files, relative to the bundle file. Must use forward slashes, not Windows separators",
1148
- pattern: "^[^\\\\]+$"
1149
- }
1150
- },
1151
- required: ["definition", "logic", "rootDirectory"],
1152
- additionalProperties: false
1153
- },
1154
- ResolvedPackageManifest: {
1155
- type: "object",
1156
- description: "Every resource a package holds: the shape the loader builds from disk and the shape the build writes to seriousgaming.json. A game holds one of nine kinds, each in its own field; everything a package may hold more than one of is an array.",
1157
- properties: {
1158
- manifestVersion: {
1159
- type: "integer",
1160
- minimum: 1,
1161
- description: "Format version of this manifest. Absent means 1. Runtimes MUST treat an absent value as 1 and MUST reject a version they do not implement."
1162
- },
1163
- requires: { $ref: "#/$defs/RequiredFeatures" },
1164
- scenarioFormat: { $ref: "#/$defs/ScenarioFormat" },
1165
- builtWith: { $ref: "#/$defs/BuiltWith" },
1166
- package: { $ref: "#/$defs/SDKPackage" },
1167
- game: { $ref: "#/$defs/SDKGame" },
1168
- engine: { $ref: "#/$defs/SDKEngine" },
1169
- ui: { $ref: "#/$defs/SDKUserInterface" },
1170
- session: { $ref: "#/$defs/SDKSessionUserInterface" },
1171
- waiting_room: { $ref: "#/$defs/SDKWaitingRoomUserInterface" },
1172
- presentation: { $ref: "#/$defs/SDKPresentation" },
1173
- setup: {
1174
- $ref: "#/$defs/SDKSetup"
1175
- },
1176
- scenario_editor: {
1177
- $ref: "#/$defs/SDKScenarioEditor"
1178
- },
1179
- tick_controller: { $ref: "#/$defs/SDKTickController" },
1180
- guide: { $ref: "#/$defs/SDKFacilitatorGuide" },
1181
- capabilities: {
1182
- type: "array",
1183
- items: { $ref: "#/$defs/SDKCapability" }
1184
- },
1185
- settings: {
1186
- type: "array",
1187
- items: { $ref: "#/$defs/SDKSettings" }
1188
- },
1189
- scenarios: {
1190
- type: "array",
1191
- items: { $ref: "#/$defs/SDKScenario" }
1192
- },
1193
- hooks: {
1194
- type: "array",
1195
- items: { $ref: "#/$defs/SDKHook" }
1196
- },
1197
- validators: {
1198
- type: "array",
1199
- items: { $ref: "#/$defs/SDKValidator" }
1200
- },
1201
- endpoints: {
1202
- type: "array",
1203
- items: { $ref: "#/$defs/SDKEndpoint" }
1204
- }
1205
- },
1206
- required: ["package", "game"],
1207
- additionalProperties: false
1208
- },
1209
- LogicLayout: {
1210
- type: "object",
1211
- description: "Where a logic-bearing resource keeps its code, and what its entrypoint is called",
1212
- properties: {
1213
- directory: {
1214
- type: "string",
1215
- description: "Subdirectory containing logic files"
1216
- },
1217
- entrypoint: {
1218
- type: "string",
1219
- description: "Path to the TypeScript entrypoint file (e.g., logic.ts)"
1220
- }
1221
- },
1222
- required: ["directory", "entrypoint"],
1223
- additionalProperties: false
1224
- },
1225
- SDKPackage: {
1226
- type: "object",
1227
- description: "Bundle containing a package definition",
1228
- properties: {
1229
- definition: { $ref: "#/$defs/PackageDefinition" }
1230
- },
1231
- required: ["definition"],
1232
- additionalProperties: false
1233
- },
1234
- SDKEngine: {
1235
- type: "object",
1236
- description: "Bundle containing an engine definition and its logic layout",
1237
- properties: {
1238
- definition: { $ref: "#/$defs/EngineDefinition" },
1239
- logic: { $ref: "#/$defs/LogicLayout" },
1240
- rootDirectory: {
1241
- type: "string",
1242
- description: "Directory containing this resource's files, relative to the bundle file. Must use forward slashes, not Windows separators",
1243
- pattern: "^[^\\\\]+$"
1244
- }
1245
- },
1246
- required: ["definition", "logic", "rootDirectory"],
1247
- additionalProperties: false
1248
- },
1249
- SDKCapability: {
1250
- type: "object",
1251
- description: "Bundle containing a capability definition",
1252
- properties: {
1253
- definition: { $ref: "#/$defs/CapabilityDefinition" }
1254
- },
1255
- required: ["definition"],
1256
- additionalProperties: false
1257
- },
1258
- SDKScenario: {
1259
- type: "object",
1260
- description: "Bundle containing a scenario definition and root directory for assets",
1261
- properties: {
1262
- definition: { $ref: "#/$defs/ScenarioDefinition" },
1263
- rootDirectory: {
1264
- type: "string",
1265
- description: "Root directory where scenario assets are located. Must use forward slashes, not Windows separators",
1266
- pattern: "^[^\\\\]+$"
1267
- }
1268
- },
1269
- required: ["definition", "rootDirectory"],
1270
- additionalProperties: false
1271
- },
1272
- SDKFacilitatorGuide: {
1273
- type: "object",
1274
- description: "Bundle containing a facilitator guide definition and root directory for content and assets",
1275
- properties: {
1276
- definition: { $ref: "#/$defs/FacilitatorGuideDefinition" },
1277
- rootDirectory: {
1278
- type: "string",
1279
- description: "Root directory where guide content and assets are located. Must use forward slashes, not Windows separators",
1280
- pattern: "^[^\\\\]+$"
1281
- }
1282
- },
1283
- required: ["definition", "rootDirectory"],
1284
- additionalProperties: false
1285
- },
1286
- SDKUserInterface: {
1287
- type: "object",
1288
- description: "Bundle containing a user interface definition and entrypoint",
1289
- properties: {
1290
- definition: { $ref: "#/$defs/UserInterfaceDefinition" },
1291
- rootDirectory: {
1292
- type: "string",
1293
- description: "Directory containing this resource's files, relative to the bundle file. Must use forward slashes, not Windows separators",
1294
- pattern: "^[^\\\\]+$"
1295
- },
1296
- ui: {
1297
- type: "object",
1298
- description: "Where this surface's entrypoint is. A UI's web files sit in the resource's own directory, so only the entrypoint's name varies",
1299
- properties: {
1300
- entrypoint: {
1301
- type: "string",
1302
- description: "Entrypoint file, in the resource's own directory (e.g., 'index.html')"
1303
- }
1304
- },
1305
- required: ["entrypoint"],
1306
- additionalProperties: false
1307
- }
1308
- },
1309
- required: ["definition", "rootDirectory", "ui"],
1310
- additionalProperties: false
1311
- },
1312
- SDKSessionUserInterface: {
1313
- type: "object",
1314
- description: "Bundle containing a session user interface definition and entrypoint",
1315
- properties: {
1316
- definition: { $ref: "#/$defs/SessionUserInterfaceDefinition" },
1317
- rootDirectory: {
1318
- type: "string",
1319
- description: "Directory containing this resource's files, relative to the bundle file. Must use forward slashes, not Windows separators",
1320
- pattern: "^[^\\\\]+$"
1321
- },
1322
- ui: {
1323
- type: "object",
1324
- description: "Where this surface's entrypoint is. A UI's web files sit in the resource's own directory, so only the entrypoint's name varies",
1325
- properties: {
1326
- entrypoint: {
1327
- type: "string",
1328
- description: "Entrypoint file, in the resource's own directory (e.g., 'index.html')"
1329
- }
1330
- },
1331
- required: ["entrypoint"],
1332
- additionalProperties: false
1333
- }
1334
- },
1335
- required: ["definition", "rootDirectory", "ui"],
1336
- additionalProperties: false
1337
- },
1338
- SDKSetup: {
1339
- type: "object",
1340
- description: "Bundle containing the setup user interface definition and entrypoint",
1341
- properties: {
1342
- definition: {
1343
- $ref: "#/$defs/SetupDefinition"
1344
- },
1345
- rootDirectory: {
1346
- type: "string",
1347
- description: "Directory containing this resource's files, relative to the bundle file. Must use forward slashes, not Windows separators",
1348
- pattern: "^[^\\\\]+$"
1349
- },
1350
- ui: {
1351
- type: "object",
1352
- description: "Where this surface's entrypoint is. A UI's web files sit in the resource's own directory, so only the entrypoint's name varies",
1353
- properties: {
1354
- entrypoint: {
1355
- type: "string",
1356
- description: "Entrypoint file, in the resource's own directory (e.g., 'index.html')"
1357
- }
1358
- },
1359
- required: ["entrypoint"],
1360
- additionalProperties: false
1361
- }
1362
- },
1363
- required: ["definition", "rootDirectory", "ui"],
1364
- additionalProperties: false
1365
- },
1366
- SDKScenarioEditor: {
1367
- type: "object",
1368
- description: "Bundle containing the scenario editor definition and entrypoint",
1369
- properties: {
1370
- definition: {
1371
- $ref: "#/$defs/ScenarioEditorDefinition"
1372
- },
1373
- rootDirectory: {
1374
- type: "string",
1375
- description: "Directory containing this resource's files, relative to the bundle file. Must use forward slashes, not Windows separators",
1376
- pattern: "^[^\\\\]+$"
1377
- },
1378
- ui: {
1379
- type: "object",
1380
- description: "Where this surface's entrypoint is. A UI's web files sit in the resource's own directory, so only the entrypoint's name varies",
1381
- properties: {
1382
- entrypoint: {
1383
- type: "string",
1384
- description: "Entrypoint file, in the resource's own directory (e.g., 'index.html')"
1385
- }
1386
- },
1387
- required: ["entrypoint"],
1388
- additionalProperties: false
1389
- }
1390
- },
1391
- required: ["definition", "rootDirectory", "ui"],
1392
- additionalProperties: false
1393
- },
1394
- PresentationDefinition: {
1395
- type: "object",
1396
- description: "Definition of a presentation: the slides a facilitator shows the room, rendered from a UI bundle of the game's own. Read-only by construction: it declares no writes, no endpoints and no callback uses, and it may be shown with no session at all",
1397
- properties: {
1398
- identifier: {
1399
- type: "string",
1400
- description: "Namespace-style identifier for the presentation",
1401
- pattern: "^[a-z][a-z0-9_]*$"
1402
- },
1403
- locales: {
1404
- type: "object",
1405
- description: "Display name per locale, for the host to label the presentation with",
1406
- additionalProperties: {
1407
- type: "object",
1408
- properties: {
1409
- name: { type: "string" }
1410
- },
1411
- required: ["name"],
1412
- additionalProperties: false
1413
- }
1414
- },
1415
- reads: {
1416
- type: "array",
1417
- description: "Identifiers of the capabilities this presentation reads, from every team and the shared store, when it is shown during a session",
1418
- items: {
1419
- type: "string",
1420
- pattern: "^[a-z][a-z0-9_]*$"
1421
- },
1422
- uniqueItems: true
1423
- },
1424
- settings: {
1425
- type: "array",
1426
- description: "Identifiers of the settings resources this presentation reads. It receives exactly these, read-only, as settings.<identifier>, with or without a session",
1427
- items: {
1428
- type: "string",
1429
- pattern: "^[a-z][a-z0-9_]*$"
1430
- },
1431
- uniqueItems: true
1432
- }
1433
- },
1434
- required: ["identifier"],
1435
- additionalProperties: false
1436
- },
1437
- SDKPresentation: {
1438
- type: "object",
1439
- description: "Bundle containing a presentation definition and entrypoint",
1440
- properties: {
1441
- definition: { $ref: "#/$defs/PresentationDefinition" },
1442
- rootDirectory: {
1443
- type: "string",
1444
- description: "Directory containing this resource's files, relative to the bundle file. Must use forward slashes, not Windows separators",
1445
- pattern: "^[^\\\\]+$"
1446
- },
1447
- ui: {
1448
- type: "object",
1449
- description: "Where this surface's entrypoint is. A UI's web files sit in the resource's own directory, so only the entrypoint's name varies",
1450
- properties: {
1451
- entrypoint: {
1452
- type: "string",
1453
- description: "Entrypoint file, in the resource's own directory (e.g., 'index.html')"
1454
- }
1455
- },
1456
- required: ["entrypoint"],
1457
- additionalProperties: false
1458
- }
1459
- },
1460
- required: ["definition", "rootDirectory", "ui"],
1461
- additionalProperties: false
1462
- },
1463
- SDKWaitingRoomUserInterface: {
1464
- type: "object",
1465
- description: "Bundle containing a waiting room user interface definition and entrypoint",
1466
- properties: {
1467
- definition: { $ref: "#/$defs/WaitingRoomUserInterfaceDefinition" },
1468
- rootDirectory: {
1469
- type: "string",
1470
- description: "Directory containing this resource's files, relative to the bundle file. Must use forward slashes, not Windows separators",
1471
- pattern: "^[^\\\\]+$"
1472
- },
1473
- ui: {
1474
- type: "object",
1475
- description: "Where this surface's entrypoint is. A UI's web files sit in the resource's own directory, so only the entrypoint's name varies",
1476
- properties: {
1477
- entrypoint: {
1478
- type: "string",
1479
- description: "Entrypoint file, in the resource's own directory (e.g., 'index.html')"
1480
- }
1481
- },
1482
- required: ["entrypoint"],
1483
- additionalProperties: false
1484
- }
1485
- },
1486
- required: ["definition", "rootDirectory", "ui"],
1487
- additionalProperties: false
1488
- },
1489
- SDKGame: {
1490
- type: "object",
1491
- description: "Bundle containing a game definition",
1492
- properties: {
1493
- definition: { $ref: "#/$defs/GameDefinition" },
1494
- rootDirectory: {
1495
- type: "string",
1496
- description: "Root directory where game files are located (e.g., '.'). Must use forward slashes, not Windows separators",
1497
- pattern: "^[^\\\\]+$"
1498
- }
1499
- },
1500
- required: ["definition", "rootDirectory"],
1501
- additionalProperties: false
1502
- },
1503
- PackageManifest: {
1504
- type: "object",
1505
- description: "A package, which is a game: its identifier and the game's settings. What it declares are the resources on disk under the conventional directories beside this file. The version comes from package.json, and the game's identifier is the package identifier with `.game` appended.",
1506
- properties: {
1507
- identifier: {
1508
- type: "string",
1509
- description: "Namespace-style identifier for the package. Every resource identifier sits under it, and the game's identifier is it with `.game` appended.",
1510
- pattern: "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$"
1511
- },
1512
- requires: { $ref: "#/$defs/RequiredFeatures" },
1513
- scenarioFormat: { $ref: "#/$defs/ScenarioFormat" },
1514
- supportedLocales: { $ref: "#/$defs/GameSupportedLocales" },
1515
- locales: { $ref: "#/$defs/GameLocales" },
1516
- maxTicks: {
1517
- type: "integer",
1518
- minimum: 1,
1519
- description: "The number of ticks (rounds) the game plays before it is complete. A tick can stand for an hour, a day, a week, or something more abstract. Omit it when the game ends by its tick controller or its engine instead. The default for the `game` settings' `maxTicks`, which a scenario or a session may override"
1520
- },
1521
- teams: { $ref: "#/$defs/GameTeams" },
1522
- waitingRoom: { $ref: "#/$defs/GameWaitingRoomSettings" },
1523
- gameSettingsConstraints: { $ref: "#/$defs/GameSettingsConstraints" },
1524
- customScenarios: { $ref: "#/$defs/GameCustomScenarios" }
1525
- },
1526
- required: ["identifier", "supportedLocales", "locales"],
1527
- additionalProperties: false
1528
- }
1529
- },
1530
- type: "object",
1531
- properties: {
1532
- PackageDefinition: { $ref: "#/$defs/PackageDefinition" },
1533
- EngineDefinition: { $ref: "#/$defs/EngineDefinition" },
1534
- CapabilityDefinition: { $ref: "#/$defs/CapabilityDefinition" },
1535
- SettingsDefinition: { $ref: "#/$defs/SettingsDefinition" },
1536
- SDKSettings: { $ref: "#/$defs/SDKSettings" },
1537
- SetupDefinition: {
1538
- $ref: "#/$defs/SetupDefinition"
1539
- },
1540
- ScenarioEditorDefinition: {
1541
- $ref: "#/$defs/ScenarioEditorDefinition"
1542
- },
1543
- ScenarioDefinition: { $ref: "#/$defs/ScenarioDefinition" },
1544
- UserInterfaceDefinition: { $ref: "#/$defs/UserInterfaceDefinition" },
1545
- GameDefinition: { $ref: "#/$defs/GameDefinition" },
1546
- SessionUserInterfaceDefinition: { $ref: "#/$defs/SessionUserInterfaceDefinition" },
1547
- SDKSessionUserInterface: { $ref: "#/$defs/SDKSessionUserInterface" },
1548
- WaitingRoomUserInterfaceDefinition: {
1549
- $ref: "#/$defs/WaitingRoomUserInterfaceDefinition"
1550
- },
1551
- SDKWaitingRoomUserInterface: { $ref: "#/$defs/SDKWaitingRoomUserInterface" },
1552
- PresentationDefinition: { $ref: "#/$defs/PresentationDefinition" },
1553
- SDKPresentation: { $ref: "#/$defs/SDKPresentation" },
1554
- GameSupportedLocales: { $ref: "#/$defs/GameSupportedLocales" },
1555
- GameLocales: { $ref: "#/$defs/GameLocales" },
1556
- GameCustomScenarios: { $ref: "#/$defs/GameCustomScenarios" },
1557
- GameTeams: { $ref: "#/$defs/GameTeams" },
1558
- GameTeamMode: { $ref: "#/$defs/GameTeamMode" },
1559
- GameSettings: { $ref: "#/$defs/GameSettings" },
1560
- GameSettingConstraint: { $ref: "#/$defs/GameSettingConstraint" },
1561
- GameSettingsConstraints: { $ref: "#/$defs/GameSettingsConstraints" },
1562
- GameWaitingRoomOpenOnStart: { $ref: "#/$defs/GameWaitingRoomOpenOnStart" },
1563
- GameWaitingRoomSettings: { $ref: "#/$defs/GameWaitingRoomSettings" },
1564
- FacilitatorGuideDefinition: { $ref: "#/$defs/FacilitatorGuideDefinition" },
1565
- SDKFacilitatorGuide: { $ref: "#/$defs/SDKFacilitatorGuide" },
1566
- ResolvedPackageManifest: { $ref: "#/$defs/ResolvedPackageManifest" },
1567
- LogicLayout: { $ref: "#/$defs/LogicLayout" },
1568
- SDKPackage: { $ref: "#/$defs/SDKPackage" },
1569
- SDKEngine: { $ref: "#/$defs/SDKEngine" },
1570
- SDKCapability: { $ref: "#/$defs/SDKCapability" },
1571
- SDKScenario: { $ref: "#/$defs/SDKScenario" },
1572
- SDKUserInterface: { $ref: "#/$defs/SDKUserInterface" },
1573
- SDKSetup: {
1574
- $ref: "#/$defs/SDKSetup"
1575
- },
1576
- SDKScenarioEditor: {
1577
- $ref: "#/$defs/SDKScenarioEditor"
1578
- },
1579
- SDKGame: { $ref: "#/$defs/SDKGame" },
1580
- PackageManifest: { $ref: "#/$defs/PackageManifest" },
1581
- TickControllerDefinition: { $ref: "#/$defs/TickControllerDefinition" },
1582
- SDKTickController: { $ref: "#/$defs/SDKTickController" },
1583
- ApiUse: { $ref: "#/$defs/ApiUse" },
1584
- EndpointActionType: { $ref: "#/$defs/EndpointActionType" },
1585
- GlobalSettings: { $ref: "#/$defs/GlobalSettings" },
1586
- HookSignal: { $ref: "#/$defs/HookSignal" },
1587
- HookDefinition: { $ref: "#/$defs/HookDefinition" },
1588
- SDKHook: { $ref: "#/$defs/SDKHook" },
1589
- ValidatorDefinition: { $ref: "#/$defs/ValidatorDefinition" },
1590
- SDKValidator: { $ref: "#/$defs/SDKValidator" },
1591
- EndpointDefinition: { $ref: "#/$defs/EndpointDefinition" },
1592
- SDKEndpoint: { $ref: "#/$defs/SDKEndpoint" }
1593
- },
1594
- additionalProperties: false
1595
- };
1596
-
1597
- // cli/core/game-settings.ts
1598
- var GAME_SETTINGS = "game";
1599
- var TITLES = {
1600
- maxTicks: "Number of rounds",
1601
- "teams.min": "Minimum teams",
1602
- "teams.max": "Maximum teams",
1603
- "teams.perTeam.minParticipants": "Minimum participants per team",
1604
- "teams.perTeam.maxParticipants": "Maximum participants per team",
1605
- "teams.defaultNames": "Default team names",
1606
- "teams.sessionJoin": "Offer a session join link",
1607
- "waitingRoom.openOnStart": "Open the waiting room on start"
1608
- };
1609
- function gameSettingsDefaults(manifest) {
1610
- const teams = manifest.teams;
1611
- return {
1612
- maxTicks: manifest.maxTicks ?? null,
1613
- teams: {
1614
- min: teams?.min ?? null,
1615
- max: teams?.max ?? null,
1616
- perTeam: {
1617
- minParticipants: teams?.perTeam?.minParticipants ?? null,
1618
- maxParticipants: teams?.perTeam?.maxParticipants ?? null
1619
- },
1620
- defaultNames: teams?.defaultNames ?? [],
1621
- sessionJoin: teams?.sessionJoin !== false
1622
- },
1623
- waitingRoom: { openOnStart: manifest.waitingRoom?.openOnStart === true }
1624
- };
1625
- }
1626
- function gameSettingsResource(manifest) {
1627
- const schema2 = structuredClone(schema_default.$defs.GameSettings);
1628
- withDefaults(schema2, gameSettingsDefaults(manifest), "");
1629
- withConstraints(schema2, manifest.gameSettingsConstraints ?? {});
1630
- return {
1631
- definition: {
1632
- identifier: GAME_SETTINGS,
1633
- settingsSchema: schema2
1634
- }
1635
- };
1636
- }
1637
- function withDefaults(schema2, value, path) {
1638
- for (const [key, property] of Object.entries(schema2.properties ?? {})) {
1639
- if (typeof property !== "object") continue;
1640
- const at = path === "" ? key : `${path}.${key}`;
1641
- const child = value[key];
1642
- property.default = structuredClone(child);
1643
- const title = TITLES[at];
1644
- if (title !== void 0) property.title = title;
1645
- if (property.properties) withDefaults(property, child, at);
1646
- }
1647
- }
1648
- function withConstraints(schema2, constraints) {
1649
- for (const [key, constraint] of Object.entries(constraints)) {
1650
- const property = schema2.properties?.[key];
1651
- if (typeof property !== "object" || constraint === null) continue;
1652
- if (property.properties) {
1653
- withConstraints(property, constraint);
1654
- continue;
1655
- }
1656
- const leaf = constraint;
1657
- if (leaf.minimum !== void 0) property.minimum = leaf.minimum;
1658
- if (leaf.maximum !== void 0) property.maximum = leaf.maximum;
1659
- if ((leaf.minimum !== void 0 || leaf.maximum !== void 0) && Array.isArray(property.type)) {
1660
- const types = property.type.filter((type) => type !== "null");
1661
- property.type = types.length === 1 ? types[0] : types;
1662
- }
1663
- if (leaf.enum !== void 0) property.enum = leaf.enum;
1664
- if (leaf.readOnly === true) property.readOnly = true;
1665
- }
1666
- }
1667
- function gameSettingConstraints(constraints) {
1668
- const leaves = /* @__PURE__ */ new Map();
1669
- const sdk = schema_default.$defs.GameSettings;
1670
- const walk = (schema2, value, at) => {
1671
- for (const [key, constraint] of Object.entries(value)) {
1672
- const property = schema2.properties?.[key];
1673
- if (typeof property !== "object" || constraint === null) continue;
1674
- const path = at === "" ? key : `${at}.${key}`;
1675
- if (property.properties) walk(property, constraint, path);
1676
- else leaves.set(path, constraint);
1677
- }
1678
- };
1679
- walk(sdk, constraints ?? {}, "");
1680
- return leaves;
1681
- }
1682
- function teamsMaxOf(schema2) {
1683
- const teams = schema2?.properties?.teams;
1684
- const max = typeof teams === "object" ? teams.properties?.max : void 0;
1685
- if (typeof max !== "object") return { max: null, locked: false };
1686
- return {
1687
- max: typeof max.default === "number" ? max.default : null,
1688
- locked: max.readOnly === true
1689
- };
1690
- }
1691
- function gameSettingsOf(resolved) {
1692
- const neutral = gameSettingsDefaults({});
1693
- const game = resolved[GAME_SETTINGS] ?? {};
1694
- return {
1695
- maxTicks: game.maxTicks ?? null,
1696
- teams: {
1697
- min: game.teams?.min ?? null,
1698
- max: game.teams?.max ?? null,
1699
- perTeam: {
1700
- minParticipants: game.teams?.perTeam?.minParticipants ?? null,
1701
- maxParticipants: game.teams?.perTeam?.maxParticipants ?? null
1702
- },
1703
- defaultNames: game.teams?.defaultNames ?? neutral.teams.defaultNames,
1704
- sessionJoin: game.teams?.sessionJoin !== false
1705
- },
1706
- waitingRoom: { openOnStart: game.waitingRoom?.openOnStart === true }
1707
- };
1708
- }
1709
- function declaredGameSettings(schema2) {
1710
- const properties = schema2?.properties;
1711
- const defaults = Object.fromEntries(
1712
- Object.entries(properties ?? {}).map(([key, property]) => [
1713
- key,
1714
- typeof property === "object" ? property.default : void 0
1715
- ])
1716
- );
1717
- return gameSettingsOf({ [GAME_SETTINGS]: defaults });
1718
- }
1719
- function gameOverrideRefusal(overrides) {
1720
- if (overrides === null || typeof overrides !== "object") return null;
1721
- const game = overrides[GAME_SETTINGS];
1722
- if (game === null || typeof game !== "object") return null;
1723
- if ("waitingRoom" in game) {
1724
- return "game.waitingRoom.openOnStart cannot be set for a session: it seeds the waiting room as the session is created, before setup. Set it in the manifest or a scenario instead";
1725
- }
1726
- const teams = game.teams;
1727
- if (teams !== null && typeof teams === "object" && "sessionJoin" in teams) {
1728
- return "game.teams.sessionJoin cannot be set for a session: it is read as the session is created, before setup, so the session link cannot switch on and off while people are arriving. Set it in the manifest or a scenario instead";
1729
- }
1730
- return null;
1731
- }
1732
-
1733
- // cli/templating/resource-metadata.ts
1734
- var MANIFEST_REFERRER = "__manifest__";
1735
- var LOGIC_IN_SLOT = { logic: { directory: ".", entrypoint: "logic.ts" } };
1736
- var LOGIC_SUBDIRECTORY = {
1737
- logic: { directory: "logic", entrypoint: "logic.ts" }
1738
- };
1739
- var UI_IN_SLOT = { ui: { entrypoint: "index.html" } };
1740
- var BASES = [
1741
- {
1742
- type: "capability",
1743
- pluralDir: "capabilities",
1744
- bundleFile: "capability.sdk.json",
1745
- manifestKey: "capabilities",
1746
- kind: "composition",
1747
- label: "Capability",
1748
- mergeDefinition: true,
1749
- referencedByReadsWrites: true
1750
- },
1751
- {
1752
- type: "engine",
1753
- slot: "engine",
1754
- layout: LOGIC_IN_SLOT,
1755
- bundleFile: "engine.sdk.json",
1756
- manifestKey: "engine",
1757
- kind: "logic",
1758
- label: "Engine",
1759
- hasReads: true,
1760
- hasWrites: true,
1761
- readsSettings: true,
1762
- sites: []
1763
- },
1764
- {
1765
- type: "ui",
1766
- slot: "ui",
1767
- layout: UI_IN_SLOT,
1768
- bundleFile: "ui.sdk.json",
1769
- manifestKey: "ui",
1770
- kind: "ui",
1771
- label: "User interface",
1772
- hasReads: true,
1773
- hasWrites: true,
1774
- hasCrossTeamReads: true,
1775
- declaresEndpoints: true,
1776
- readsSettings: true,
1777
- sites: []
1778
- },
1779
- {
1780
- type: "session",
1781
- slot: "session",
1782
- layout: UI_IN_SLOT,
1783
- bundleFile: "session.sdk.json",
1784
- manifestKey: "session",
1785
- kind: "ui",
1786
- label: "Session user interface",
1787
- hasReads: true,
1788
- hasWrites: true,
1789
- declaresEndpoints: true,
1790
- readsSettings: true,
1791
- sites: []
1792
- },
1793
- {
1794
- type: "waiting_room",
1795
- slot: "waiting_room",
1796
- layout: UI_IN_SLOT,
1797
- bundleFile: "waiting_room.sdk.json",
1798
- manifestKey: "waiting_room",
1799
- kind: "ui",
1800
- label: "Waiting room user interface",
1801
- hasReads: true,
1802
- hasWrites: true,
1803
- hasCrossTeamReads: true,
1804
- declaresEndpoints: true,
1805
- readsSettings: true,
1806
- sites: []
1807
- },
1808
- {
1809
- type: "presentation",
1810
- slot: "presentation",
1811
- layout: UI_IN_SLOT,
1812
- bundleFile: "presentation.sdk.json",
1813
- manifestKey: "presentation",
1814
- kind: "ui",
1815
- label: "Presentation",
1816
- hasReads: true,
1817
- readsSettings: true,
1818
- sites: []
1819
- },
1820
- // The two settings editors (§6.5): one layout, both naming the settings
1821
- // they edit in `configures`. Neither ever lived under a plural directory;
1822
- // the version 2 settings editors they replace did, and the loader refuses
1823
- // that directory with its own message.
1824
- {
1825
- type: "setup",
1826
- slot: "setup",
1827
- layout: UI_IN_SLOT,
1828
- bundleFile: "setup.sdk.json",
1829
- manifestKey: "setup",
1830
- kind: "ui",
1831
- label: "Setup user interface",
1832
- declaresEndpoints: true,
1833
- sites: []
1834
- },
1835
- {
1836
- type: "scenario_editor",
1837
- slot: "scenario_editor",
1838
- layout: UI_IN_SLOT,
1839
- bundleFile: "scenario_editor.sdk.json",
1840
- manifestKey: "scenario_editor",
1841
- kind: "ui",
1842
- label: "Scenario editor",
1843
- declaresEndpoints: true,
1844
- sites: []
1845
- },
1846
- {
1847
- type: "scenario",
1848
- pluralDir: "scenarios",
1849
- bundleFile: "scenario.sdk.json",
1850
- manifestKey: "scenarios",
1851
- kind: "content",
1852
- label: "Scenario",
1853
- sites: []
1854
- },
1855
- {
1856
- type: "guide",
1857
- slot: "guide",
1858
- bundleFile: "guide.sdk.json",
1859
- manifestKey: "guide",
1860
- kind: "content",
1861
- label: "Facilitator guide",
1862
- sites: []
1863
- },
1864
- {
1865
- type: "tick_controller",
1866
- slot: "tick_controller",
1867
- layout: LOGIC_IN_SLOT,
1868
- bundleFile: "tick_controller.sdk.json",
1869
- manifestKey: "tick_controller",
1870
- kind: "logic",
1871
- label: "Tick controller",
1872
- hasReads: true,
1873
- readsSettings: true,
1874
- sites: []
1875
- },
1876
- {
1877
- type: "hook",
1878
- layout: LOGIC_SUBDIRECTORY,
1879
- pluralDir: "hooks",
1880
- bundleFile: "hook.sdk.json",
1881
- manifestKey: "hooks",
1882
- kind: "logic",
1883
- label: "Hook",
1884
- hasReads: true,
1885
- hasWrites: true,
1886
- readsSettings: true,
1887
- sites: []
1888
- },
1889
- {
1890
- type: "validator",
1891
- layout: LOGIC_SUBDIRECTORY,
1892
- pluralDir: "validators",
1893
- bundleFile: "validator.sdk.json",
1894
- manifestKey: "validators",
1895
- kind: "logic",
1896
- label: "Validator",
1897
- hasReads: true,
1898
- readsSettings: true,
1899
- sites: []
1900
- },
1901
- {
1902
- type: "endpoint",
1903
- layout: LOGIC_SUBDIRECTORY,
1904
- pluralDir: "endpoints",
1905
- bundleFile: "endpoint.sdk.json",
1906
- manifestKey: "endpoints",
1907
- kind: "logic",
1908
- label: "Endpoint",
1909
- hasReads: true,
1910
- readsSettings: true,
1911
- referencedByEndpointDeclarers: true,
1912
- sites: []
1913
- },
1914
- {
1915
- type: "settings",
1916
- pluralDir: "settings",
1917
- bundleFile: "settings.sdk.json",
1918
- manifestKey: "settings",
1919
- kind: "composition",
1920
- label: "Settings",
1921
- referencedBySettingsReaders: true,
1922
- sites: [
1923
- {
1924
- referrerKeys: ["setup", "scenario_editor"],
1925
- shape: { kind: "stringArray", path: "configures", labelSuffix: "configures" }
1926
- },
1927
- {
1928
- referrerKeys: ["scenarios"],
1929
- shape: { kind: "keyedMap", path: "settings" }
1930
- }
1931
- ]
1932
- }
1933
- ];
1934
- var READS_BEARERS = BASES.filter((b) => b.hasReads).map((b) => b.manifestKey);
1935
- var WRITES_BEARERS = BASES.filter((b) => b.hasWrites).map((b) => b.manifestKey);
1936
- var CROSS_TEAM_READS_BEARERS = BASES.filter((b) => b.hasCrossTeamReads).map((b) => b.manifestKey);
1937
- var ENDPOINT_DECLARERS = BASES.filter((b) => b.declaresEndpoints).map((b) => b.manifestKey);
1938
- var SETTINGS_READERS = BASES.filter((b) => b.readsSettings).map((b) => b.manifestKey);
1939
- function sitesFor(base) {
1940
- const sites = [...base.sites ?? []];
1941
- if (base.referencedByReadsWrites) {
1942
- sites.push({
1943
- referrerKeys: READS_BEARERS,
1944
- shape: { kind: "stringArray", path: "reads", labelSuffix: "reads" }
1945
- });
1946
- sites.push({
1947
- referrerKeys: WRITES_BEARERS,
1948
- shape: { kind: "stringArray", path: "writes", labelSuffix: "writes" }
1949
- });
1950
- sites.push({
1951
- referrerKeys: CROSS_TEAM_READS_BEARERS,
1952
- shape: { kind: "stringArray", path: "crossTeamReads", labelSuffix: "crossTeamReads" }
1953
- });
1954
- }
1955
- if (base.referencedByEndpointDeclarers) {
1956
- sites.push({
1957
- referrerKeys: ENDPOINT_DECLARERS,
1958
- shape: { kind: "stringArray", path: "endpoints" }
1959
- });
1960
- }
1961
- if (base.referencedBySettingsReaders) {
1962
- sites.push({
1963
- referrerKeys: SETTINGS_READERS,
1964
- shape: { kind: "stringArray", path: "settings", labelSuffix: "settings" }
1965
- });
1966
- }
1967
- return sites;
1968
- }
1969
- var RESOURCE_METADATA = BASES.map((base) => ({
1970
- type: base.type,
1971
- ...base.slot ? { slot: base.slot } : { pluralDir: base.pluralDir },
1972
- layout: base.layout,
1973
- bundleFile: base.bundleFile,
1974
- manifestKey: base.manifestKey,
1975
- kind: base.kind,
1976
- label: base.label,
1977
- mergeDefinition: base.mergeDefinition ?? false,
1978
- hasReads: base.hasReads ?? false,
1979
- hasWrites: base.hasWrites ?? false,
1980
- hasCrossTeamReads: base.hasCrossTeamReads ?? false,
1981
- declaresEndpoints: base.declaresEndpoints ?? false,
1982
- readsSettings: base.readsSettings ?? false,
1983
- referenceSites: sitesFor(base)
1984
- }));
1985
- var RESOURCE_METADATA_BY_TYPE = new Map(
1986
- RESOURCE_METADATA.map((meta) => [meta.type, meta])
1987
- );
1988
- var RESOURCE_METADATA_BY_MANIFEST_KEY = new Map(
1989
- RESOURCE_METADATA.map((meta) => [meta.manifestKey, meta])
1990
- );
1991
- function findResourceMeta(type) {
1992
- return RESOURCE_METADATA_BY_TYPE.get(type);
1993
- }
1994
- function isNamelessInterface(meta) {
1995
- return meta.slot !== void 0 && meta.kind === "ui" && meta.type !== "presentation";
1996
- }
1997
- function getResourceMeta(type) {
1998
- const meta = RESOURCE_METADATA_BY_TYPE.get(type);
1999
- if (!meta) {
2000
- throw new Error(`No resource metadata registered for type "${type}"`);
2001
- }
2002
- return meta;
2003
- }
2004
- function getPluralResourceMeta(type) {
2005
- const meta = getResourceMeta(type);
2006
- if (meta.slot) throw new Error(`${meta.label} lives in a slot, not a plural directory`);
2007
- return meta;
2008
- }
2009
-
2010
- // cli/core/settings-locks.ts
2011
- import { isDeepStrictEqual } from "util";
2012
-
2013
- // ../sdk/lib/build/callbacks.js
2014
- var UndeclaredApiUseError = class extends Error {
2015
- resourceIdentifier;
2016
- api;
2017
- constructor(resourceIdentifier, api) {
2018
- super(`Resource "${resourceIdentifier}" attempted to call callback "${api}" but did not declare it in its bundle's "uses" array. Add "${api}" to the bundle's uses to allow this call.`);
2019
- this.name = "UndeclaredApiUseError";
2020
- this.resourceIdentifier = resourceIdentifier;
2021
- this.api = api;
2022
- }
2023
- };
2024
-
2025
- // ../sdk/lib/build/tick-validation.js
2026
- var MAX_EFFECTIVE_TICK_INTERVAL_MS = 7 * 24 * 60 * 60 * 1e3;
2027
-
2028
- // ../sdk/lib/build/setting-path.js
2029
- var NOT_PLAIN = /[.[\]"\s]/u;
2030
- function isPlainKey(key) {
2031
- return key !== "" && !NOT_PLAIN.test(key);
2032
- }
2033
- function settingPath(identifier, ...keys) {
2034
- let path = isPlainKey(identifier) ? identifier : `[${JSON.stringify(identifier)}]`;
2035
- for (const key of keys) {
2036
- const step = String(key);
2037
- path += isPlainKey(step) ? `.${step}` : `[${JSON.stringify(step)}]`;
2038
- }
2039
- return path;
2040
- }
2041
- function parseSettingPath(path) {
2042
- const steps = [];
2043
- let at = 0;
2044
- while (at < path.length) {
2045
- if (path[at] === "[") {
2046
- const end2 = closingQuote(path, at + 1);
2047
- if (end2 === void 0 || path[end2 + 1] !== "]")
2048
- return void 0;
2049
- let key2;
2050
- try {
2051
- key2 = JSON.parse(path.slice(at + 1, end2 + 1));
2052
- } catch {
2053
- return void 0;
2054
- }
2055
- if (typeof key2 !== "string")
2056
- return void 0;
2057
- steps.push(key2);
2058
- at = end2 + 2;
2059
- continue;
2060
- }
2061
- if (steps.length > 0) {
2062
- if (path[at] !== ".")
2063
- return void 0;
2064
- at += 1;
2065
- }
2066
- let end = at;
2067
- while (end < path.length && path[end] !== "." && path[end] !== "[")
2068
- end += 1;
2069
- const key = path.slice(at, end);
2070
- if (!isPlainKey(key))
2071
- return void 0;
2072
- steps.push(key);
2073
- at = end;
2074
- }
2075
- const [identifier, ...keys] = steps;
2076
- return identifier === void 0 ? void 0 : { identifier, keys };
2077
- }
2078
- function closingQuote(path, start) {
2079
- if (path[start] !== '"')
2080
- return void 0;
2081
- for (let at = start + 1; at < path.length; at += 1) {
2082
- if (path[at] === "\\")
2083
- at += 1;
2084
- else if (path[at] === '"')
2085
- return at;
2086
- }
2087
- return void 0;
2088
- }
2089
-
2090
- // ../sdk/lib/build/validators.js
2091
- var SCENARIO_GATE_READ_LIMIT_BYTES = 10 * 1024 * 1024;
2092
- var ScenarioAssetTooLargeError = class _ScenarioAssetTooLargeError extends Error {
2093
- /** The reference the gate asked to read. */
2094
- reference;
2095
- /** The file's size in bytes. */
2096
- size;
2097
- /** The cap it exceeds: {@link SCENARIO_GATE_READ_LIMIT_BYTES}. */
2098
- limit;
2099
- constructor(reference, size) {
2100
- super(`Cannot read "${reference}" in a Scenario gate: it is ${size} bytes, over the ${SCENARIO_GATE_READ_LIMIT_BYTES}-byte (10 MB) limit on a gate's reads. Call describeAsset to check that it is there or how large it is.`);
2101
- this.name = "ScenarioAssetTooLargeError";
2102
- this.reference = reference;
2103
- this.size = size;
2104
- this.limit = SCENARIO_GATE_READ_LIMIT_BYTES;
2105
- Object.setPrototypeOf(this, _ScenarioAssetTooLargeError.prototype);
2106
- }
2107
- };
2108
-
2109
- // cli/utils/local-refs.ts
2110
- function isLocalRef(ref) {
2111
- return ref === "#" || ref.startsWith("#/");
2112
- }
2113
- function resolveLocalRef(root, ref) {
2114
- if (!isLocalRef(ref)) return void 0;
2115
- let current = root;
2116
- for (const token of ref === "#" ? [] : ref.slice(2).split("/")) {
2117
- const key = decodeToken(token);
2118
- if (current === null || typeof current !== "object") return void 0;
2119
- if (Array.isArray(current)) {
2120
- if (!/^\d+$/.test(key)) return void 0;
2121
- current = current[Number(key)];
2122
- } else {
2123
- if (!Object.prototype.hasOwnProperty.call(current, key)) return void 0;
2124
- current = current[key];
2125
- }
2126
- }
2127
- return typeof current === "boolean" || current !== null && typeof current === "object" && !Array.isArray(current) ? current : void 0;
2128
- }
2129
- function decodeToken(token) {
2130
- let decoded = token;
2131
- try {
2132
- decoded = decodeURIComponent(token);
2133
- } catch {
2134
- }
2135
- return decoded.replace(/~1/g, "/").replace(/~0/g, "~");
2136
- }
2137
- function dereference(root, schema2) {
2138
- let current = schema2;
2139
- const followed = /* @__PURE__ */ new Set();
2140
- while (typeof current.$ref === "string") {
2141
- const { $ref: ref, ...beside } = current;
2142
- const target = followed.has(ref) ? void 0 : resolveLocalRef(root, ref);
2143
- followed.add(ref);
2144
- if (target === void 0 || typeof target !== "object") return beside;
2145
- current = { ...target, ...beside };
2146
- }
2147
- return current;
2148
- }
2149
- var SCHEMA_MAPS = ["properties", "patternProperties", "definitions", "$defs"];
2150
- var SCHEMA_SLOTS = [
2151
- "additionalProperties",
2152
- "additionalItems",
2153
- "contains",
2154
- "propertyNames",
2155
- "if",
2156
- "then",
2157
- "else",
2158
- "not"
2159
- ];
2160
- var SCHEMA_LISTS = ["allOf", "anyOf", "oneOf"];
2161
- function childSchemas(schema2) {
2162
- const found = [];
2163
- const push = (step, child) => {
2164
- if (child !== null && typeof child === "object" && !Array.isArray(child)) {
2165
- found.push({ step, schema: child });
2166
- }
2167
- };
2168
- for (const keyword of SCHEMA_MAPS) {
2169
- const map = schema2[keyword];
2170
- if (!map || typeof map !== "object") continue;
2171
- for (const [key, child] of Object.entries(map))
2172
- push(`${keyword}/${encodeToken(key)}`, child);
2173
- }
2174
- for (const keyword of SCHEMA_SLOTS) push(keyword, schema2[keyword]);
2175
- for (const keyword of SCHEMA_LISTS) {
2176
- schema2[keyword]?.forEach((child, index) => push(`${keyword}/${index}`, child));
2177
- }
2178
- if (Array.isArray(schema2.items)) {
2179
- schema2.items.forEach((child, index) => push(`items/${index}`, child));
2180
- } else {
2181
- push("items", schema2.items);
2182
- }
2183
- return found;
2184
- }
2185
- function encodeToken(key) {
2186
- return key.replace(/~/g, "~0").replace(/\//g, "~1");
2187
- }
2188
- function refProblems(schema2) {
2189
- const problems = [];
2190
- const visit = (node, pointer) => {
2191
- const ref = node.$ref;
2192
- if (typeof ref === "string") {
2193
- if (!isLocalRef(ref)) problems.push({ pointer, ref, reason: "not-local" });
2194
- else if (resolveLocalRef(schema2, ref) === void 0) {
2195
- problems.push({ pointer, ref, reason: "unresolved" });
2196
- }
2197
- }
2198
- for (const child of childSchemas(node)) visit(child.schema, `${pointer}/${child.step}`);
2199
- };
2200
- visit(schema2, "");
2201
- return problems;
2202
- }
2203
- function refProblemMessage(owner, keyword, problem) {
2204
- const at = `${keyword}${problem.pointer}`;
2205
- return problem.reason === "not-local" ? `${owner}: ${at} has "$ref": ${JSON.stringify(problem.ref)}, which is not a reference into the same schema. A reference may only name a part of the schema that holds it, such as "#/$defs/rule"` : `${owner}: ${at} has "$ref": ${JSON.stringify(problem.ref)}, which names nothing in the schema. Add it under $defs, or correct the reference`;
2206
- }
2207
-
2208
- // cli/core/settings-locks.ts
2209
- function lockedPathsNamed(override, schema2) {
2210
- const paths = [];
2211
- if (schema2) named(schema2, schema2, override, [], paths);
2212
- return paths;
2213
- }
2214
- function named(root, declared, value, at, paths) {
2215
- if (value === void 0) return;
2216
- const schema2 = dereference(root, declared);
2217
- if (schema2.readOnly === true) {
2218
- paths.push(at);
2219
- return;
2220
- }
2221
- if (value === null || typeof value !== "object" || Array.isArray(value)) return;
2222
- for (const [key, member] of Object.entries(value)) {
2223
- const property = schema2.properties?.[key];
2224
- if (typeof property === "object") named(root, property, member, [...at, key], paths);
2225
- }
2226
- }
2227
- function unenforceableLocks(schema2) {
2228
- const found = [];
2229
- const visited = /* @__PURE__ */ new Set();
2230
- const walk = (declared, at, inside) => {
2231
- const ref = declared.$ref;
2232
- if (typeof ref === "string") {
2233
- const key = `${inside ? "entry" : "named"}\0${ref}`;
2234
- if (visited.has(key)) return;
2235
- visited.add(key);
2236
- }
2237
- const node = dereference(schema2, declared);
2238
- if (node.readOnly === true) {
2239
- if (inside) found.push({ path: at, ...inside });
2240
- return;
2241
- }
2242
- for (const [key, property] of Object.entries(node.properties ?? {})) {
2243
- if (typeof property === "object") walk(property, [...at, key], inside);
2244
- }
2245
- const entries = { container: at, kind: "map" };
2246
- for (const [pattern, child] of Object.entries(node.patternProperties ?? {})) {
2247
- if (typeof child === "object") walk(child, [...at, `/${pattern}/`], inside ?? entries);
2248
- }
2249
- if (typeof node.additionalProperties === "object") {
2250
- walk(node.additionalProperties, [...at, "*"], inside ?? entries);
2251
- }
2252
- const items = Array.isArray(node.items) ? node.items : node.items ? [node.items] : [];
2253
- for (const item of items) {
2254
- if (typeof item === "object") {
2255
- walk(item, [...at, "[]"], inside ?? { container: at, kind: "list" });
2256
- }
2257
- }
2258
- };
2259
- walk(schema2, [], void 0);
2260
- return found;
2261
- }
2262
- function unenforceableLockMessage(identifier, lock) {
2263
- const where = lock.kind === "list" ? "a list's items" : "a map's entries";
2264
- const container2 = lock.container.length > 0 ? lock.container.join(".") : "the top level";
2265
- return `Settings "${identifier}" property "${lock.path.join(".")}" is readOnly inside ${where}, which a scenario adds and removes, so there is no single value for the lock to keep. Lock the whole ${lock.kind} instead: put readOnly on "${container2}"`;
2266
- }
2267
- function lockedSettingName(identifier, path) {
2268
- return settingPath(identifier, ...path);
2269
- }
2270
- function lockedSettingMessage(identifier, path) {
2271
- return `"${lockedSettingName(identifier, path)}" is read-only: the game fixes it, so no scenario or session may change it`;
2272
- }
2273
- function withoutLockedDefaults(settings, schemas) {
2274
- const result = structuredClone(settings);
2275
- for (const [identifier, schema2] of Object.entries(schemas)) {
2276
- if (!(identifier in result)) continue;
2277
- const defaults = schemaDefaults(schema2);
2278
- for (const path of lockedPathsNamed(result[identifier], schema2)) {
2279
- if (path.length === 0) {
2280
- if (isDeepStrictEqual(result[identifier], defaults)) delete result[identifier];
2281
- continue;
2282
- }
2283
- const value = valueAt(result[identifier], path);
2284
- if (value !== void 0 && isDeepStrictEqual(value, valueAt(defaults, path))) {
2285
- removeAt(result[identifier], path);
2286
- }
2287
- }
2288
- }
2289
- return result;
2290
- }
2291
- function schemaDefaults(schema2) {
2292
- return Object.fromEntries(
2293
- Object.entries(schema2.properties ?? {}).map(([key, property]) => [
2294
- key,
2295
- typeof property === "object" ? property.default : void 0
2296
- ])
2297
- );
2298
- }
2299
- function valueAt(value, path) {
2300
- let current = value;
2301
- for (const key of path) {
2302
- if (current === null || typeof current !== "object" || Array.isArray(current)) {
2303
- return void 0;
2304
- }
2305
- current = current[key];
2306
- }
2307
- return current;
2308
- }
2309
- function removeAt(value, path) {
2310
- const [head, ...rest] = path;
2311
- if (head === void 0 || value === null || typeof value !== "object") return;
2312
- const record = value;
2313
- if (rest.length === 0) {
2314
- delete record[head];
2315
- return;
2316
- }
2317
- removeAt(record[head], rest);
2318
- const child = record[head];
2319
- if (child !== null && typeof child === "object" && Object.keys(child).length === 0) {
2320
- delete record[head];
2321
- }
2322
- }
2323
-
2324
- // cli/validation/ajv.ts
2325
- import Ajv from "ajv";
2326
- function createAjv(fileValues = "resolved") {
2327
- const ajv3 = new Ajv({
2328
- allErrors: true,
2329
- // Report all errors, not just the first one
2330
- verbose: true,
2331
- // Include schema and data in errors
2332
- // A game schema may write a keyword beside a `$ref` with no `type` of
2333
- // its own (§6), which strictTypes would log as a warning on every compile.
2334
- strictTypes: false
2335
- });
2336
- ajv3.addKeyword({ keyword: "tsType", schemaType: "string" });
2337
- ajv3.addKeyword({
2338
- keyword: "blob",
2339
- type: "string",
2340
- metaSchema: {
2341
- type: "object",
2342
- properties: {
2343
- accept: { type: "array", items: { type: "string", pattern: "^[^/]+/[^/]+$" } },
2344
- maxBytes: { type: "integer", minimum: 1 }
2345
- },
2346
- additionalProperties: false
2347
- },
2348
- validate: (_spec, data) => fileValues === "resolved" ? data.startsWith("blob:") : isFileSettingValue(data),
2349
- errors: false
2350
- });
2351
- return ajv3;
2352
- }
2353
- function isFileSettingValue(value) {
2354
- return value === "" || /^(asset|shared|blob):./.test(value);
2355
- }
2356
-
2357
- // cli/validation/findings.ts
2358
- var MANIFEST_FILE = "seriousgaming.sdk.json";
2359
- function bundleFileOf(type, identifier) {
2360
- if (type === "package" || type === "game") return MANIFEST_FILE;
2361
- const meta = RESOURCE_METADATA.find((candidate) => candidate.type === type);
2362
- if (!meta) return void 0;
2363
- return meta.slot ? `${meta.slot}/${meta.bundleFile}` : `${meta.pluralDir}/${identifier}/${meta.bundleFile}`;
2364
- }
2365
- function pointerToken(segment) {
2366
- return String(segment).replace(/~/g, "~0").replace(/\//g, "~1");
2367
- }
2368
- function pointerOf(...segments) {
2369
- return segments.map((segment) => `/${pointerToken(segment)}`).join("");
2370
- }
2371
- function closestMatch(name, candidates) {
2372
- const target = name.toLowerCase();
2373
- let best;
2374
- let bestDistance = Infinity;
2375
- for (const candidate of candidates) {
2376
- const distance = editDistance(target, candidate.toLowerCase());
2377
- if (distance < bestDistance) {
2378
- best = candidate;
2379
- bestDistance = distance;
2380
- }
2381
- }
2382
- if (best === void 0) return void 0;
2383
- const allowed = Math.max(1, Math.floor(Math.max(name.length, best.length) / 3));
2384
- return bestDistance <= allowed ? best : void 0;
2385
- }
2386
- function didYouMean(name, candidates) {
2387
- const match2 = closestMatch(name, candidates);
2388
- return match2 === void 0 ? void 0 : `Did you mean '${match2}'?`;
2389
- }
2390
- function editDistance(a, b) {
2391
- let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
2392
- for (let i = 1; i <= a.length; i++) {
2393
- const current = [i];
2394
- for (let j = 1; j <= b.length; j++) {
2395
- const cost = a[i - 1] === b[j - 1] ? 0 : 1;
2396
- current[j] = Math.min(
2397
- (previous[j] ?? 0) + 1,
2398
- (current[j - 1] ?? 0) + 1,
2399
- (previous[j - 1] ?? 0) + cost
2400
- );
2401
- }
2402
- previous = current;
2403
- }
2404
- return previous[b.length] ?? 0;
2405
- }
2406
- function splitHint(text) {
2407
- const match2 = /^(.+?[.:])\s+(\S[\s\S]*)$/.exec(text);
2408
- if (!match2 || match2[1] === void 0 || match2[2] === void 0) return { message: text };
2409
- return { message: match2[1], hint: match2[2] };
2410
- }
2411
-
2412
- // cli/validation/schema-validation.ts
2413
- var schema = { ...schema_default };
2414
- delete schema.$schema;
2415
- var ajv = createAjv();
2416
- var settingsAjv = createAjv("reference");
2417
- ajv.addSchema(schema, "schema.json");
2418
- var validators = {
2419
- sdkCapability: ajv.compile({ $ref: "schema.json#/$defs/SDKCapability" }),
2420
- sdkSettings: ajv.compile({ $ref: "schema.json#/$defs/SDKSettings" }),
2421
- sdkEngine: ajv.compile({ $ref: "schema.json#/$defs/SDKEngine" }),
2422
- sdkUserInterface: ajv.compile({
2423
- $ref: "schema.json#/$defs/SDKUserInterface"
2424
- }),
2425
- packageManifest: ajv.compile({ $ref: "schema.json#/$defs/PackageManifest" }),
2426
- sdkSetup: ajv.compile({ $ref: "schema.json#/$defs/SDKSetup" }),
2427
- sdkScenarioEditor: ajv.compile({ $ref: "schema.json#/$defs/SDKScenarioEditor" }),
2428
- sdkSessionUserInterface: ajv.compile({
2429
- $ref: "schema.json#/$defs/SDKSessionUserInterface"
2430
- }),
2431
- sdkWaitingRoomUserInterface: ajv.compile({
2432
- $ref: "schema.json#/$defs/SDKWaitingRoomUserInterface"
2433
- }),
2434
- sdkPresentation: ajv.compile({
2435
- $ref: "schema.json#/$defs/SDKPresentation"
2436
- }),
2437
- sdkTickController: ajv.compile({
2438
- $ref: "schema.json#/$defs/SDKTickController"
2439
- }),
2440
- sdkScenario: ajv.compile({
2441
- $ref: "schema.json#/$defs/SDKScenario"
2442
- }),
2443
- sdkFacilitatorGuide: ajv.compile({
2444
- $ref: "schema.json#/$defs/SDKFacilitatorGuide"
2445
- }),
2446
- sdkHook: ajv.compile({
2447
- $ref: "schema.json#/$defs/SDKHook"
2448
- }),
2449
- sdkValidator: ajv.compile({
2450
- $ref: "schema.json#/$defs/SDKValidator"
2451
- }),
2452
- sdkEndpoint: ajv.compile({
2453
- $ref: "schema.json#/$defs/SDKEndpoint"
2454
- })
2455
- };
2456
- function hasAllowedValues(params) {
2457
- return typeof params === "object" && params !== null && "allowedValues" in params;
2458
- }
2459
- function hasPattern(params) {
2460
- return typeof params === "object" && params !== null && "pattern" in params;
2461
- }
2462
- function schemaDescription(err) {
2463
- const parent = err.parentSchema;
2464
- if (typeof parent !== "object" || parent === null || !("description" in parent)) {
2465
- return void 0;
2466
- }
2467
- const description = parent.description;
2468
- return typeof description === "string" ? description : void 0;
2469
- }
2470
- function hasAdditionalProperty(params) {
2471
- return typeof params === "object" && params !== null && "additionalProperty" in params;
2472
- }
2473
- function hasMissingProperty(params) {
2474
- return typeof params === "object" && params !== null && "missingProperty" in params;
2475
- }
2476
- function formatErrors(errors) {
2477
- if (!errors || errors.length === 0) {
2478
- return "Unknown validation error";
2479
- }
2480
- return errors.map((err) => {
2481
- const path = err.instancePath || "data";
2482
- const message = err.message || "invalid";
2483
- if (err.keyword === "enum" && hasAllowedValues(err.params)) {
2484
- const allowedValues = err.params.allowedValues.join(", ");
2485
- return `${path} ${message} (allowed values: ${allowedValues})`;
2486
- }
2487
- if (err.keyword === "pattern" && hasPattern(err.params)) {
2488
- const guidance = schemaDescription(err) ?? `must match pattern: ${err.params.pattern}`;
2489
- return `${path} ${message} (${guidance})`;
2490
- }
2491
- if (err.keyword === "additionalProperties" && hasAdditionalProperty(err.params)) {
2492
- return `${path} ${message} (unexpected property: "${err.params.additionalProperty}")`;
2493
- }
2494
- return `${path} ${message}`;
2495
- }).join("\n");
2496
- }
2497
- function declaredProperties(err) {
2498
- const parent = err.parentSchema;
2499
- if (typeof parent !== "object" || parent === null || !("properties" in parent)) return [];
2500
- const properties = parent.properties;
2501
- return typeof properties === "object" && properties !== null ? Object.keys(properties) : [];
2502
- }
2503
- function schemaFinding(err) {
2504
- const message = err.message || "invalid";
2505
- if (err.keyword === "additionalProperties" && hasAdditionalProperty(err.params)) {
2506
- const property = err.params.additionalProperty;
2507
- const hint = didYouMean(property, declaredProperties(err));
2508
- return {
2509
- code: "SCHEMA_INVALID",
2510
- message: `Unexpected property "${property}"`,
2511
- pointer: `${err.instancePath}${pointerOf(property)}`,
2512
- ...hint === void 0 ? {} : { hint }
2513
- };
2514
- }
2515
- if (err.keyword === "enum" && hasAllowedValues(err.params)) {
2516
- return {
2517
- code: "SCHEMA_INVALID",
2518
- message: `${message} (allowed values: ${err.params.allowedValues.join(", ")})`,
2519
- pointer: err.instancePath
2520
- };
2521
- }
2522
- if (err.keyword === "pattern" && hasPattern(err.params)) {
2523
- return {
2524
- code: "SCHEMA_INVALID",
2525
- message,
2526
- pointer: err.instancePath,
2527
- hint: schemaDescription(err) ?? `It must match the pattern ${err.params.pattern}.`
2528
- };
2529
- }
2530
- return { code: "SCHEMA_INVALID", message, pointer: err.instancePath };
2531
- }
2532
- function schemaFindings(errors) {
2533
- return (errors ?? []).map(schemaFinding);
2534
- }
2535
- function formatResourceErrors(errors, resourceFileName, expectedShape) {
2536
- if (!errors || errors.length === 0) {
2537
- return "Unknown validation error";
2538
- }
2539
- const missingProps = errors.filter(
2540
- (err) => err.keyword === "required" && err.instancePath === "" && hasMissingProperty(err.params)
2541
- ).map((err) => err.params.missingProperty);
2542
- if (missingProps.length > 0) {
2543
- const propList = missingProps.map((p) => `"${p}"`).join(", ");
2544
- return [
2545
- `Missing required ${missingProps.length === 1 ? "property" : "properties"}: ${propList}`,
2546
- "",
2547
- `Expected ${resourceFileName} structure:`,
2548
- expectedShape
2549
- ].join("\n");
2550
- }
2551
- return formatErrors(errors);
2552
- }
2553
- function makeValidator(validatorFn, resourceFile, expectedShape) {
2554
- return (data) => {
2555
- if (validatorFn(data)) {
2556
- return { valid: true };
2557
- }
2558
- const errors = resourceFile !== void 0 && expectedShape !== void 0 ? formatResourceErrors(validatorFn.errors, resourceFile, expectedShape) : formatErrors(validatorFn.errors);
2559
- const findings = schemaFindings(validatorFn.errors).map(
2560
- (finding) => resourceFile !== void 0 && expectedShape !== void 0 && finding.pointer === "" && finding.message.startsWith("must have required property") ? { ...finding, hint: `Expected ${resourceFile} structure:
2561
- ${expectedShape}` } : finding
2562
- );
2563
- return { valid: false, errors, findings };
2564
- };
2565
- }
2566
- var validateSDKCapability = makeValidator(
2567
- validators.sdkCapability,
2568
- "capability.sdk.json",
2569
- resourceExample("capability", "new")
2570
- );
2571
- var validateSDKSettings = makeValidator(
2572
- validators.sdkSettings,
2573
- "settings.sdk.json",
2574
- resourceExample("settings", "new")
2575
- );
2576
- var validateSDKEngine = makeValidator(
2577
- validators.sdkEngine,
2578
- "engine.sdk.json",
2579
- resourceExample("engine", "new")
2580
- );
2581
- var validateSDKUserInterface = makeValidator(
2582
- validators.sdkUserInterface,
2583
- "ui.sdk.json",
2584
- resourceExample("ui", "new")
2585
- );
2586
- var validatePackageManifest = makeValidator(
2587
- validators.packageManifest,
2588
- "seriousgaming.sdk.json",
2589
- resourceExample("package", "update")
2590
- );
2591
- var validateSDKTickController = makeValidator(
2592
- validators.sdkTickController,
2593
- "tick_controller.sdk.json",
2594
- resourceExample("tick_controller", "new")
2595
- );
2596
- var validateSDKScenario = makeValidator(
2597
- validators.sdkScenario,
2598
- "scenario.sdk.json",
2599
- resourceExample("scenario", "new")
2600
- );
2601
- var validateSDKFacilitatorGuide = makeValidator(
2602
- validators.sdkFacilitatorGuide,
2603
- "guide.sdk.json",
2604
- resourceExample("guide", "new")
2605
- );
2606
- var validateSDKSetup = makeValidator(
2607
- validators.sdkSetup,
2608
- "setup.sdk.json",
2609
- resourceExample("setup", "new")
2610
- );
2611
- var validateSDKScenarioEditor = makeValidator(
2612
- validators.sdkScenarioEditor,
2613
- "scenario_editor.sdk.json",
2614
- resourceExample("scenario_editor", "new")
2615
- );
2616
- var validateSDKSessionUserInterface = makeValidator(
2617
- validators.sdkSessionUserInterface,
2618
- "session.sdk.json",
2619
- resourceExample("session", "new")
2620
- );
2621
- var validateSDKWaitingRoomUserInterface = makeValidator(
2622
- validators.sdkWaitingRoomUserInterface,
2623
- "waiting_room.sdk.json",
2624
- resourceExample("waiting_room", "new")
2625
- );
2626
- var validateSDKPresentation = makeValidator(
2627
- validators.sdkPresentation,
2628
- "presentation.sdk.json",
2629
- resourceExample("presentation", "new")
2630
- );
2631
- var validateSDKHook = makeValidator(
2632
- validators.sdkHook,
2633
- "hook.sdk.json",
2634
- resourceExample("hook", "new")
2635
- );
2636
- var validateSDKValidator = makeValidator(
2637
- validators.sdkValidator,
2638
- "validator.sdk.json",
2639
- resourceExample("validator", "new")
2640
- );
2641
- var validateSDKEndpoint = makeValidator(
2642
- validators.sdkEndpoint,
2643
- "endpoint.sdk.json",
2644
- resourceExample("endpoint", "new")
2645
- );
2646
- function settingsSchemas(config) {
2647
- return Object.fromEntries(
2648
- (config.settings ?? []).map((settings) => [
2649
- settings.definition.identifier,
2650
- settings.definition.settingsSchema
2651
- ])
2652
- );
2653
- }
2654
- function collectSettingsOverrideErrors(overrides, schemas) {
2655
- const errors = [];
2656
- for (const [identifier, value] of Object.entries(overrides)) {
2657
- const schema2 = schemas[identifier];
2658
- if (!schema2) {
2659
- const known = Object.keys(schemas);
2660
- errors.push(
2661
- `Unknown settings "${identifier}": ` + (known.length > 0 ? `expected one of ${known.join(", ")}` : "this package declares no settings")
2662
- );
2663
- continue;
2664
- }
2665
- if (!value || typeof value !== "object" || Array.isArray(value)) {
2666
- errors.push(`Settings "${identifier}": an override must be an object`);
2667
- continue;
2668
- }
2669
- const failures = validatePartialOverride(value, schema2);
2670
- if (failures) errors.push(`Settings "${identifier}": ${formatErrors(failures)}`);
2671
- for (const path of lockedPathsNamed(value, schema2)) {
2672
- errors.push(lockedSettingMessage(identifier, path));
2673
- }
2674
- }
2675
- return errors;
2676
- }
2677
- function collectSettingsOverrideFindings(overrides, schemas, base = "") {
2678
- const findings = [];
2679
- const known = Object.keys(schemas);
2680
- for (const [identifier, value] of Object.entries(overrides)) {
2681
- const at = `${base}${pointerOf(identifier)}`;
2682
- const schema2 = schemas[identifier];
2683
- if (!schema2) {
2684
- const hint = didYouMean(identifier, known) ?? (known.length > 0 ? `The package declares ${known.map((name) => `'${name}'`).join(", ")}.` : "This package declares no settings. Create one with `pnpm run sdk new settings`.");
2685
- findings.push({
2686
- code: "SETTINGS_UNKNOWN",
2687
- message: `Overrides settings "${identifier}", which the package does not declare`,
2688
- pointer: at,
2689
- hint
2690
- });
2691
- continue;
2692
- }
2693
- if (!value || typeof value !== "object" || Array.isArray(value)) {
2694
- findings.push({
2695
- code: "SETTINGS_INVALID",
2696
- message: `Settings "${identifier}": an override must be an object`,
2697
- pointer: at
2698
- });
2699
- continue;
2700
- }
2701
- for (const path of lockedPathsNamed(value, schema2)) {
2702
- findings.push({
2703
- code: "SETTINGS_LOCKED",
2704
- message: lockedSettingMessage(identifier, path),
2705
- pointer: `${at}${pointerOf(...path)}`,
2706
- hint: identifier === GAME_SETTINGS ? "Remove it. The game locks it with readOnly in gameSettingsConstraints in seriousgaming.sdk.json." : `Remove it. The game locks it with readOnly in settings/${identifier}/settings.sdk.json.`
2707
- });
2708
- }
2709
- for (const err of validatePartialOverride(value, schema2) ?? []) {
2710
- if (err.keyword === "additionalProperties" && hasAdditionalProperty(err.params)) {
2711
- const key = err.params.additionalProperty;
2712
- const hint = didYouMean(key, declaredProperties(err));
2713
- findings.push({
2714
- code: "SETTINGS_UNKNOWN_KEY",
2715
- message: `Overrides "${key}", which settings "${identifier}" does not declare`,
2716
- pointer: `${at}${err.instancePath}${pointerOf(key)}`,
2717
- ...hint === void 0 ? {} : { hint }
2718
- });
2719
- continue;
2720
- }
2721
- const finding = schemaFinding(err);
2722
- findings.push({
2723
- ...finding,
2724
- code: "SETTINGS_INVALID",
2725
- message: `Settings "${identifier}": ${finding.message}`,
2726
- pointer: `${at}${err.instancePath}`
2727
- });
2728
- }
2729
- }
2730
- return findings;
2731
- }
2732
- function validateSessionOverrides(configuration, schemas) {
2733
- if (!configuration || typeof configuration !== "object" || Array.isArray(configuration)) {
2734
- return { valid: false, errors: "Settings overrides must be an object" };
2735
- }
2736
- const errors = collectSettingsOverrideErrors(configuration, schemas);
2737
- const refusal = gameOverrideRefusal(configuration);
2738
- if (refusal !== null) errors.push(refusal);
2739
- return errors.length > 0 ? { valid: false, errors: errors.join("\n") } : { valid: true };
2740
- }
2741
- function validateSettingsOverrides(overrides, schemas, sourceLabel) {
2742
- const errors = collectSettingsOverrideErrors(overrides, schemas);
2743
- return errors.length > 0 ? { valid: false, errors: `${sourceLabel}:
2744
- ${errors.join("\n")}` } : { valid: true };
2745
- }
2746
- function validatePartialOverride(override, settingsSchema) {
2747
- let validator;
2748
- try {
2749
- validator = settingsAjv.compile(closed(withoutRequired(settingsSchema)));
2750
- } catch (error) {
2751
- return [
2752
- {
2753
- keyword: "compile",
2754
- instancePath: "",
2755
- schemaPath: "#",
2756
- params: {},
2757
- message: `cannot be checked: its settings schema does not compile (${error instanceof Error ? error.message : String(error)})`
2758
- }
2759
- ];
2760
- }
2761
- return validator(override) ? null : validator.errors ?? [];
2762
- }
2763
- var SCHEMA_MAP_KEYWORDS = ["properties", "patternProperties", "definitions", "$defs"];
2764
- var SUBSCHEMA_KEYWORDS = ["additionalProperties", "then", "else"];
2765
- var SCHEMA_LIST_KEYWORDS = ["allOf", "anyOf", "oneOf"];
2766
- function withoutRequired(schema2) {
2767
- const partial = partially(schema2);
2768
- if (typeof schema2 !== "object" || typeof partial !== "object") return partial;
2769
- for (const keyword of DEFINITION_KEYWORDS) {
2770
- const defs = schema2[keyword];
2771
- const copied = partial[keyword];
2772
- if (!defs || typeof defs !== "object" || !copied || typeof copied !== "object") continue;
2773
- for (const [name, def] of Object.entries(defs)) {
2774
- copied[`${WHOLE}${name}`] = wholeRefs(def);
2775
- }
2776
- }
2777
- return partial;
2778
- }
2779
- var DEFINITION_KEYWORDS = ["$defs", "definitions"];
2780
- var WHOLE = "__whole__";
2781
- function partially(schema2) {
2782
- if (typeof schema2 !== "object" || schema2 === null) return schema2;
2783
- const { required: _required, ...rest } = schema2;
2784
- const copy = { ...rest };
2785
- for (const keyword of SCHEMA_MAP_KEYWORDS) {
2786
- const map = rest[keyword];
2787
- if (map && typeof map === "object") {
2788
- copy[keyword] = Object.fromEntries(
2789
- Object.entries(map).map(([key, value]) => [key, partially(value)])
2790
- );
2791
- }
2792
- }
2793
- for (const keyword of SUBSCHEMA_KEYWORDS) {
2794
- const sub = rest[keyword];
2795
- if (sub !== void 0) copy[keyword] = partially(sub);
2796
- }
2797
- for (const keyword of SCHEMA_LIST_KEYWORDS) {
2798
- const list = rest[keyword];
2799
- if (Array.isArray(list)) copy[keyword] = list.map(partially);
2800
- }
2801
- if (rest.items !== void 0) copy.items = wholeRefs(rest.items);
2802
- return copy;
2803
- }
2804
- var DATA_KEYWORDS = /* @__PURE__ */ new Set(["default", "const", "enum", "examples"]);
2805
- function wholeRefs(value) {
2806
- if (Array.isArray(value)) return value.map(wholeRefs);
2807
- if (value === null || typeof value !== "object") return value;
2808
- return Object.fromEntries(
2809
- Object.entries(value).map(([key, child]) => [
2810
- key,
2811
- key === "$ref" && typeof child === "string" ? child.replace(/^#\/(\$defs|definitions)\/(?=[^/]+$)/, `#/$1/${WHOLE}`) : DATA_KEYWORDS.has(key) ? child : wholeRefs(child)
2812
- ])
2813
- );
2814
- }
2815
- var COMBINATOR_KEYWORDS = ["allOf", "anyOf", "oneOf", "if", "not", "$ref"];
2816
- function closed(schema2) {
2817
- if (typeof schema2 !== "object" || schema2 === null) return schema2;
2818
- const copy = { ...schema2 };
2819
- for (const keyword of SCHEMA_MAP_KEYWORDS) {
2820
- const map = schema2[keyword];
2821
- if (map && typeof map === "object") {
2822
- copy[keyword] = Object.fromEntries(
2823
- Object.entries(map).map(([key, value]) => [key, closed(value)])
2824
- );
2825
- }
2826
- }
2827
- if (typeof schema2.additionalProperties === "object") {
2828
- copy.additionalProperties = closed(schema2.additionalProperties);
2829
- }
2830
- if (Array.isArray(schema2.items)) copy.items = schema2.items.map(closed);
2831
- else if (schema2.items !== void 0) copy.items = closed(schema2.items);
2832
- if (isPlainOpen(schema2)) copy.additionalProperties = false;
2833
- return copy;
2834
- }
2835
- function isPlainOpen(schema2) {
2836
- return schema2.properties !== void 0 && schema2.additionalProperties === void 0 && schema2.patternProperties === void 0 && !COMBINATOR_KEYWORDS.some((keyword) => keyword in schema2);
2837
- }
2838
- function openSettingsObjects(schema2, at = "") {
2839
- if (typeof schema2 !== "object" || schema2 === null) return [];
2840
- const found = isPlainOpen(schema2) ? [at] : [];
2841
- for (const keyword of SCHEMA_MAP_KEYWORDS) {
2842
- const map = schema2[keyword];
2843
- if (!map || typeof map !== "object") continue;
2844
- for (const [key, value] of Object.entries(map)) {
2845
- found.push(...openSettingsObjects(value, `${at}/${keyword}/${key}`));
2846
- }
2847
- }
2848
- if (typeof schema2.additionalProperties === "object") {
2849
- found.push(
2850
- ...openSettingsObjects(schema2.additionalProperties, `${at}/additionalProperties`)
2851
- );
2852
- }
2853
- if (Array.isArray(schema2.items)) {
2854
- schema2.items.forEach(
2855
- (item, index) => found.push(...openSettingsObjects(item, `${at}/items/${index}`))
2856
- );
2857
- } else if (schema2.items !== void 0) {
2858
- found.push(...openSettingsObjects(schema2.items, `${at}/items`));
2859
- }
2860
- return found;
2861
- }
2862
-
2863
- // cli/utils/errors.ts
2864
- function errorMessage(error, fallback = "Unknown error") {
2865
- return isErrorLike(error) ? error.message : fallback;
2866
- }
2867
- function isErrorLike(error) {
2868
- return typeof error === "object" && error !== null && "message" in error && typeof error.message === "string";
2869
- }
2870
- var DeniedError = class extends Error {
2871
- constructor(message) {
2872
- super(message);
2873
- this.name = "DeniedError";
2874
- }
2875
- };
2876
-
2877
- // cli/bundling/node-builtins.ts
2878
- import { builtinModules } from "node:module";
2879
- var LOGIC_NODE_BUILTIN = "LOGIC_NODE_BUILTIN";
2880
- var BUILTINS = new Set(builtinModules);
2881
- function isNodeBuiltin(specifier) {
2882
- if (specifier.startsWith("node:")) return true;
2883
- return BUILTINS.has(specifier) || BUILTINS.has(specifier.split("/")[0] ?? specifier);
2884
- }
2885
- function nodeBuiltinMessage(where, specifier) {
2886
- return `${LOGIC_NODE_BUILTIN}: ${where || "game logic"} imports '${specifier}', a Node built-in. Game logic runs on the ECMAScript intrinsics alone, so a built-in that loads in development is absent in production. Reach external services through the callbacks argument, and bytes through the SDK helpers encodeUtf8 and decodeUtf8.`;
2887
- }
2888
- function escape(name) {
2889
- return name.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
2890
- }
2891
- var BUILTIN_FILTER = new RegExp(
2892
- `^(?:node:|(?:${[...BUILTINS].filter((name) => !name.includes("/")).map(escape).join("|")})(?:/|$))`
2893
- );
2894
- function refuseNodeBuiltins() {
2895
- return {
2896
- name: "refuse-node-builtins",
2897
- setup(build) {
2898
- build.onResolve({ filter: BUILTIN_FILTER }, (args) => {
2899
- if (args.kind === "entry-point" || !isNodeBuiltin(args.path)) return void 0;
2900
- return {
2901
- errors: [
2902
- {
2903
- text: nodeBuiltinMessage(args.importer, args.path),
2904
- detail: { specifier: args.path, importer: args.importer }
2905
- }
2906
- ]
2907
- };
2908
- });
2909
- }
2910
- };
2911
- }
2912
- function nodeBuiltinRefusals(errors) {
2913
- return errors.flatMap((error) => {
2914
- const detail = error.detail;
2915
- if (!detail?.specifier) return [];
2916
- const where = error.location ? `${error.location.file}:${error.location.line}:${error.location.column + 1}` : detail.importer ?? "";
2917
- return [nodeBuiltinMessage(where, detail.specifier)];
2918
- });
2919
- }
2920
-
2921
- // cli/bundling/transpiler.ts
2922
- import { isAbsolute, relative, resolve, sep } from "path";
2923
- import { build as esbuild } from "esbuild";
2924
-
2925
- // cli/utils/real-path.ts
2926
- import { realpathSync } from "node:fs";
2927
- function realPath(path) {
2928
- try {
2929
- return realpathSync(path);
2930
- } catch {
2931
- return path;
2932
- }
2933
- }
2934
-
2935
- // cli/bundling/transpiler.ts
2936
- var CONSOLE_SHIM = `if (typeof console === "undefined") {
2937
- globalThis.console = ["log", "info", "warn", "error", "debug"].reduce(function (c, level) {
2938
- c[level] = function () {
2939
- if (typeof globalThis.__logBridge === "function") {
2940
- globalThis.__logBridge(level, Array.prototype.slice.call(arguments));
2941
- }
2942
- };
2943
- return c;
2944
- }, {});
2945
- }
2946
- `;
2947
- async function Transpile({
2948
- entrypoint,
2949
- sourcemap = false,
2950
- packageRoot
2951
- }) {
2952
- try {
2953
- const result = await esbuild({
2954
- entryPoints: [entrypoint],
2955
- bundle: true,
2956
- minify: false,
2957
- treeShaking: true,
2958
- write: false,
2959
- format: "cjs",
2960
- platform: "node",
2961
- banner: { js: CONSOLE_SHIM },
2962
- // `platform: 'node'` would leave a built-in to Node's `require`,
2963
- // which the production runtime does not have (§3.2), so one is
2964
- // refused here.
2965
- plugins: [refuseNodeBuiltins()],
2966
- logLevel: "silent",
2967
- // An inline map with no sources content: the stack is mapped back
2968
- // to a file the author already has open. The outfile is never
2969
- // written; it anchors the map's source paths beside the entrypoint.
2970
- ...sourcemap ? {
2971
- sourcemap: "inline",
2972
- sourcesContent: false,
2973
- outfile: `${entrypoint}.bundle.js`
2974
- } : {}
2975
- });
2976
- return result.outputFiles[0].text;
2977
- } catch (error) {
2978
- const errors = error.errors ?? [];
2979
- const root = packageRoot ?? process.cwd();
2980
- const refusals = nodeBuiltinRefusals(errors);
2981
- if (refusals.length > 0) {
2982
- throw new CliError("LOGIC_NODE_BUILTIN", refusals.join("\n"), {
2983
- cause: error,
2984
- diagnostics: errors.filter((entry) => isBuiltinRefusal(entry)).map((entry) => bundleDiagnostic("LOGIC_NODE_BUILTIN", entry, root))
2985
- });
2986
- }
2987
- if (errors.length > 0) {
2988
- throw new CliError("LOGIC_BUNDLE_FAILED", errorMessage(error), {
2989
- cause: error,
2990
- diagnostics: errors.map(
2991
- (entry) => bundleDiagnostic("LOGIC_BUNDLE_FAILED", entry, root)
2992
- )
2993
- });
2994
- }
2995
- throw error;
2996
- }
2997
- }
2998
- function isBuiltinRefusal(message) {
2999
- return Boolean(message.detail?.specifier);
3000
- }
3001
- function bundleDiagnostic(code, message, packageRoot) {
3002
- const location = message.location;
3003
- const specifier = message.detail?.specifier;
3004
- return {
3005
- severity: "error",
3006
- code,
3007
- message: code === "LOGIC_NODE_BUILTIN" && specifier !== void 0 ? `Imports '${specifier}', a Node built-in, which game logic cannot use in production` : message.text,
3008
- ...location ? {
3009
- file: packageRelativePath(location.file, packageRoot),
3010
- line: location.line,
3011
- column: location.column + 1
3012
- } : {},
3013
- ...code === "LOGIC_NODE_BUILTIN" ? {
3014
- hint: "Reach external services through the callbacks argument, and bytes through encodeUtf8 and decodeUtf8."
3015
- } : {}
3016
- };
3017
- }
3018
- function packageRelativePath(file, packageRoot) {
3019
- const absolute = isAbsolute(file) ? file : resolve(process.cwd(), file);
3020
- return relative(realPath(packageRoot), realPath(absolute)).split(sep).join("/");
3021
- }
3022
-
3023
- // cli/runtime/manifest-version.ts
3024
- var MANIFEST_VERSION = 3;
3025
- var SPEC_REVISION = "1.6";
3026
- var SUPPORTED_FEATURES = [
3027
- // A validator's `Scenario` gate (§15.8).
3028
- "scenario-validation",
3029
- // The presentation as a host overlay a session surface may open (§6.4).
3030
- "presentation-overlay",
3031
- // File reads in a validator's `Scenario` gate (§15.8).
3032
- "scenario-files"
3033
- ];
3034
- function unsupportedFeatures(manifest) {
3035
- return (manifest.requires ?? []).filter((feature) => !SUPPORTED_FEATURES.includes(feature));
3036
- }
3037
- var SUPPORTED_SERVICES = [
3038
- "generateText",
3039
- "extractText",
3040
- "generateSpeech",
3041
- "writeBlob"
3042
- ];
3043
- function unsupportedServices(resources, supported = SUPPORTED_SERVICES) {
3044
- const missing = /* @__PURE__ */ new Map();
3045
- for (const resource of resources) {
3046
- for (const service of resource.definition.uses ?? []) {
3047
- if (supported.includes(service)) continue;
3048
- const declaring = missing.get(service) ?? [];
3049
- if (!declaring.includes(resource.definition.identifier)) {
3050
- declaring.push(resource.definition.identifier);
3051
- }
3052
- missing.set(service, declaring);
3053
- }
3054
- }
3055
- return [...missing].map(([service, declaring]) => ({ service, resources: declaring }));
3056
- }
3057
-
3058
- // cli/discovery/config.ts
3059
- import { existsSync as existsSync2, readFileSync } from "fs";
3060
- import { readFile, readdir } from "fs/promises";
3061
- import { basename, dirname, join, relative as relative2, sep as sep2 } from "path";
3062
-
3063
- // cli/bundling/logic-exports.ts
3064
- import { existsSync } from "fs";
3065
- async function readLogicExports(filePath, names, packageRoot) {
3066
- if (!existsSync(filePath)) {
3067
- return { exists: false, present: /* @__PURE__ */ new Set() };
3068
- }
3069
- if (names.length === 0) {
3070
- return { exists: true, present: /* @__PURE__ */ new Set() };
3071
- }
3072
- try {
3073
- const bundledCode = await Transpile({
3074
- entrypoint: filePath,
3075
- ...packageRoot === void 0 ? {} : { packageRoot }
3076
- });
3077
- const present = /* @__PURE__ */ new Set();
3078
- for (const name of names) {
3079
- const patterns = [
3080
- // esbuild's __export(): __export(x, { Name: () => Name })
3081
- new RegExp(`${name}:\\s*\\(\\)\\s*=>`),
3082
- new RegExp(`exports\\.${name}\\s*=`),
3083
- new RegExp(`exports\\["${name}"\\]\\s*=`),
3084
- new RegExp(`exports\\['${name}'\\]\\s*=`)
3085
- ];
3086
- if (patterns.some((pattern) => pattern.test(bundledCode))) {
3087
- present.add(name);
3088
- }
3089
- }
3090
- return { exists: true, present };
3091
- } catch (error) {
3092
- return {
3093
- exists: true,
3094
- present: /* @__PURE__ */ new Set(),
3095
- failure: error instanceof Error ? error.message : String(error),
3096
- ...error instanceof CliError && error.diagnostics.length > 0 ? { failureDiagnostics: error.diagnostics } : {}
3097
- };
3098
- }
3099
- }
3100
-
3101
- // cli/validation/game-constraints.ts
3102
- var ajv2 = createAjv();
3103
- function gameConstraintFindings(manifest) {
3104
- const findings = [];
3105
- const sdk = schema_default.$defs.GameSettings;
3106
- for (const [path, constraint] of gameSettingConstraints(manifest.gameSettingsConstraints)) {
3107
- const leaf = leafAt(sdk, path);
3108
- const at = `gameSettingsConstraints.${path}`;
3109
- const refuse = (message, keyword) => {
3110
- findings.push({
3111
- code: "GAME_CONSTRAINT_INVALID",
3112
- message,
3113
- file: MANIFEST_FILE,
3114
- pointer: `/gameSettingsConstraints/${path.split(".").join("/")}/${keyword}`,
3115
- hint: "A constraint may only narrow the SDK's own schema for the `game` settings."
3116
- });
3117
- };
3118
- const { minimum, maximum } = constraint;
3119
- const numeric = typesOf(leaf).some((type) => type === "integer" || type === "number");
3120
- if (!numeric) {
3121
- if (minimum !== void 0)
3122
- refuse(`${at} sets a minimum, but game.${path} is not a number`, "minimum");
3123
- if (maximum !== void 0)
3124
- refuse(`${at} sets a maximum, but game.${path} is not a number`, "maximum");
3125
- } else {
3126
- if (minimum !== void 0 && typeof leaf.minimum === "number" && minimum < leaf.minimum) {
3127
- refuse(
3128
- `${at}.minimum is ${minimum}, below the SDK's own minimum of ${leaf.minimum}`,
3129
- "minimum"
3130
- );
3131
- }
3132
- if (maximum !== void 0 && typeof leaf.maximum === "number" && maximum > leaf.maximum) {
3133
- refuse(
3134
- `${at}.maximum is ${maximum}, above the SDK's own maximum of ${leaf.maximum}`,
3135
- "maximum"
3136
- );
3137
- }
3138
- if (minimum !== void 0 && maximum !== void 0 && minimum > maximum) {
3139
- refuse(`${at}.minimum is above its maximum, so no value meets both`, "minimum");
3140
- }
3141
- }
3142
- if (constraint.enum !== void 0) {
3143
- const accepts = ajv2.compile(leaf);
3144
- for (const value of constraint.enum) {
3145
- if (!accepts(value)) {
3146
- refuse(
3147
- `${at}.enum lists ${JSON.stringify(value)}, which game.${path} does not accept`,
3148
- "enum"
3149
- );
3150
- }
3151
- }
3152
- }
3153
- }
3154
- if (findings.length > 0) return findings;
3155
- const merged = gameSettingsResource(manifest).definition.settingsSchema;
3156
- const validate = ajv2.compile(merged);
3157
- if (validate(gameSettingsDefaults(manifest))) return findings;
3158
- for (const error of validate.errors ?? []) {
3159
- const path = error.instancePath.split("/").filter(Boolean).join(".");
3160
- findings.push({
3161
- code: "GAME_CONSTRAINT_VIOLATED",
3162
- message: `The game's own ${path} ${error.message ?? "is invalid"}, by its gameSettingsConstraints`,
3163
- file: MANIFEST_FILE,
3164
- pointer: error.instancePath,
3165
- hint: error.data === null ? `Set ${path} in seriousgaming.sdk.json: a bound rules out leaving it unset.` : `Change ${path} in seriousgaming.sdk.json, or the constraint on it.`
3166
- });
3167
- }
3168
- return findings;
3169
- }
3170
- function leafAt(schema2, path) {
3171
- let current = schema2;
3172
- for (const key of path.split(".")) {
3173
- const next = current.properties?.[key];
3174
- if (typeof next !== "object") return {};
3175
- current = next;
3176
- }
3177
- return current;
3178
- }
3179
- function typesOf(schema2) {
3180
- if (schema2.type === void 0) return [];
3181
- return Array.isArray(schema2.type) ? schema2.type : [schema2.type];
3182
- }
3183
-
3184
- // cli/discovery/manifest-paths.ts
3185
- import { posix } from "path";
3186
- function toPosixPath(value) {
3187
- return value.replace(/\\/g, "/");
3188
- }
3189
- function resolveManifestRootDirectory(resourcePath, declaredRootDirectory) {
3190
- return posix.join(posix.dirname(toPosixPath(resourcePath)), toPosixPath(declaredRootDirectory));
3191
- }
3192
-
3193
- // cli/discovery/removed-fields.ts
3194
- var REMOVED_CONFIGURATION_SCHEMA = "`configurationSchema` has been removed. Move these properties into a settings resource (`pnpm run sdk new settings`), and list it in this resource's `settings`.";
3195
- var REMOVED_GAME_CONFIGURATION = "The game-level `configuration` block has been removed: edit the settings resource's defaults instead, or override them in a scenario's `settings`. Delete the block.";
3196
- var RENAMED_SCENARIO_CONFIGURATION = "A scenario's `configuration` has been renamed to `settings`. Rename the field; what it holds, keyed by settings identifier, stays as it is.";
3197
- var REMOVED_UI_USES = "`uses` has been removed from user interfaces: a user interface reaches a service through an endpoint. Declare the API in the endpoint's `uses`, list the endpoint in this interface's `endpoints`, and delete the field.";
3198
- var REMOVED_DEMO = "Demo mode has been removed, so `demo` is read by nothing. To show a game to a room, start a walkthrough run, which plays it without touching the session. Delete the block.";
3199
- var REMOVED_CONFIGURATION_SURFACES = "`configurationSurfaces` has been removed: the two surfaces are slots of their own. Move the UI wired into 'quick-config' to `setup/` (bundle `setup/setup.sdk.json`) and the one wired into 'scenario-builder' to `scenario_editor/` (bundle `scenario_editor/scenario_editor.sdk.json`), then delete the key.";
3200
- var RENAMED_MANIFEST_TICKS = "`ticks` has been renamed to `maxTicks`. Rename the field; its value, the number of ticks the game plays, stays as it is.";
3201
- function movedScenarioGameField(key, value) {
3202
- const moved = key === "ticks" ? { maxTicks: value } : { [key]: value };
3203
- return `A scenario's \`${key}\` has moved to \`settings.game\`: the game-level settings are the built-in \`game\` settings resource, overridden like any other. Replace it with "settings": { "game": ${JSON.stringify(moved)} }` + (key === "ticks" ? ", where `ticks` is called `maxTicks`." : ".");
3204
- }
3205
- var UPGRADING_HINT = "If this package was written for an earlier SDK, `seriousgaming-sdk docs view guides/upgrading.md` says what changed.";
3206
- var UI_BUNDLES = RESOURCE_METADATA.filter((meta) => meta.kind === "ui").map((meta) => meta.type);
3207
- var NAMELESS_UI_BUNDLES = RESOURCE_METADATA.filter(isNamelessInterface).map((meta) => meta.type);
3208
- var isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
3209
- function container(key, why) {
3210
- return {
3211
- where: "manifest",
3212
- path: [key],
3213
- since: "0.1.0",
3214
- message: `\`${key}\` has been removed. A package is a game, so ${why}.`
3215
- };
3216
- }
3217
- function resourceList(key) {
3218
- return {
3219
- where: "manifest",
3220
- path: [key],
3221
- since: "0.1.0",
3222
- message: `The resource lists have been removed (${key}).`,
3223
- hint: "A package declares whatever is on disk under the conventional directories, so delete the lists; the directories they named are the declaration."
3224
- };
3225
- }
3226
- function pluralSlotDirectory(directory, slot, label) {
3227
- return {
3228
- where: "package",
3229
- path: [directory],
3230
- since: "0.1.0",
3231
- message: `A game holds one ${label}, so it lives in a fixed slot rather than a named directory (${directory}/<name>/ -> ${slot}/).`,
3232
- hint: `Move it to \`${slot}/\`, with its logic or ui files directly inside, and delete \`${directory}/\`.`
3233
- };
3234
- }
3235
- function gameReference(key, why) {
3236
- return {
3237
- where: "manifest",
3238
- path: [key],
3239
- since: "0.1.0",
3240
- message: `\`${key}\` has been removed. A game wires whatever its package declares, so ${why}. Delete the field; configuration lives in settings resources, which a scenario overrides by identifier.`
3241
- };
3242
- }
3243
- var MOVED_REFERENCE_FIELDS = [
3244
- [
3245
- "optional",
3246
- "a game wires whatever its package declares, and the runtime seeds every declared capability from its schema defaults, so a declared read is always satisfied. Delete the field"
3247
- ],
3248
- [
3249
- "crossTeam",
3250
- "it has moved to the surface's own `crossTeamReads` array, which lists the capabilities every team's value of arrives for"
3251
- ],
3252
- [
3253
- "requiresDownstreamWrite",
3254
- "it meant an engine later in the order had to write the capability, and a game holds one engine. Delete the field"
3255
- ]
3256
- ];
3257
- function objectReference(key) {
3258
- return {
3259
- where: "every bundle",
3260
- path: ["definition", key, "*"],
3261
- since: "0.1.0",
3262
- when: isObject,
3263
- message: (entry) => {
3264
- const fields = entry;
3265
- const identifier = typeof fields.identifier === "string" ? fields.identifier : "<name>";
3266
- const moved = MOVED_REFERENCE_FIELDS.find(([field]) => fields[field] !== void 0);
3267
- return `\`${key}\` is an array of capability identifiers. Replace ${JSON.stringify(entry)} with ${JSON.stringify(identifier)}.` + (moved ? ` \`${moved[0]}\` has been removed: ${moved[1]}.` : "");
3268
- }
3269
- };
3270
- }
3271
- var REMOVED_FIELDS = [
3272
- container(
3273
- "package",
3274
- "its `identifier` moves to the top level, its `name` is now the game's name in its first supported locale, and its `version` lives in package.json"
3275
- ),
3276
- container("game", "its settings move to the top level, beside the resource lists"),
3277
- container(
3278
- "games",
3279
- "a package is a game: move the settings out of `games/<identifier>/game.sdk.json` to the top level of this file, drop the game identifier, and delete the directory"
3280
- ),
3281
- ...[
3282
- "modules",
3283
- "capabilities",
3284
- "userInterfaces",
3285
- "configurationUserInterfaces",
3286
- "sessionUserInterfaces",
3287
- "waitingRoomUserInterfaces",
3288
- "scenarios",
3289
- "facilitatorGuides",
3290
- "tickControllers",
3291
- "hooks",
3292
- "validators",
3293
- "endpoints"
3294
- ].map(resourceList),
3295
- {
3296
- where: "package",
3297
- path: ["configuration-user-interfaces"],
3298
- since: "1.0.0",
3299
- message: "Configuration user interfaces have been removed: their two jobs are slots of their own. Move the UI that served 'quick-config' to `setup/` and the one that served 'scenario-builder' to `scenario_editor/`, letting its files sit directly in the slot, rename its bundle to `setup.sdk.json` or `scenario_editor.sdk.json`, delete its `identifier`, and delete `configuration-user-interfaces/`. A UI wired into both becomes two slots, or one if the game needs only one of the jobs."
3300
- },
3301
- {
3302
- where: "manifest",
3303
- path: ["configurationSurfaces"],
3304
- since: "1.0.0",
3305
- message: REMOVED_CONFIGURATION_SURFACES
3306
- },
3307
- pluralSlotDirectory("modules", "engine", "engine"),
3308
- pluralSlotDirectory("user-interfaces", "ui", "user interface"),
3309
- pluralSlotDirectory("session-user-interfaces", "session", "session user interface"),
3310
- pluralSlotDirectory(
3311
- "waiting-room-user-interfaces",
3312
- "waiting_room",
3313
- "waiting room user interface"
3314
- ),
3315
- pluralSlotDirectory("facilitator-guides", "guide", "facilitator guide"),
3316
- pluralSlotDirectory("tick-controllers", "tick_controller", "tick controller"),
3317
- {
3318
- where: "manifest",
3319
- path: ["configurationUserInterface"],
3320
- since: "0.0.107",
3321
- message: "configurationUserInterface has been removed. A light form shown at session creation is the `setup` slot (setup/setup.sdk.json), and a screen for authoring lasting scenarios is the `scenario_editor` slot (scenario_editor/scenario_editor.sdk.json). See the upgrade guide: docs/guides/upgrading.md"
3322
- },
3323
- gameReference("hookOrder", "hooks run in the order the package declares them"),
3324
- gameReference("validatorOrder", "validators run in the order the package declares them"),
3325
- gameReference("moduleOrder", "a game holds one engine, so there is no order to declare"),
3326
- gameReference(
3327
- "tickController",
3328
- "the package's tick controller is the game's; declare it in `tickControllers`"
3329
- ),
3330
- gameReference(
3331
- "sessionUserInterface",
3332
- "the package's session user interface is the game's; it lives in the `session` slot, and what it reads is listed in its `settings`"
3333
- ),
3334
- {
3335
- where: "manifest",
3336
- path: ["waitingRoom", "identifier"],
3337
- since: "0.1.0",
3338
- message: "waitingRoom.identifier has been removed. The package's waiting room user interface is the game's; keep only the settings, such as `openOnStart`."
3339
- },
3340
- {
3341
- where: "manifest",
3342
- path: ["configuration"],
3343
- since: "1.0.0",
3344
- message: REMOVED_GAME_CONFIGURATION
3345
- },
3346
- { where: "manifest", path: ["demo"], since: "1.0.0", message: REMOVED_DEMO },
3347
- {
3348
- where: "manifest",
3349
- path: ["ticks"],
3350
- since: "1.0.0",
3351
- message: RENAMED_MANIFEST_TICKS
3352
- },
3353
- {
3354
- where: "every bundle",
3355
- path: ["definition", "identifier"],
3356
- since: "0.1.0",
3357
- message: "`identifier` has been removed. A resource is named by its directory, so delete the field; the directory name is the identifier."
3358
- },
3359
- {
3360
- where: ["engine"],
3361
- path: ["definition", "aggregate"],
3362
- since: "0.2.0",
3363
- message: "`aggregate` has been removed. An engine is aggregate because it exports `InitAggregate` and `RunAggregate`, and the build reads that from the code. Delete the field; export the pair to make the engine aggregate, or remove the pair to make it per-team."
3364
- },
3365
- {
3366
- where: ["validator"],
3367
- path: ["definition", "gates"],
3368
- since: "1.0.0",
3369
- message: "`gates` is generated, not authored. A validator gates what its logic exports a function for: `UpdateData` for a context write, `RequestTick` for a tick request. Delete the field."
3370
- },
3371
- {
3372
- where: ["endpoint"],
3373
- path: ["definition", "responds"],
3374
- since: "1.0.0",
3375
- message: "`responds` is generated, not authored. An endpoint responds after its effects when its logic exports `Plan` and `Respond`. Delete the field."
3376
- },
3377
- {
3378
- where: NAMELESS_UI_BUNDLES,
3379
- path: ["definition", "locales"],
3380
- since: "0.1.0",
3381
- message: "`locales` has been removed. A game holds one of this interface, so nothing labels it and the name was never shown. Delete the field; the screen's own strings belong in its `src/i18n.ts`."
3382
- },
3383
- {
3384
- where: ["endpoint"],
3385
- path: ["definition", "agentCallable"],
3386
- since: "1.0.0",
3387
- message: (value) => "`agentCallable` has been replaced by `visibility`. " + (value === true ? 'Replace `"agentCallable": true` with `"visibility": "external"`.' : "Delete the field; an endpoint is internal unless it says otherwise.")
3388
- },
3389
- {
3390
- where: "every bundle",
3391
- path: ["definition", "configurationSchema"],
3392
- since: "1.0.0",
3393
- message: REMOVED_CONFIGURATION_SCHEMA
3394
- },
3395
- {
3396
- where: ["scenario"],
3397
- path: ["definition", "configuration"],
3398
- since: "1.0.0",
3399
- message: RENAMED_SCENARIO_CONFIGURATION
3400
- },
3401
- { where: ["scenario"], path: ["definition", "demo"], since: "1.0.0", message: REMOVED_DEMO },
3402
- ...["ticks", "teams", "waitingRoom"].map((key) => ({
3403
- where: ["scenario"],
3404
- path: ["definition", key],
3405
- since: "1.0.0",
3406
- message: (value) => movedScenarioGameField(key, value)
3407
- })),
3408
- { where: UI_BUNDLES, path: ["definition", "uses"], since: "1.0.0", message: REMOVED_UI_USES },
3409
- objectReference("reads"),
3410
- objectReference("writes")
3411
- ];
3412
- function valuesAt(data, path, at = []) {
3413
- if (data === void 0) return [];
3414
- const [head, ...rest] = path;
3415
- if (head === void 0) return [{ pointer: at, value: data }];
3416
- if (head === "*") {
3417
- return Array.isArray(data) ? data.flatMap((entry, index) => valuesAt(entry, rest, [...at, index])) : [];
3418
- }
3419
- if (!isObject(data)) return [];
3420
- return valuesAt(data[head], rest, [...at, head]);
3421
- }
3422
- function match(field, pointer, value) {
3423
- const text = typeof field.message === "string" ? field.message : field.message(value);
3424
- if (field.hint === void 0) return { field, pointer, explanation: text, ...splitHint(text) };
3425
- return {
3426
- field,
3427
- pointer,
3428
- explanation: `${text} ${field.hint}`,
3429
- message: text,
3430
- hint: field.hint
3431
- };
3432
- }
3433
- function matchesAt(field, data) {
3434
- return valuesAt(data, field.path).filter(({ value }) => field.when?.(value) ?? true).map(({ pointer, value }) => match(field, pointer, value));
3435
- }
3436
- function removedFromPackage(manifest, directoryExists) {
3437
- return REMOVED_FIELDS.flatMap((field) => {
3438
- if (field.where === "manifest") return matchesAt(field, manifest);
3439
- if (field.where === "package") {
3440
- const directory = field.path.join("/");
3441
- return directoryExists(directory) ? [match(field, [directory], void 0)] : [];
3442
- }
3443
- return [];
3444
- });
3445
- }
3446
- function removedFromBundle(type, bundle) {
3447
- return REMOVED_FIELDS.flatMap((field) => {
3448
- if (field.where === "manifest" || field.where === "package") return [];
3449
- if (field.where !== "every bundle" && !field.where.includes(type)) return [];
3450
- return matchesAt(field, bundle);
3451
- });
3452
- }
3453
-
3454
- // cli/discovery/config.ts
3455
- async function loadConfig(configPath) {
3456
- let configContent;
3457
- try {
3458
- configContent = await readFile(configPath, "utf-8");
3459
- } catch (error) {
3460
- throw new CliError(
3461
- error.code === "ENOENT" ? "MANIFEST_NOT_FOUND" : "MANIFEST_INVALID",
3462
- `Could not read ${configPath}: ${error.message}`,
3463
- { hint: "Run the command in a Serious Gaming package, or pass --working-dir." }
3464
- );
3465
- }
3466
- let jsonConfig;
3467
- try {
3468
- jsonConfig = JSON.parse(configContent);
3469
- } catch (error) {
3470
- throw new CliError(
3471
- "MANIFEST_INVALID",
3472
- `${basename(configPath)} is not valid JSON: ${error.message}`,
3473
- {
3474
- diagnostics: [
3475
- {
3476
- severity: "error",
3477
- code: "JSON_INVALID",
3478
- message: error.message,
3479
- file: basename(configPath)
3480
- }
3481
- ]
3482
- }
3483
- );
3484
- }
3485
- const configDir = dirname(configPath);
3486
- const problems = new LoadProblems();
3487
- reportRemovedFromPackage(problems, jsonConfig, configPath);
3488
- problems.throwIfAny();
3489
- checkValid(problems, validatePackageManifest(jsonConfig), "package", {
3490
- file: basename(configPath)
3491
- });
3492
- problems.throwIfAny();
3493
- const constraintFindings = gameConstraintFindings(jsonConfig);
3494
- for (const finding of constraintFindings) {
3495
- problems.add(finding.code, `Invalid package: ${finding.message}`, [finding]);
3496
- }
3497
- problems.throwIfAny();
3498
- assertRequiredFeaturesSupported(jsonConfig, configPath);
3499
- const capabilities = await discover(configDir, KINDS.capability, problems);
3500
- const authoredSettings = await discover(configDir, KINDS.settings, problems);
3501
- refuseReservedSettings(problems, authoredSettings);
3502
- const scenarios = await discover(configDir, KINDS.scenario, problems);
3503
- const hooks = await discover(configDir, KINDS.hook, problems);
3504
- const discoveredValidators = await discover(configDir, KINDS.validator, problems);
3505
- const discoveredEndpoints = await discover(configDir, KINDS.endpoint, problems);
3506
- const discoveredEngine = await discoverSlot(configDir, KINDS.engine, problems);
3507
- const ui = await discoverSlot(configDir, KINDS.ui, problems);
3508
- const session = await discoverSlot(configDir, KINDS.session, problems);
3509
- const waiting_room = await discoverSlot(
3510
- configDir,
3511
- KINDS.waiting_room,
3512
- problems
3513
- );
3514
- const presentation = await discoverSlot(
3515
- configDir,
3516
- KINDS.presentation,
3517
- problems
3518
- );
3519
- const setup = await discoverSlot(configDir, KINDS.setup, problems);
3520
- const scenario_editor = await discoverSlot(
3521
- configDir,
3522
- KINDS.scenario_editor,
3523
- problems
3524
- );
3525
- const tick_controller = await discoverSlot(
3526
- configDir,
3527
- KINDS.tick_controller,
3528
- problems
3529
- );
3530
- const guide = await discoverSlot(configDir, KINDS.guide, problems);
3531
- problems.throwIfAny();
3532
- const validators2 = await withDerivedGates(discoveredValidators, configDir, problems);
3533
- const endpoints = await withDerivedResponds(discoveredEndpoints, configDir, problems);
3534
- const engine = await withDerivedAggregate(discoveredEngine, configDir);
3535
- problems.throwIfAny();
3536
- assertDeclaredServicesSupported([
3537
- ...engine ? [engine] : [],
3538
- ...tick_controller ? [tick_controller] : [],
3539
- ...hooks,
3540
- ...endpoints
3541
- ]);
3542
- const game = {
3543
- definition: {
3544
- ...gameSettings(jsonConfig),
3545
- identifier: `${jsonConfig.identifier}.game`
3546
- },
3547
- rootDirectory: "."
3548
- };
3549
- return {
3550
- ...jsonConfig.requires?.length ? { requires: jsonConfig.requires } : {},
3551
- ...jsonConfig.scenarioFormat === void 0 ? {} : { scenarioFormat: jsonConfig.scenarioFormat },
3552
- package: resolvePackage(jsonConfig, configDir, game),
3553
- game,
3554
- ...engine ? { engine } : {},
3555
- ...ui ? { ui } : {},
3556
- ...session ? { session } : {},
3557
- ...waiting_room ? { waiting_room } : {},
3558
- ...presentation ? { presentation } : {},
3559
- ...setup ? { setup } : {},
3560
- ...scenario_editor ? { scenario_editor } : {},
3561
- ...tick_controller ? { tick_controller } : {},
3562
- ...guide ? { guide } : {},
3563
- capabilities,
3564
- // The built-in `game` settings come first, then the package's own.
3565
- settings: [gameSettingsResource(jsonConfig), ...authoredSettings],
3566
- scenarios,
3567
- hooks,
3568
- validators: validators2,
3569
- endpoints
3570
- };
3571
- }
3572
- async function discoverSlot(configDir, resourceKind, problems) {
3573
- return (await discover(configDir, resourceKind, problems))[0];
3574
- }
3575
- var AGGREGATE_EXPORTS = ["InitAggregate", "RunAggregate"];
3576
- async function withDerivedAggregate(engine, configDir) {
3577
- if (!engine) return void 0;
3578
- const logicFile = join(
3579
- configDir,
3580
- engine.rootDirectory,
3581
- engine.logic.directory,
3582
- engine.logic.entrypoint
3583
- );
3584
- const { present } = await readLogicExports(logicFile, AGGREGATE_EXPORTS);
3585
- const aggregate = AGGREGATE_EXPORTS.some((name) => present.has(name));
3586
- return {
3587
- ...engine,
3588
- definition: { ...engine.definition, aggregate }
3589
- };
3590
- }
3591
- var GATE_EXPORTS = {
3592
- UpdateData: "updateData",
3593
- RequestTick: "requestTick",
3594
- Scenario: "scenario"
3595
- };
3596
- async function withDerivedGates(validators2, configDir, problems) {
3597
- return Promise.all(
3598
- validators2.map(async (validator) => {
3599
- const logicFile = join(
3600
- configDir,
3601
- validator.rootDirectory,
3602
- validator.logic.directory,
3603
- validator.logic.entrypoint
3604
- );
3605
- const { present } = await readLogicExports(logicFile, [
3606
- ...Object.keys(GATE_EXPORTS),
3607
- "Run"
3608
- ]);
3609
- if (present.has("Run")) {
3610
- const hint = "A validator now names what it gates: rename `Run` to `UpdateData` to gate a participant's context write, or export `RequestTick` to gate their request for the next tick.";
3611
- problems.add(
3612
- "BUNDLE_INVALID",
3613
- `Validator "${validator.definition.identifier}" exports \`Run\`. ${hint}`,
3614
- [
3615
- {
3616
- code: "LOGIC_EXPORT_MISSING",
3617
- message: "The validator exports `Run`, which has been renamed.",
3618
- file: packageRelative(configDir, logicFile),
3619
- resource: {
3620
- type: "validator",
3621
- identifier: validator.definition.identifier
3622
- },
3623
- hint
3624
- }
3625
- ]
3626
- );
3627
- }
3628
- const gates = Object.entries(GATE_EXPORTS).filter(([name]) => present.has(name)).map(([, gate]) => gate);
3629
- return { ...validator, definition: { ...validator.definition, gates } };
3630
- })
3631
- );
3632
- }
3633
- async function withDerivedResponds(endpoints, configDir, problems) {
3634
- return Promise.all(
3635
- endpoints.map(async (endpoint) => {
3636
- const logicFile = join(
3637
- configDir,
3638
- endpoint.rootDirectory,
3639
- endpoint.logic.directory,
3640
- endpoint.logic.entrypoint
3641
- );
3642
- const { present } = await readLogicExports(logicFile, ["Handle", "Plan", "Respond"]);
3643
- const { identifier, writes, actions } = endpoint.definition;
3644
- let refused = false;
3645
- const refuse = (why) => {
3646
- if (refused) return;
3647
- refused = true;
3648
- problems.add("BUNDLE_INVALID", `Endpoint "${identifier}" ${why}`, [
3649
- {
3650
- code: "LOGIC_EXPORT_MISSING",
3651
- ...splitHint(`The endpoint ${why}`),
3652
- file: packageRelative(configDir, logicFile),
3653
- resource: { type: "endpoint", identifier }
3654
- }
3655
- ]);
3656
- };
3657
- if (present.has("Handle") && present.has("Plan")) {
3658
- refuse(
3659
- "exports both `Handle` and `Plan`. Export `Handle` alone to return the response with the effects, or `Plan` and `Respond` to write the response after they land."
3660
- );
3661
- }
3662
- if (present.has("Handle") && present.has("Respond")) {
3663
- refuse(
3664
- "exports `Respond` beside `Handle`. An endpoint that responds after its effects decides them in `Plan`: rename `Handle` to `Plan`, and return the effects alone."
3665
- );
3666
- }
3667
- if (present.has("Plan") && !present.has("Respond")) {
3668
- refuse(
3669
- "exports `Plan` without `Respond`, so nothing writes its response. Export `Respond`, or rename `Plan` to `Handle` and return the response from it."
3670
- );
3671
- }
3672
- if (present.has("Respond") && !present.has("Plan")) {
3673
- refuse("exports `Respond` without `Plan`, so nothing decides its effects.");
3674
- }
3675
- const responds = present.has("Plan");
3676
- if (!refused && responds && (writes ?? []).length === 0 && (actions ?? []).length === 0) {
3677
- refuse(
3678
- "exports `Plan` and `Respond`, but declares no `writes` and no `actions`, so there are no effects to plan. Export `Handle` alone and return the response from it."
3679
- );
3680
- }
3681
- return responds ? { ...endpoint, definition: { ...endpoint.definition, responds } } : endpoint;
3682
- })
3683
- );
3684
- }
3685
- var NOT_GAME_FIELDS = /* @__PURE__ */ new Set([
3686
- "identifier",
3687
- "requires",
3688
- "scenarioFormat",
3689
- "maxTicks",
3690
- "waitingRoom",
3691
- "teams",
3692
- "gameSettingsConstraints"
3693
- ]);
3694
- function gameSettings(config) {
3695
- const definition = Object.fromEntries(
3696
- Object.entries(config).filter(([key]) => !NOT_GAME_FIELDS.has(key))
3697
- );
3698
- if (config.teams?.mode !== void 0) definition.teams = { mode: config.teams.mode };
3699
- return definition;
3700
- }
3701
- function refuseReservedSettings(problems, settings) {
3702
- if (!settings.some((entry) => entry.definition.identifier === GAME_SETTINGS)) return;
3703
- const message = `\`settings/${GAME_SETTINGS}/\` is reserved for the built-in game settings`;
3704
- const hint = "Set the game's own values in seriousgaming.sdk.json (`maxTicks`, `teams`, `waitingRoom`), and rename this settings resource.";
3705
- problems.add("SETTINGS_RESERVED", `Invalid package: ${message}. ${hint}`, [
3706
- {
3707
- code: "SETTINGS_RESERVED",
3708
- message,
3709
- hint,
3710
- file: `settings/${GAME_SETTINGS}/settings.sdk.json`
3711
- }
3712
- ]);
3713
- }
3714
- function assertRequiredFeaturesSupported(config, filePath) {
3715
- const missing = unsupportedFeatures(config);
3716
- if (missing.length === 0) return;
3717
- const file = basename(filePath);
3718
- const hint = "Upgrade the SDK, or remove the feature from `requires` if the game does not depend on it.";
3719
- throw new CliError(
3720
- "MANIFEST_INVALID",
3721
- `Invalid manifest "${file}": \`requires\` lists ${missing.map((f) => `"${f}"`).join(", ")}, which this version of the SDK does not support. ${hint}`,
3722
- {
3723
- diagnostics: missing.map((feature) => ({
3724
- severity: "error",
3725
- code: "FEATURE_UNSUPPORTED",
3726
- message: `"${feature}" is not a feature this version of the SDK supports`,
3727
- file,
3728
- pointer: pointerOf("requires", (config.requires ?? []).indexOf(feature)),
3729
- hint
3730
- }))
3731
- }
3732
- );
3733
- }
3734
- function assertDeclaredServicesSupported(resources) {
3735
- const missing = unsupportedServices(resources);
3736
- if (missing.length === 0) return;
3737
- const named2 = missing.map(
3738
- ({ service, resources: declaring }) => `"${service}" (declared by ${declaring.join(", ")})`
3739
- ).join(", ");
3740
- throw new CliError(
3741
- "PACKAGE_INVALID",
3742
- `Invalid package: its resources declare ${named2} in \`uses\`, which this version of the SDK does not provide. Upgrade the SDK, or remove the service from \`uses\` if the resource does not call it.`
3743
- );
3744
- }
3745
- function resolvePackage(config, configDir, game) {
3746
- const locale = game.definition.supportedLocales?.[0] ?? "en";
3747
- return {
3748
- definition: {
3749
- identifier: config.identifier,
3750
- name: game.definition.locales?.[locale]?.name ?? config.identifier,
3751
- version: readPackageVersion(configDir)
3752
- }
3753
- };
3754
- }
3755
- var UNVERSIONED = "0.0.0";
3756
- function readPackageVersion(configDir) {
3757
- try {
3758
- const raw = readFileSync(join(configDir, "package.json"), "utf-8");
3759
- const version = JSON.parse(raw).version;
3760
- return typeof version === "string" && version.length > 0 ? version : UNVERSIONED;
3761
- } catch {
3762
- return UNVERSIONED;
3763
- }
3764
- }
3765
- var LoadProblems = class {
3766
- entries = [];
3767
- add(code, text, findings) {
3768
- this.entries.push({ code, text, findings });
3769
- }
3770
- get count() {
3771
- return this.entries.length;
3772
- }
3773
- /**
3774
- * Fail with everything collected so far. The error's code is the one every
3775
- * problem shares, or PACKAGE_INVALID when they differ; each finding keeps
3776
- * its own.
3777
- */
3778
- throwIfAny() {
3779
- if (this.entries.length === 0) return;
3780
- const codes = new Set(this.entries.map((entry) => entry.code));
3781
- const [only] = codes;
3782
- throw new CliError(
3783
- codes.size === 1 && only !== void 0 ? only : "PACKAGE_INVALID",
3784
- this.entries.map((entry) => entry.text).join("\n"),
3785
- {
3786
- diagnostics: this.entries.flatMap(
3787
- (entry) => entry.findings.map((finding) => ({ severity: "error", ...finding }))
3788
- )
3789
- }
3790
- );
3791
- }
3792
- };
3793
- function reportRemovedFromPackage(problems, manifest, filePath) {
3794
- const configDir = dirname(filePath);
3795
- const removed = removedFromPackage(
3796
- manifest,
3797
- (directory) => existsSync2(join(configDir, directory))
3798
- );
3799
- for (const { field, pointer, explanation, message, hint } of removed) {
3800
- const finding = { message, ...hint === void 0 ? {} : { hint } };
3801
- if (field.where === "package") {
3802
- problems.add("PACKAGE_INVALID", `Invalid package: ${explanation}`, [
3803
- { code: "LAYOUT_OUTDATED", ...finding, file: `${pointer.join("/")}/` }
3804
- ]);
3805
- } else {
3806
- problems.add(
3807
- "MANIFEST_INVALID",
3808
- `Invalid manifest "${basename(filePath)}": ${explanation}`,
3809
- [
3810
- {
3811
- code: "REMOVED_FIELD",
3812
- ...finding,
3813
- file: basename(filePath),
3814
- pointer: pointerOf(...pointer)
3815
- }
3816
- ]
3817
- );
3818
- }
3819
- }
3820
- }
3821
- function reportRemovedFromBundle(problems, type, data, site) {
3822
- for (const { pointer, explanation, message, hint } of removedFromBundle(type, data)) {
3823
- problems.add("BUNDLE_INVALID", `Invalid bundle "${site.relPath}": ${explanation}`, [
3824
- {
3825
- code: "REMOVED_FIELD",
3826
- message,
3827
- ...hint === void 0 ? {} : { hint },
3828
- file: site.relPath,
3829
- pointer: pointerOf(...pointer),
3830
- resource: site.resource
3831
- }
3832
- ]);
3833
- }
3834
- }
3835
- function checkValid(problems, result, resourceType, location) {
3836
- if (result.valid) return true;
3837
- const findings = (result.findings ?? [{ code: "SCHEMA_INVALID", message: result.errors ?? "" }]).map((finding) => ({
3838
- ...finding,
3839
- // A field the table of removed fields does not explain may still be
3840
- // one an upgrade took away.
3841
- ...finding.code === "SCHEMA_INVALID" && finding.hint === void 0 ? { hint: UPGRADING_HINT } : {},
3842
- file: location.file,
3843
- ...location.resource ? { resource: location.resource } : {}
3844
- }));
3845
- problems.add(
3846
- resourceType === "package" ? "MANIFEST_INVALID" : "BUNDLE_INVALID",
3847
- `Invalid ${resourceType} file "${location.file}":
3848
- ${result.errors}`,
3849
- findings
3850
- );
3851
- return false;
3852
- }
3853
- function kind(type, validate, hasRootDirectory = true) {
3854
- return { meta: getResourceMeta(type), validate, hasRootDirectory };
3855
- }
3856
- var KINDS = {
3857
- capability: kind("capability", validateSDKCapability, false),
3858
- settings: kind("settings", validateSDKSettings, false),
3859
- engine: kind("engine", validateSDKEngine),
3860
- ui: kind("ui", validateSDKUserInterface),
3861
- session: kind("session", validateSDKSessionUserInterface),
3862
- waiting_room: kind("waiting_room", validateSDKWaitingRoomUserInterface),
3863
- presentation: kind("presentation", validateSDKPresentation),
3864
- setup: kind("setup", validateSDKSetup),
3865
- scenario_editor: kind("scenario_editor", validateSDKScenarioEditor),
3866
- scenario: kind("scenario", validateSDKScenario),
3867
- guide: kind("guide", validateSDKFacilitatorGuide),
3868
- tick_controller: kind("tick_controller", validateSDKTickController),
3869
- hook: kind("hook", validateSDKHook),
3870
- validator: kind("validator", validateSDKValidator),
3871
- endpoint: kind("endpoint", validateSDKEndpoint)
3872
- };
3873
- function isNotFound(error) {
3874
- return error?.code === "ENOENT";
3875
- }
3876
- async function discover(configDir, resourceKind, problems) {
3877
- const { meta } = resourceKind;
3878
- const names = meta.slot ? existsSync2(join(configDir, meta.slot, meta.bundleFile)) ? [meta.slot] : [] : await scanNames(configDir, meta);
3879
- const resolved = [];
3880
- for (const name of names) {
3881
- const dir = meta.slot ?? `${meta.pluralDir}/${name}`;
3882
- const relPath = `${dir}/${meta.bundleFile}`;
3883
- const fullPath = join(configDir, relPath);
3884
- let data;
3885
- try {
3886
- data = JSON.parse(await readFile(fullPath, "utf-8"));
3887
- } catch (error) {
3888
- const resource = { type: meta.type, identifier: name };
3889
- if (isNotFound(error)) {
3890
- problems.add(
3891
- "BUNDLE_INVALID",
3892
- `Resource directory ${dir}/ contains no bundle.
3893
- Delete the directory, or add ${meta.bundleFile} to it.`,
3894
- [
3895
- {
3896
- code: "BUNDLE_MISSING",
3897
- message: `${dir}/ contains no bundle.`,
3898
- file: `${dir}/`,
3899
- resource,
3900
- hint: `Delete the directory, or add ${meta.bundleFile} to it.`
3901
- }
3902
- ]
3903
- );
3904
- continue;
3905
- }
3906
- const message = error instanceof Error ? error.message : String(error);
3907
- problems.add(
3908
- "BUNDLE_INVALID",
3909
- `Failed to load ${meta.label.toLowerCase()} "${name}": expected a bundle at ${relPath}.
3910
- ${message}`,
3911
- [{ code: "JSON_INVALID", message, file: relPath, resource }]
3912
- );
3913
- continue;
3914
- }
3915
- const site = { relPath, resource: { type: meta.type, identifier: name } };
3916
- const before = problems.count;
3917
- reportRemovedFromBundle(problems, meta.type, data, site);
3918
- if (problems.count > before) continue;
3919
- const bundle = data;
3920
- const withIdentifier = {
3921
- ...bundle,
3922
- definition: { ...bundle.definition, identifier: name }
3923
- };
3924
- if (!checkValid(problems, resourceKind.validate(withIdentifier), meta.label.toLowerCase(), {
3925
- file: relPath,
3926
- resource: site.resource
3927
- })) {
3928
- continue;
3929
- }
3930
- if (resourceKind.hasRootDirectory) {
3931
- resolved.push({
3932
- ...withIdentifier,
3933
- rootDirectory: resolveManifestRootDirectory(
3934
- relPath,
3935
- bundle.rootDirectory
3936
- )
3937
- });
3938
- } else {
3939
- resolved.push(withIdentifier);
3940
- }
3941
- logger.debug(`Loaded: ${relPath}`);
3942
- }
3943
- return resolved;
3944
- }
3945
- function packageRelative(configDir, path) {
3946
- return relative2(configDir, path).split(sep2).join("/");
3947
- }
3948
- async function scanNames(configDir, meta) {
3949
- let entries;
3950
- try {
3951
- entries = await readdir(join(configDir, meta.pluralDir), { withFileTypes: true });
3952
- } catch {
3953
- return [];
3954
- }
3955
- return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
3956
- }
3957
-
3958
- export {
3959
- GAME_SETTINGS,
3960
- teamsMaxOf,
3961
- gameSettingsOf,
3962
- declaredGameSettings,
3963
- UndeclaredApiUseError,
3964
- settingPath,
3965
- parseSettingPath,
3966
- SCENARIO_GATE_READ_LIMIT_BYTES,
3967
- ScenarioAssetTooLargeError,
3968
- isLocalRef,
3969
- resolveLocalRef,
3970
- dereference,
3971
- refProblems,
3972
- refProblemMessage,
3973
- unenforceableLocks,
3974
- unenforceableLockMessage,
3975
- withoutLockedDefaults,
3976
- createAjv,
3977
- MANIFEST_REFERRER,
3978
- RESOURCE_METADATA,
3979
- RESOURCE_METADATA_BY_MANIFEST_KEY,
3980
- findResourceMeta,
3981
- isNamelessInterface,
3982
- getResourceMeta,
3983
- getPluralResourceMeta,
3984
- MANIFEST_FILE,
3985
- bundleFileOf,
3986
- pointerOf,
3987
- didYouMean,
3988
- validateSDKCapability,
3989
- validateSDKSettings,
3990
- validateSDKEngine,
3991
- validateSDKUserInterface,
3992
- validatePackageManifest,
3993
- validateSDKTickController,
3994
- validateSDKScenario,
3995
- validateSDKFacilitatorGuide,
3996
- validateSDKSetup,
3997
- validateSDKScenarioEditor,
3998
- validateSDKSessionUserInterface,
3999
- validateSDKWaitingRoomUserInterface,
4000
- validateSDKPresentation,
4001
- validateSDKHook,
4002
- validateSDKValidator,
4003
- validateSDKEndpoint,
4004
- settingsSchemas,
4005
- collectSettingsOverrideErrors,
4006
- collectSettingsOverrideFindings,
4007
- validateSessionOverrides,
4008
- validateSettingsOverrides,
4009
- openSettingsObjects,
4010
- errorMessage,
4011
- DeniedError,
4012
- realPath,
4013
- LOGIC_NODE_BUILTIN,
4014
- Transpile,
4015
- readLogicExports,
4016
- MANIFEST_VERSION,
4017
- SPEC_REVISION,
4018
- REMOVED_CONFIGURATION_SCHEMA,
4019
- REMOVED_GAME_CONFIGURATION,
4020
- RENAMED_SCENARIO_CONFIGURATION,
4021
- REMOVED_UI_USES,
4022
- REMOVED_DEMO,
4023
- REMOVED_CONFIGURATION_SURFACES,
4024
- removedFromBundle,
4025
- loadConfig
4026
- };