@seriousgaming/sdk-tools 1.4.0 → 1.6.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 (302) hide show
  1. package/dist/bundling/ui-bundler.d.ts +12 -0
  2. package/dist/cli-25RWY5BQ.js +41 -0
  3. package/dist/cli-272KBNJH.js +97 -0
  4. package/dist/cli-2BH7FX27.js +52 -0
  5. package/dist/cli-2GOFEW26.js +81 -0
  6. package/dist/cli-3E3MD5U4.js +21 -0
  7. package/dist/cli-3HE4AVZG.js +115 -0
  8. package/dist/cli-4AKVLEC4.js +1387 -0
  9. package/dist/cli-4BV45LBH.js +126 -0
  10. package/dist/cli-4LKXZQ2B.js +48 -0
  11. package/dist/cli-4UWFQNGF.js +54 -0
  12. package/dist/cli-4YB3ROVR.js +78 -0
  13. package/dist/cli-57RXC3HQ.js +36 -0
  14. package/dist/cli-5JEGTVTG.js +96 -0
  15. package/dist/cli-6AMT3BUO.js +97 -0
  16. package/dist/cli-6RRVEGFB.js +80 -0
  17. package/dist/cli-6WXLXJVX.js +36 -0
  18. package/dist/cli-7OGYADZ3.js +97 -0
  19. package/dist/cli-AK7OIPWY.js +229 -0
  20. package/dist/cli-B4TN6PJP.js +124 -0
  21. package/dist/cli-B6YHEKIJ.js +248 -0
  22. package/dist/cli-BPYMTOUL.js +89 -0
  23. package/dist/cli-BWX5E7TQ.js +23 -0
  24. package/dist/cli-BYJWFFCF.js +37 -0
  25. package/dist/cli-C3NVCKO6.js +43 -0
  26. package/dist/cli-C47GJATR.js +42 -0
  27. package/dist/cli-C5QOJJWX.js +46 -0
  28. package/dist/cli-C6TH5S7K.js +6417 -0
  29. package/dist/cli-DL2CVMRF.js +89 -0
  30. package/dist/cli-DMW2OQIJ.js +76 -0
  31. package/dist/cli-DZW3XD5F.js +143 -0
  32. package/dist/cli-E2NLWIFE.js +1331 -0
  33. package/dist/cli-E33CJRRQ.js +36 -0
  34. package/dist/cli-E6DJIMYD.js +142 -0
  35. package/dist/cli-EEFJKIGL.js +151 -0
  36. package/dist/cli-EVFS55WN.js +185 -0
  37. package/dist/cli-F2D4GGUA.js +549 -0
  38. package/dist/cli-FBTRTIZJ.js +226 -0
  39. package/dist/cli-FWFRKQNE.js +11 -0
  40. package/dist/cli-FYINNRML.js +760 -0
  41. package/dist/cli-G522CPRL.js +88 -0
  42. package/dist/cli-G6KELFSX.js +2847 -0
  43. package/dist/cli-G6UE5NL4.js +90 -0
  44. package/dist/cli-GBFM76BF.js +16 -0
  45. package/dist/cli-GDQ6ILJY.js +101 -0
  46. package/dist/cli-GFBGYFYD.js +50 -0
  47. package/dist/cli-GGPDQNM3.js +35 -0
  48. package/dist/cli-GTSGLN3Z.js +307 -0
  49. package/dist/cli-GUXKQMJ7.js +13641 -0
  50. package/dist/cli-GXD36NF2.js +60 -0
  51. package/dist/cli-HCRTYQQS.js +16 -0
  52. package/dist/cli-HYY64SUD.js +185 -0
  53. package/dist/cli-I355WTAF.js +463 -0
  54. package/dist/cli-IDKYF5XB.js +59 -0
  55. package/dist/cli-ILKCQNM6.js +8 -0
  56. package/dist/cli-IRZ5KB7D.js +36 -0
  57. package/dist/cli-IUS2YCD3.js +31 -0
  58. package/dist/cli-J4DKUUTK.js +138 -0
  59. package/dist/cli-JFU22EJ2.js +187 -0
  60. package/dist/cli-JMZLT65J.js +226 -0
  61. package/dist/cli-JZM7XTNV.js +89 -0
  62. package/dist/cli-K2B6WHKA.js +81 -0
  63. package/dist/cli-KL3756X6.js +126 -0
  64. package/dist/cli-KNOOKGYW.js +88 -0
  65. package/dist/cli-LFGRFIEO.js +226 -0
  66. package/dist/cli-LFM7GJHI.js +0 -0
  67. package/dist/cli-LMDJCHHD.js +304 -0
  68. package/dist/cli-LXYPE3L5.js +99 -0
  69. package/dist/cli-M6BCQRID.js +153 -0
  70. package/dist/cli-MBNMPVDC.js +367 -0
  71. package/dist/cli-MJUYJIEP.js +13 -0
  72. package/dist/cli-MMN4BPO4.js +145 -0
  73. package/dist/cli-MYJGMA6U.js +40 -0
  74. package/dist/cli-N6H6T2E2.js +616 -0
  75. package/dist/cli-O5KP4OVN.js +61 -0
  76. package/dist/cli-O6PWMJTZ.js +25 -0
  77. package/dist/cli-ORIG557O.js +141 -0
  78. package/dist/cli-PFFCNGHI.js +243 -0
  79. package/dist/cli-PNLYX6R6.js +131 -0
  80. package/dist/cli-PQBXVLEU.js +649 -0
  81. package/dist/cli-PTT5RGKO.js +62 -0
  82. package/dist/cli-Q2XJF5AS.js +127 -0
  83. package/dist/cli-QEVDDBNO.js +60 -0
  84. package/dist/cli-QEVE5HUM.js +167 -0
  85. package/dist/cli-QUIJCBYB.js +391 -0
  86. package/dist/cli-QUNIRH7A.js +57 -0
  87. package/dist/cli-QVASWX2A.js +187 -0
  88. package/dist/cli-QWQMPCL6.js +253 -0
  89. package/dist/cli-R4PCG5YX.js +131 -0
  90. package/dist/cli-RA673NGF.js +53 -0
  91. package/dist/cli-RN6IWTL2.js +36 -0
  92. package/dist/cli-ROT3DRKU.js +145 -0
  93. package/dist/cli-RZITKPJX.js +367 -0
  94. package/dist/cli-S5IVGDDD.js +32 -0
  95. package/dist/cli-S5QDONIQ.js +218 -0
  96. package/dist/cli-SIPDUBFL.js +36 -0
  97. package/dist/cli-SMFSZF2G.js +4009 -0
  98. package/dist/cli-SRHBXZCN.js +159 -0
  99. package/dist/cli-TCY5LJ7E.js +88 -0
  100. package/dist/cli-TDSQSCX4.js +131 -0
  101. package/dist/cli-TIDQ4WUE.js +257 -0
  102. package/dist/cli-TLLA6KAP.js +79 -0
  103. package/dist/cli-TPU4TUR6.js +132 -0
  104. package/dist/cli-U2UE7I7J.js +30 -0
  105. package/dist/cli-UELGBQG7.js +101 -0
  106. package/dist/cli-UHSZBKYO.js +97 -0
  107. package/dist/cli-UJ4UCL2Z.js +38 -0
  108. package/dist/cli-UKQYZYFK.js +31 -0
  109. package/dist/cli-UMFFURZ7.js +81 -0
  110. package/dist/cli-UNAJ2OTE.js +15 -0
  111. package/dist/cli-UNJ5X6BU.js +89 -0
  112. package/dist/cli-UTJU4IYG.js +117 -0
  113. package/dist/cli-V4GHRWOV.js +1837 -0
  114. package/dist/cli-VCI3CG36.js +73 -0
  115. package/dist/cli-VCKOC2EV.js +256 -0
  116. package/dist/cli-VL2P354N.js +46 -0
  117. package/dist/cli-WAE26SVW.js +72 -0
  118. package/dist/cli-WOGIAU2E.js +100 -0
  119. package/dist/cli-WU43JT4T.js +52 -0
  120. package/dist/cli-XCO2VQOH.js +122 -0
  121. package/dist/cli-XSVGKI3R.js +39 -0
  122. package/dist/cli-YOTGR3NB.js +82 -0
  123. package/dist/cli-YVVXUD2G.js +197 -0
  124. package/dist/cli-ZISJ36MM.js +89 -0
  125. package/dist/cli-ZTWOE3ZT.js +65 -0
  126. package/dist/cli-ZVSFYDPQ.js +205 -0
  127. package/dist/cli-ZWPYIXNI.js +68 -0
  128. package/dist/cli.js +171 -42385
  129. package/dist/client/build-surfaces.d.ts +33 -0
  130. package/dist/client/dev-server.d.ts +6 -0
  131. package/dist/client/index.d.ts +1 -0
  132. package/dist/client/playwright.d.ts +62 -0
  133. package/dist/client.js +339 -56
  134. package/dist/core/session.d.ts +15 -1
  135. package/dist/dev/console/assets/{index-BvB-LFQZ.js → index-CuMOOH9m.js} +21 -21
  136. package/dist/dev/console/index.html +1 -1
  137. package/dist/dev/public-origins.d.ts +61 -0
  138. package/dist/dev/shell.d.ts +51 -4
  139. package/dist/dev/surfaces.d.ts +7 -0
  140. package/dist/docs/ai-agents.md +5 -0
  141. package/dist/docs/api/index.md +14 -12
  142. package/dist/docs/api/sdk-tools-client.md +29 -0
  143. package/dist/docs/api/sdk-tools-playwright.md +104 -0
  144. package/dist/docs/changelog-0.x.md +2 -2
  145. package/dist/docs/changelog.md +56 -4
  146. package/dist/docs/cli-and-dev-server.md +79 -0
  147. package/dist/docs/cli-error-codes.md +39 -36
  148. package/dist/docs/cli-reference.md +93 -32
  149. package/dist/docs/environment-variables.md +16 -5
  150. package/dist/docs/guides/ai-facilitation.md +2 -0
  151. package/dist/docs/guides/capabilities.md +2 -0
  152. package/dist/docs/guides/designing-a-game.md +31 -4
  153. package/dist/docs/guides/designing-screens.md +133 -0
  154. package/dist/docs/guides/endpoints.md +2 -0
  155. package/dist/docs/guides/engine-testing.md +5 -1
  156. package/dist/docs/guides/engine.md +2 -0
  157. package/dist/docs/guides/file-handling.md +3 -1
  158. package/dist/docs/guides/games.md +3 -1
  159. package/dist/docs/guides/global-settings.md +2 -0
  160. package/dist/docs/guides/guide.md +2 -0
  161. package/dist/docs/guides/hooks.md +2 -0
  162. package/dist/docs/guides/index.md +9 -0
  163. package/dist/docs/guides/internationalization.md +2 -0
  164. package/dist/docs/guides/llm-integration.md +4 -2
  165. package/dist/docs/guides/multi-team-games.md +3 -1
  166. package/dist/docs/guides/patterns.md +2 -0
  167. package/dist/docs/guides/presentation.md +1 -1
  168. package/dist/docs/guides/production-constraints.md +2 -0
  169. package/dist/docs/guides/scenario-editor.md +2 -0
  170. package/dist/docs/guides/scenarios.md +6 -2
  171. package/dist/docs/guides/session-game-flow.md +365 -0
  172. package/dist/docs/guides/session-hooks.md +205 -0
  173. package/dist/docs/guides/session.md +27 -565
  174. package/dist/docs/guides/settings.md +2 -0
  175. package/dist/docs/guides/setup.md +3 -1
  176. package/dist/docs/guides/speech-generation.md +2 -0
  177. package/dist/docs/guides/starter-game.md +63 -23
  178. package/dist/docs/guides/testing.md +35 -18
  179. package/dist/docs/guides/tick-controller.md +3 -1
  180. package/dist/docs/guides/type-safety.md +2 -0
  181. package/dist/docs/guides/ui-files-and-llms.md +328 -0
  182. package/dist/docs/guides/ui-participants.md +281 -0
  183. package/dist/docs/guides/ui-styling.md +263 -0
  184. package/dist/docs/guides/ui-ticks.md +247 -0
  185. package/dist/docs/guides/ui.md +11 -1092
  186. package/dist/docs/guides/upgrading.md +2 -0
  187. package/dist/docs/guides/validators.md +2 -0
  188. package/dist/docs/guides/waiting-room.md +1 -1
  189. package/dist/docs/index.md +2 -1
  190. package/dist/docs/page-index.md +146 -0
  191. package/dist/docs/recipes/adapt-a-game-for-walkthroughs.md +1 -1
  192. package/dist/docs/recipes/adapt-ui-for-observers.md +1 -1
  193. package/dist/docs/recipes/create-presentation.md +11 -0
  194. package/dist/docs/recipes/create-scenario-editor.md +1 -0
  195. package/dist/docs/recipes/create-session-ui.md +2 -1
  196. package/dist/docs/recipes/create-setup.md +1 -0
  197. package/dist/docs/recipes/create-user-interface.md +1 -0
  198. package/dist/docs/recipes/create-waiting-room-ui.md +1 -0
  199. package/dist/docs/recipes/design-state-for-concurrent-writes.md +1 -1
  200. package/dist/docs/recipes/e2e-testing.md +19 -20
  201. package/dist/docs/recipes/fix-duplicate-packages.md +2 -2
  202. package/dist/docs/recipes/index.md +3 -0
  203. package/dist/docs/recipes/screenshot-a-surface.md +80 -0
  204. package/dist/docs/recipes/test-a-multi-role-game.md +1 -1
  205. package/dist/docs/recipes/use-request-tick.md +2 -2
  206. package/dist/execution/config-resolver.d.ts +4 -1
  207. package/dist/playwright.js +32232 -0
  208. package/dist/runtime/manifest-version.d.ts +1 -1
  209. package/dist/runtime.js +1 -1
  210. package/dist/templates/package/CLAUDE.md.template +14 -5
  211. package/dist/templates/package/DESIGN.md.liquid +39 -7
  212. package/dist/templates/package/README.md.liquid +1 -1
  213. package/dist/templates/package/claude/rules/workflow-create-user-interface.md +1 -1
  214. package/dist/templates/package/claude/rules/workflow-test-engine-or-ui.md +1 -1
  215. package/dist/templates/package/global-setup.ts.template +7 -18
  216. package/dist/templates/package/playwright.config.ts.liquid +8 -11
  217. package/dist/templates/package/pnpm-workspace.yaml.template +13 -0
  218. package/dist/templates/starter-game/capabilities/pacing/capability.sdk.json +18 -0
  219. package/dist/templates/starter-game/package.json +2 -0
  220. package/dist/templates/starter-game/playwright.config.ts +8 -11
  221. package/dist/templates/starter-game/presentation/defaults.ts +52 -0
  222. package/dist/templates/starter-game/presentation/index.html +20 -0
  223. package/dist/templates/starter-game/presentation/presentation.sdk.json +10 -0
  224. package/dist/templates/starter-game/presentation/src/App.tsx +55 -0
  225. package/dist/templates/starter-game/presentation/src/Band.tsx +40 -0
  226. package/dist/templates/starter-game/presentation/src/Slides.tsx +415 -0
  227. package/dist/templates/starter-game/presentation/src/WeatherIcon.tsx +21 -0
  228. package/dist/templates/starter-game/presentation/src/i18n.ts +88 -0
  229. package/dist/templates/starter-game/presentation/src/main.tsx +15 -0
  230. package/dist/templates/starter-game/presentation/src/stalls.test.ts +196 -0
  231. package/dist/templates/starter-game/presentation/src/stalls.ts +199 -0
  232. package/dist/templates/starter-game/presentation/types.ts +94 -0
  233. package/dist/templates/starter-game/seriousgaming.sdk.json +2 -1
  234. package/dist/templates/starter-game/session/defaults.ts +6 -0
  235. package/dist/templates/starter-game/session/index.html +1 -1
  236. package/dist/templates/starter-game/session/session.sdk.json +2 -2
  237. package/dist/templates/starter-game/session/src/App.test.tsx +436 -115
  238. package/dist/templates/starter-game/session/src/App.tsx +372 -222
  239. package/dist/templates/starter-game/session/src/JoinCodes.tsx +184 -0
  240. package/dist/templates/starter-game/session/src/ManagePanel.tsx +188 -0
  241. package/dist/templates/starter-game/session/src/Results.tsx +340 -0
  242. package/dist/templates/starter-game/session/src/SessionBar.tsx +179 -0
  243. package/dist/templates/starter-game/session/src/SessionPanels.tsx +105 -0
  244. package/dist/templates/starter-game/session/src/SidePanel.tsx +89 -0
  245. package/dist/templates/starter-game/session/src/StallCard.tsx +253 -0
  246. package/dist/templates/starter-game/session/src/TopBar.tsx +36 -0
  247. package/dist/templates/starter-game/session/src/i18n.ts +91 -24
  248. package/dist/templates/starter-game/session/src/status.ts +28 -0
  249. package/dist/templates/starter-game/session/types.ts +8 -2
  250. package/dist/templates/starter-game/shared/Awning.tsx +31 -0
  251. package/dist/templates/starter-game/shared/HostLogo.test.tsx +38 -0
  252. package/dist/templates/starter-game/shared/HostLogo.tsx +48 -0
  253. package/dist/templates/starter-game/shared/StallIcons.tsx +83 -0
  254. package/dist/templates/starter-game/shared/days.ts +11 -0
  255. package/dist/templates/starter-game/shared/format.test.ts +13 -0
  256. package/dist/templates/starter-game/{ui/src → shared}/format.ts +1 -1
  257. package/dist/templates/starter-game/testing/e2e/game.spec.ts +43 -9
  258. package/dist/templates/starter-game/testing/e2e/global-setup.ts +7 -18
  259. package/dist/templates/starter-game/ui/defaults.ts +3 -0
  260. package/dist/templates/starter-game/ui/src/App.test.tsx +197 -29
  261. package/dist/templates/starter-game/ui/src/App.tsx +176 -99
  262. package/dist/templates/starter-game/ui/src/DayBar.test.tsx +50 -7
  263. package/dist/templates/starter-game/ui/src/DayBar.tsx +96 -38
  264. package/dist/templates/starter-game/ui/src/DaysTable.tsx +69 -0
  265. package/dist/templates/starter-game/ui/src/FirstDay.tsx +37 -0
  266. package/dist/templates/starter-game/ui/src/Header.tsx +257 -0
  267. package/dist/templates/starter-game/ui/src/Lesson.tsx +63 -0
  268. package/dist/templates/starter-game/ui/src/MakeRow.tsx +98 -71
  269. package/dist/templates/starter-game/ui/src/Notices.tsx +59 -0
  270. package/dist/templates/starter-game/ui/src/PastDay.tsx +88 -0
  271. package/dist/templates/starter-game/ui/src/Section.tsx +26 -26
  272. package/dist/templates/starter-game/ui/src/ThemeToggle.tsx +25 -11
  273. package/dist/templates/starter-game/ui/src/TodayPanel.test.tsx +37 -33
  274. package/dist/templates/starter-game/ui/src/TodayPanel.tsx +66 -52
  275. package/dist/templates/starter-game/ui/src/WeatherCard.tsx +47 -0
  276. package/dist/templates/starter-game/ui/src/WeekOver.tsx +145 -0
  277. package/dist/templates/starter-game/ui/src/YesterdayPanel.tsx +65 -114
  278. package/dist/templates/starter-game/ui/src/days.ts +58 -0
  279. package/dist/templates/starter-game/ui/src/i18n.ts +86 -32
  280. package/dist/templates/starter-game/ui/src/test-helpers.ts +1 -0
  281. package/dist/templates/starter-game/ui/src/theme.ts +8 -8
  282. package/dist/templates/starter-game/ui/types.ts +6 -0
  283. package/dist/templates/starter-game/ui/ui.sdk.json +1 -1
  284. package/dist/templates/starter-game/validators/daylimit/defaults.ts +13 -0
  285. package/dist/templates/starter-game/validators/daylimit/logic/logic.test.ts +20 -0
  286. package/dist/templates/starter-game/validators/daylimit/logic/logic.ts +23 -0
  287. package/dist/templates/starter-game/validators/daylimit/types.ts +23 -0
  288. package/dist/templates/starter-game/validators/daylimit/validator.sdk.json +10 -0
  289. package/dist/templates/starter-game/waiting_room/src/App.test.tsx +83 -5
  290. package/dist/templates/starter-game/waiting_room/src/App.tsx +262 -119
  291. package/dist/templates/starter-game/waiting_room/src/i18n.ts +8 -4
  292. package/dist/utils/error-codes.d.ts +12 -0
  293. package/dist/utils/prompt.d.ts +5 -5
  294. package/dist/utils/resource-scan.d.ts +39 -0
  295. package/package.json +15 -4
  296. package/dist/templates/starter-game/session/src/Section.tsx +0 -37
  297. package/dist/templates/starter-game/session/src/TeamDoor.tsx +0 -96
  298. package/dist/templates/starter-game/session/src/format.ts +0 -8
  299. package/dist/templates/starter-game/ui/src/HistoryPanel.test.tsx +0 -74
  300. package/dist/templates/starter-game/ui/src/HistoryPanel.tsx +0 -120
  301. package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +0 -25
  302. package/dist/templates/starter-game/ui/src/HostLogo.tsx +0 -38
@@ -0,0 +1,133 @@
1
+ # Designing screens
2
+
3
+ What a good simulation screen looks like, whatever the brand: how to decide what a screen should be before you build it, and how to check it afterwards.
4
+
5
+ **Keywords:** UI design, UX, screen design, dialog, backdrop, side panel, icons, Material Symbols, screen brief, layout, visual hierarchy, primary action, spacing, type scale, density, mobile, phone, projector, empty state, loading state, error state, feedback, accessibility, contrast, focus, keyboard, right-to-left, identity, look and feel, design review
6
+
7
+ This page is about standards and habits, not a house style. Publishers build for their own brands, so nothing here asks a game to look a particular way. It asks each screen to be clear about what it is for, to work on the device it is used on, and to handle every state it can be in. For the mechanics of building a surface, see [Building user interfaces](./ui.md); for the host's colours, logo and fonts, see [Theming and branding](./theming-and-branding.md).
8
+
9
+ ## Start with a brief
10
+
11
+ Write the screen's brief before you write its code. A few lines in `DESIGN.md` are enough:
12
+
13
+ - **Who uses it, and on what:** a participant on their own phone, a team round one laptop, a facilitator on a laptop that is also on the projector
14
+ - **Its one main action:** the thing the person came to the screen to do
15
+ - **What they need to see to do it:** the two or three numbers or facts the action depends on
16
+ - **Its states:** before play, mid-round, waiting for a tick, after the last round, and when something goes wrong
17
+ - **Its tone:** calm and focused, playful, urgent against a clock
18
+
19
+ A screen without a brief tends to become a dump of every variable the surface reads, laid out in the order the schema lists them. That is the most common reason two games built with the SDK look the same.
20
+
21
+ **Good:** 'Participant, own phone, standing at a stall. Main action: set how many of each item to make. Needs: the forecast and what is left of capacity. Tone: quick and light.'
22
+
23
+ **Weak:** 'Shows the plan, the weather and the results.'
24
+
25
+ ## Design for the room
26
+
27
+ Simulations are played in workshops, so design for the devices the brief names, not the monitor you build on.
28
+
29
+ - **A participant's phone:** one column, the main action reachable with a thumb, nothing that needs hovering. Expect a narrow screen (360 CSS pixels wide is common), patchy attention, and someone talking to them while they use it
30
+ - **A team's shared laptop:** room for two columns, but several people read it at once from further away, so keep text larger than you would for one reader
31
+ - **The facilitator's laptop:** dense is fine, because they are fluent in it by the second round. Group by what they do (watch, intervene, move the session on) rather than by data source
32
+ - **A projector:** large type, high contrast, little on screen at once. Assume the back of the room is five metres away and the projector washes out pale colours. A presentation is always projected; a session screen often is
33
+
34
+ Every surface also runs inside the host's frame, under the host's own bar. A dialog with a backdrop darkens only the frame and looks broken, so show detail in a side panel, ask 'are you sure?' beside the button that asked, and go full screen for what the room looks at. See [Avoid dialogs with a backdrop](./session.md#avoid-dialogs-with-a-backdrop).
35
+
36
+ Size to the container rather than the viewport, as [Sizing to the viewport on mobile](./ui-styling.md#sizing-to-the-viewport-on-mobile) explains, and never rely on a fixed width.
37
+
38
+ ## Hierarchy
39
+
40
+ Each screen has one primary action, and the most important number or decision sits where the eye lands first.
41
+
42
+ - **One primary button.** Style the main action as the primary button and everything else as secondary or text. Two filled buttons side by side make the person choose which one matters
43
+ - **Lead with the decision or the outcome.** On a decision screen, the inputs and what limits them come first. On a results screen, the one figure that tells the team how they did comes first, with the breakdown underneath
44
+ - **Group, then label.** Put related things together and give the group a heading, rather than labelling every field
45
+ - **Cut before you shrink.** If a screen will not fit a phone, move the secondary detail behind a tab or a disclosure rather than making everything smaller
46
+
47
+ **Good:** a large 'Profit today' figure, then a short table of what sold, then a link to every past day.
48
+
49
+ **Weak:** six cards of equal size and weight, one per capability.
50
+
51
+ ## Rhythm
52
+
53
+ Consistent spacing and type make a screen feel finished, whatever the colours.
54
+
55
+ - **A spacing scale.** Pick a base unit (8px is common, and MUI's `theme.spacing` is built on it) and use multiples of it. Tight spacing inside a group, more between groups
56
+ - **A type scale.** Three or four sizes are enough: a heading, a sub-heading, body, and small print. Use weight and colour for emphasis before adding a size
57
+ - **Density suited to the device.** Generous padding and large touch targets on a phone; tighter tables on the facilitator's laptop
58
+ - **Numbers that line up.** Right-align numbers in a table and use tabular figures (`font-variant-numeric: tabular-nums`), so a column reads at a glance and values do not jump as they change
59
+
60
+ ## Every state, designed
61
+
62
+ A simulation screen spends much of its life somewhere other than mid-game. Design each of these on purpose:
63
+
64
+ | State | What the person should see |
65
+ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
66
+ | Empty | What will appear here and when, such as 'Your results appear after the first round', never a blank card or a table of zeros |
67
+ | Loading | A short, quiet indicator in the space the content will fill, so the layout does not jump when it arrives |
68
+ | Before play | What the game is and what to do first. `completedTicks` is 0 |
69
+ | Mid-game | The decision for this round, and what last round caused |
70
+ | Waiting | That a round is being processed, and that nothing is broken. See [Saying a tick is processing](./ui.md#saying-a-tick-is-processing) |
71
+ | End of game | That play is over, the final result, and what to look at for the debrief, rather than live controls that no longer do anything |
72
+ | Error | What went wrong in plain words, and what the person can do about it |
73
+ | Being observed | A facilitator watching a team sees what the team sees. See [Adapt a UI for observers](../recipes/adapt-ui-for-observers.md) |
74
+
75
+ Test each one: a component test can render a surface with `completedTicks` at 0, mid-game and at the last round (see [Testing](./testing.md)).
76
+
77
+ ## Feedback
78
+
79
+ After every action, the person should know whether it worked.
80
+
81
+ - **Show the change where it happened.** The value they changed updates in place; a separate 'saved' message is rarely needed
82
+ - **Report a refused write to the person who made it.** Every `setData` returns a promise that rejects when the host or a validator refuses the write. Route writes through `useMutationReporter` and show the reason beside the control, in the validator's own words. A write that fails silently is a decision the team thinks they made and the game never received
83
+ - **Say what a tick will do before it happens.** A button that ends the round says so ('Open the stall', 'Submit for round 3'), and disables itself while the request is in flight
84
+ - **Never punish a slow network.** Keep the person's input while a write is pending, and offer to try again on a conflict rather than discarding what they typed
85
+
86
+ **Good:** 'The stall can only make 120 things a day. Take some off another item first.' beside the slider that was moved.
87
+
88
+ **Weak:** a red toast reading 'Error 409' that disappears after two seconds.
89
+
90
+ ## Accessibility
91
+
92
+ Workshops include people with low vision, colour blindness, a keyboard instead of a mouse, and a right-to-left language. Building for them makes the screen clearer for everyone.
93
+
94
+ - **Contrast.** Body text at least 4.5:1 against its background, large text 3:1. The host's colour roles come with a `contrastText` that meets this, so put text on a role colour in its `contrastText`
95
+ - **Colour is never the only signal.** Pair red and green with a word, a sign or an icon: 'Down 12%' rather than a red number
96
+ - **Focus order follows reading order.** Tab through the screen and check the focus visits controls in the order a person reads them, and is always visible
97
+ - **Everything works from the keyboard.** Every control reachable and usable without a mouse, including sliders and custom toggles
98
+ - **Touch targets.** At least 44 by 44 CSS pixels on a phone, with space between them
99
+ - **Labels.** Every input has a visible label, and every icon-only button has an accessible name
100
+ - **Right-to-left.** In a right-to-left locale the layout mirrors. Use logical CSS properties (`margin-inline-start`, `inset-inline-end`) rather than left and right, and let the wrapper set `dir`. See [Internationalisation](./internationalization.md)
101
+ - **Motion.** Keep animation short and purposeful, and respect `prefers-reduced-motion`
102
+
103
+ ## Identity
104
+
105
+ Two games on one host share its colours, logo and fonts, so the host's theme alone will make them look alike. Give each game an identity of its own on top of the host's theme, without replacing it.
106
+
107
+ - **Keep the host's layer.** Use `createSurfaceTheme` for the palette and fonts, and show the host's logo where your layout has room (see [Theming and branding](./theming-and-branding.md)). A white-label host's clients expect to see their brand
108
+ - **Add an accent layer.** Shape, corner radius, borders, the weight of headings, and the way cards and tables are drawn are the game's to choose, and they change the feel more than colour does
109
+ - **Draw from the game's world.** Iconography, illustration and imagery from the setting: a weather icon on a stall's forecast, a floor plan in a factory game, a map in a logistics game. One strong motif used consistently beats many small decorations
110
+ - **Take icons from an icon set.** Material Symbols, through `@mui/icons-material` (a dependency of every new game), covers weather, food, money, people and most actions. Icons drawn one at a time rarely match each other in weight and size; keep your own drawing for the one motif that makes the game recognisable
111
+ - **Name things in the game's language.** 'Open the stall' rather than 'Submit', 'Stall' rather than 'Team' where the setting supports it
112
+
113
+ **Good:** the host's primary colour on the main button, weather icons from the icon set on each forecast, and rounded, card-like panels that suit a market stall.
114
+
115
+ **Weak:** the default component library look, unchanged, with the game's name in the top bar as the only sign of which game it is.
116
+
117
+ ## Check it, then go round once more
118
+
119
+ When a screen is built, check it against its brief and this page before calling it done.
120
+
121
+ 1. Open it at phone size (360 by 740) and at laptop size (1280 by 800), and on a projector-sized window for anything the room will see. The browser's device toolbar gives each size; open the surface with `?bare` so the dev console's chrome does not take up the room
122
+ 2. Walk through every state in the table above: before play, mid-game, waiting, end of game, and a refused write
123
+ 3. Tab through it with the keyboard, and switch the dev drawer to dark mode and to another brand
124
+ 4. Ask of each screen: is the main action obvious within two seconds? Is the most important number where the eye lands first? Would two games on this host look different?
125
+ 5. Fix what you found, then go round once more. The second pass catches what the first fix moved
126
+
127
+ ## Related
128
+
129
+ - [Designing a serious game](./designing-a-game.md): what each round should teach and show, before what each screen looks like
130
+ - [Building user interfaces](./ui.md): building the game UI
131
+ - [Building session UIs](./session.md): the facilitator's screen
132
+ - [Theming and branding](./theming-and-branding.md): the host's colours, logo and fonts
133
+ - [Testing](./testing.md): component tests for each state
@@ -2,6 +2,8 @@
2
2
 
3
3
  An endpoint is a named, server-side handler that a caller invokes by identifier: one of the game's own user interfaces, or a caller outside the game, such as a facilitator's AI agent or a platform API, when the endpoint allows it. It is how a caller runs code you wrote: you own the request and response shapes, the runtime validates both, and the handler works strictly within the bounds it declares.
4
4
 
5
+ **Keywords:** endpoint, server-side handler, call from UI, callEndpoint, Handle, Plan, Respond, requestSchema, responseSchema, actions, visibility, external endpoint, scope, LLM from a UI
6
+
5
7
  ## The model
6
8
 
7
9
  ### Why endpoints exist
@@ -2,6 +2,8 @@
2
2
 
3
3
  Test your whole game in-process: no dev server, no browser, and no LLM API key required, because service callbacks are stubbed by default.
4
4
 
5
+ **Keywords:** engine testing, createTestSession, in-process test, test a whole game, Vitest, stubbed callbacks, ticks in tests, test endpoints, test hooks, GameRunner, CI
6
+
5
7
  ## What is createTestSession?
6
8
 
7
9
  `createTestSession` starts the session the dev server runs, inside your test process. Everything a game does is there: `Init` and `Run`, hooks when somebody joins, validators on a participant's write, endpoints, undo, independent teams ticking on their own, the configuration step, and automatic ticks. You drive it with the same commands the console, the CLI and your surfaces send, and read it with the same state `sdk view --full` prints.
@@ -270,10 +272,12 @@ By default the session resolves the game's default scenario when one is declared
270
272
  // A specific scenario (it must be listed in the game's `scenarios`)
271
273
  await createTestSession({ packagePath: PACKAGE_PATH, scenarioId: 'easy_mode' });
272
274
 
273
- // Or opt out of the default scenario and test the settings defaults
275
+ // Or, in a game with no default scenario, test the settings defaults
274
276
  await createTestSession({ packagePath: PACKAGE_PATH, scenarioId: null });
275
277
  ```
276
278
 
279
+ A game that marks a default scenario never runs on none, so `scenarioId: null` is refused for it, naming the default. Pin one of its scenarios instead.
280
+
277
281
  ### The configuration step
278
282
 
279
283
  A game with a `setup` slot starts at its configuration step. `createTestSession` presses Play for you, so a tick has a game to run. Pass `play: false` to test the step itself, then send `updateSettings` (keyed by settings identifier, for example `{ type: 'updateSettings', payload: { engine: { BaseDemand: 200 } } }`) and `play` as the setup screen would. Settings are fixed from Play onwards, so `state().settings` after `play` is what every tick reads.
@@ -4,6 +4,8 @@ The engine is the logic that moves your game forward: it sets up the board, then
4
4
 
5
5
  This guide explains how an engine is shaped and why, then covers everything you write in one.
6
6
 
7
+ **Keywords:** engine, game logic, simulation, Init, Run, tick, reads, writes, settings, return capabilities, deletes, end the game, aggregate engine, randomness, language environment
8
+
7
9
  ## The model
8
10
 
9
11
  A game holds one engine, in the `engine/` slot. It:
@@ -6,6 +6,8 @@ This guide explains the scheme, then covers uploading files at runtime, displayi
6
6
 
7
7
  Common uses include uploading a market research PDF in a decisions UI, displaying it in a results UI, and summarising it with an LLM inside an engine.
8
8
 
9
+ **Keywords:** files, assets, blobs, upload a file, display a file, asset references, asset:, shared:, uploadBlob, useAsset, readBlob, extractText, PDF, images, media types
10
+
9
11
  ## Asset references
10
12
 
11
13
  Every file a game can read is named by a self-describing string:
@@ -188,7 +190,7 @@ const logo = useAssetUrl('asset:shared/logo.svg');
188
190
  return <img src={logo} alt="Logo" />;
189
191
  ```
190
192
 
191
- Outside a component, the surface's `getAssetUrl` callback does the same. To render a file's contents rather than link to it, such as a localised briefing, use `useAsset(reference, { as: 'text' })`, which fetches and reads it (see [Reading an asset's contents](./ui.md#reading-an-assets-contents)).
193
+ Outside a component, the surface's `getAssetUrl` callback does the same. To render a file's contents rather than link to it, such as a localised briefing, use `useAsset(reference, { as: 'text' })`, which fetches and reads it (see [Reading an asset's contents](./ui-files-and-llms.md#reading-an-assets-contents)).
192
194
 
193
195
  ## Reading an asset in an engine
194
196
 
@@ -4,6 +4,8 @@ Shape the game as a whole: how many rounds it runs, how teams form, which langua
4
4
 
5
5
  A package is a game, so all of this lives in the package's own manifest.
6
6
 
7
+ **Keywords:** game, seriousgaming.sdk.json, manifest, maxTicks, rounds, teams, team size, waitingRoom, supportedLocales, game settings, goal-based game, host controls
8
+
7
9
  ## Where the game lives
8
10
 
9
11
  The game is `seriousgaming.sdk.json`: the manifest is the package, and the package is the game.
@@ -98,7 +100,7 @@ which does the same thing, but it is an addition, never a replacement, so a bug
98
100
  in a game's own control cannot leave a facilitator with no way out of
99
101
  configuration.
100
102
 
101
- **Tick controls are the game's own.** There is no built-in next tick button: use the [`requestTick` callback](./ui.md#requesting-a-tick) in a game or session UI to advance the game. The console's dev drawer keeps a developer-only **Tick** button for testing.
103
+ **Tick controls are the game's own.** There is no built-in next tick button: use the [`requestTick` callback](./ui-ticks.md#requesting-a-tick) in a game or session UI to advance the game. The console's dev drawer keeps a developer-only **Tick** button for testing.
102
104
 
103
105
  **Tip**: To finish configuration from inside your own form, call `requestPlay` from your [setup screen](./setup.md). The host's Play control stays alongside it.
104
106
 
@@ -4,6 +4,8 @@ The global settings file lets you store API keys and defaults once, in a single
4
4
 
5
5
  Without it, each new shell needs the keys re-exported, and project-level `.env` files are easy to leak into git. The global file lives outside any project, so it is shared across every game you work on.
6
6
 
7
+ **Keywords:** global settings, config.json, ~/.seriousgaming-sdk, API keys, credentials, SERIOUSGAMING_API_KEY, ElevenLabs key, config set, config get, precedence
8
+
7
9
  ## Location
8
10
 
9
11
  The file lives at:
@@ -4,6 +4,8 @@ A facilitator guide bundles the run-sheet for a simulation into the package itse
4
4
 
5
5
  Guides are content as data, not UI bundles: learning designers author markdown, the host renders it. A game holds one guide; a one-page cheat sheet is a chapter of it.
6
6
 
7
+ **Keywords:** facilitator guide, run-sheet, markdown chapters, guide content, admonitions, video embed, YouTube, print, localised guide, ::::when, scenario-aware guide
8
+
7
9
  ## Resource shape
8
10
 
9
11
  ```
@@ -2,6 +2,8 @@
2
2
 
3
3
  A hook is logic that runs when the runtime emits a lifecycle signal, such as a participant joining a team. It runs outside the tick loop, after the runtime has applied the change, and can write the capabilities it declares.
4
4
 
5
+ **Keywords:** hook, lifecycle signal, participantJoin, participantMove, participant joins, outside the tick loop, event handler, signals, hook order, new hook
6
+
5
7
  ## The model
6
8
 
7
9
  The engine runs inside the tick loop: it takes a context, returns what it writes, and does so only when the loop ticks. That fits everything shaped like 'every tick, do X', but not what happens between ticks, such as a participant joining or a facilitator moving someone to another team. There is no tick boundary to bind engine logic to, so an engine either misses those events or has to poll for them.
@@ -4,6 +4,8 @@ Each guide is the one page for a resource kind or a topic: it explains the model
4
4
 
5
5
  New to the SDK? Start with [Designing a serious game](./designing-a-game.md), for what to build, and [A tour of the starter game](./starter-game.md), for every file `new package` gives you and which guide goes deeper.
6
6
 
7
+ **Keywords:** guides, guide list, reference, resource kinds, topics, where to start, all guides
8
+
7
9
  ## The game and its logic
8
10
 
9
11
  - **[Common patterns](./patterns.md)**: inventory, revenue and multi-step engine patterns, with the commands and code for each
@@ -21,8 +23,15 @@ New to the SDK? Start with [Designing a serious game](./designing-a-game.md), fo
21
23
 
22
24
  ## User interfaces
23
25
 
26
+ - **[Designing screens](./designing-screens.md)**: what a good simulation screen looks like whatever the brand, the brief to write first, and the check to run after
24
27
  - **[Building user interfaces](./ui.md)**: the game UI each participant plays
28
+ - **[Participants and teams in user interfaces](./ui-participants.md)**: the current participant, observers, walkthroughs, joining, and renaming
29
+ - **[Ticks and the timer in user interfaces](./ui-ticks.md)**: requesting a tick, awaiting a write, and the countdown
30
+ - **[Styling and building user interfaces](./ui-styling.md)**: language, theme, mobile viewports, and customising Vite
31
+ - **[Files and LLMs in user interfaces](./ui-files-and-llms.md)**: static assets, file uploads, and a chat through an endpoint
25
32
  - **[Building session UIs](./session.md)**: the facilitator's whole-session screen
33
+ - **[Running the game from a session UI](./session-game-flow.md)**: ticks, the timer, host overlays, undo, the waiting room, and the roster
34
+ - **[Session UI hooks reference](./session-hooks.md)**: every session UI hook and the messages the host sends
26
35
  - **[Building a setup screen](./setup.md)**: the short form a facilitator fills in at session creation
27
36
  - **[Building a scenario editor](./scenario-editor.md)**: the screen for authoring lasting scenarios, and when a game needs one
28
37
  - **[Building waiting room UIs](./waiting-room.md)**: the holding screen participants see while the session is held
@@ -2,6 +2,8 @@
2
2
 
3
3
  Run your game in more than one language: declare the locales it supports, then translate its screens, scenario content, dates, and numbers.
4
4
 
5
+ **Keywords:** internationalisation, i18n, localisation, translation, languages, locale, supportedLocales, react-i18next, useTranslation, multilingual, date and number formatting, Intl
6
+
5
7
  ## Game localisation
6
8
 
7
9
  Add a language to a game by patching its manifest:
@@ -4,6 +4,8 @@ Use generated text to give teams feedback, play characters, or write round repor
4
4
 
5
5
  Text is generated through the Serious Gaming platform's LLM pipeline, the same `generateText` path production game code runs, so you configure no provider credentials: all you need is a platform API key. This guide covers setup, usage, and best practices.
6
6
 
7
+ **Keywords:** LLM, AI, generateText, getText, generated text, tiers, quick, standard, expert, platform API key, SERIOUSGAMING_API_KEY, uses, tool use, JSON responses, prompts
8
+
7
9
  ## Overview
8
10
 
9
11
  LLM integration allows you to:
@@ -496,7 +498,7 @@ Declare the endpoint in the UI bundle's `endpoints` array. The endpoint validate
496
498
 
497
499
  Engines and endpoints receive the session locale as `meta.locale`, so either can ask the model to answer in the session's language on its own. When a UI needs its own localised system prompt, translate it in the UI and pass it to the endpoint in the request.
498
500
 
499
- The [user interfaces guide](./ui.md#using-llms-in-user-interfaces) carries the UI half in full: a chat component that persists its conversation in a capability, localised prompts, markdown rendering, and error handling. To build the endpoint, follow [Create an endpoint](../recipes/create-endpoint.md), and see [Call an endpoint from a UI](../recipes/call-endpoint-from-ui.md) for the call itself.
501
+ The [user interfaces guide](./ui-files-and-llms.md#using-llms-in-user-interfaces) carries the UI half in full: a chat component that persists its conversation in a capability, localised prompts, markdown rendering, and error handling. To build the endpoint, follow [Create an endpoint](../recipes/create-endpoint.md), and see [Call an endpoint from a UI](../recipes/call-endpoint-from-ui.md) for the call itself.
500
502
 
501
503
  ## Best practices
502
504
 
@@ -618,7 +620,7 @@ export const Run: RunFunction = async ({ context, callbacks }) => {
618
620
 
619
621
  - [The CLI and the dev server](../cli-and-dev-server.md): what the dev server is and how to drive it
620
622
  - [Environment variables](../environment-variables.md): full env-var reference (LLM, TTS, publishing)
621
- - [User interfaces guide](./ui.md#using-llms-in-user-interfaces): building LLM-powered UIs through endpoints
623
+ - [User interfaces guide](./ui-files-and-llms.md#using-llms-in-user-interfaces): building LLM-powered UIs through endpoints
622
624
  - [Call an endpoint from a UI](../recipes/call-endpoint-from-ui.md): how a UI reaches LLM, document, and speech services
623
625
  - [Engine development](./engine.md): engine creation and patterns
624
626
  - [Service callbacks in tests](./engine-testing.md#service-callbacks-are-stubbed): the offline `generateText` stub, and choosing its answer in a test
@@ -4,6 +4,8 @@ Let teams compete for one market, cooperate on a shared goal, or each play their
4
4
 
5
5
  This guide covers play modes, shared capabilities, an aggregate engine, team composition, and how to run multi-team games in the dev server and from the CLI.
6
6
 
7
+ **Keywords:** multi-team, teams, independent mode, shared-state mode, competition, cooperation, shared capabilities, aggregate engine, team composition, team names, interaction mode
8
+
7
9
  ## Play modes
8
10
 
9
11
  Every multi-team game operates in one of two **interaction modes**. The mode is a fixed property of the game definition: the author chooses it once, and facilitators and participants never select it. This keeps a structural, technical concern out of the hands of everyone downstream of authoring.
@@ -67,7 +69,7 @@ All fields are optional, and each is enforced differently. Every field but `mode
67
69
 
68
70
  ### Naming teams
69
71
 
70
- Every team carries a platform-assigned, session-stable, zero-based `index`. Team ids are `team-${index + 1}`, so the team with index 0 is `team-1`. The index never renumbers: removing a team leaves a gap in the `team-N` sequence, and a later-added team takes the lowest unused index. That team is a new one with the default name: nothing of the removed team comes back with it. Only an empty team in an independent-mode session can be removed (see [Deleting a team](./session.md#deleting-a-team)).
72
+ Every team carries a platform-assigned, session-stable, zero-based `index`. Team ids are `team-${index + 1}`, so the team with index 0 is `team-1`. The index never renumbers: removing a team leaves a gap in the `team-N` sequence, and a later-added team takes the lowest unused index. That team is a new one with the default name: nothing of the removed team comes back with it. Only an empty team in an independent-mode session can be removed (see [Deleting a team](./session-game-flow.md#deleting-a-team)).
71
73
 
72
74
  By default teams are shown as 'Team 1', 'Team 2', and so on. To give them meaningful default names (for example a game where each team is a predefined brand), declare `teams.defaultNames`: an ordered, localised list applied by index, so entry N names the team with index N.
73
75
 
@@ -4,6 +4,8 @@ Three patterns for an engine's state and logic, each built up from the CLI comma
4
4
 
5
5
  For the shape of a whole game, start from the starter game `new package` gives you: [A tour of the starter game](./starter-game.md) walks through it, and [Design state for concurrent writes](../recipes/design-state-for-concurrent-writes.md) states the rules it follows on their own.
6
6
 
7
+ **Keywords:** patterns, examples, inventory, stock, pricing, revenue, multi-step engine, state management, engine examples, best practices
8
+
7
9
  ## Basic inventory system
8
10
 
9
11
  A simple system that tracks stock and prevents negative inventory.
@@ -162,7 +162,7 @@ Use the light palette whatever mode the facilitator's screen is in: slides are m
162
162
 
163
163
  ## Opening from the session UI
164
164
 
165
- A session UI that owns the whole canvas can open the deck for the facilitator with `openHostOverlay('presentation')`, once the game lists `presentation-overlay` in `requires`. The host opens it in its own chrome, usually in a window of its own that the facilitator can put on the projector. See [Opening host overlays](./session.md#opening-host-overlays).
165
+ A session UI that owns the whole canvas can open the deck for the facilitator with `openHostOverlay('presentation')`, once the game lists `presentation-overlay` in `requires`. The host opens it in its own chrome, usually in a window of its own that the facilitator can put on the projector. See [Opening host overlays](./session-game-flow.md#opening-host-overlays).
166
166
 
167
167
  ## Coming back to where you were
168
168
 
@@ -4,6 +4,8 @@ In production your UI bundle runs cross-origin, behind a strict content security
4
4
 
5
5
  The dev server mirrors this policy, so a UI that works locally will work in production. This guide explains the constraints and the things to do and avoid so you never ship a UI that passes locally and breaks live.
6
6
 
7
+ **Keywords:** production, security, content security policy, CSP, iframe, cross-origin, cookies, sandbox, what a UI may do, works locally fails live, caching
8
+
7
9
  ## The two-origin model
8
10
 
9
11
  The platform serves the app and your content from two separate domains:
@@ -4,6 +4,8 @@ The `scenario_editor` slot holds the screen people use to build new scenarios fo
4
4
 
5
5
  It works at any time, with no session, and what it produces is a lasting scenario. This guide covers creating one, what it may and may not do, and when you need one at all.
6
6
 
7
+ **Keywords:** scenario editor, scenario_editor, build scenarios, author scenarios, custom scenarios, configures, settings editor, useSettingsEditor, lasting scenario
8
+
7
9
  ## What the scenario editor is
8
10
 
9
11
  A game holds at most one scenario editor, at `scenario_editor/`. It is a slot, like `session` or `setup`, so it carries no name of its own: the slot is its identifier.
@@ -4,6 +4,8 @@ A scenario is a named set of settings overrides and static assets that makes a d
4
4
 
5
5
  This guide explains the model, then covers creating, running, and authoring scenarios.
6
6
 
7
+ **Keywords:** scenario, scenarios, game variant, flavour, difficulty preset, settings overrides, default scenario, restricted scenario, scenario assets, custom scenarios, scenarioFormat, team names
8
+
7
9
  ## The model
8
10
 
9
11
  Games often ship several variants. A business simulation might have 'Standard', 'AI Disruption', and 'Merger' editions that share one engine and one set of UIs but differ in starting values, narrative text, and media. Without scenarios each variant is either a separate game, duplicating everything, or a manual configuration exercise for the facilitator.
@@ -20,7 +22,7 @@ The facilitator picks a scenario when the session starts, and the game runs with
20
22
  - **Data-only.** Scenarios carry no logic. They override settings values that the engine, hooks, validators, and UIs already interpret. For different behaviour, put conditional logic in the engine and drive it through settings
21
23
  - **Fixed for the session.** A scenario's overrides reach the game through `Init`, so switching scenario means starting again from tick 0
22
24
  - **Optional.** Games work without scenarios
23
- - **One may be the default.** A scenario can mark itself `default: true`, and it is used whenever none is chosen
25
+ - **One may be the default.** A scenario can mark itself `default: true`, and it is used whenever none is chosen. A game with a default always runs on a scenario: no session of it runs on the settings defaults alone, so mark one whenever your game does not make sense without its scenario
24
26
  - **One may be restricted.** A scenario marked `restricted: true` is built for one audience rather than every client the package is shared with. The package never names that audience: the runtime hosting the game decides who has been granted it
25
27
  - **The directory is the declaration.** A scenario is available because it exists under `scenarios/`, and nothing references it
26
28
 
@@ -105,7 +107,7 @@ pnpm run sdk update scenario ai_influence --patch '[
105
107
  ]'
106
108
  ```
107
109
 
108
- **Important:** At most one scenario per package may have `"default": true`. If a default is set, it is used automatically when no `--scenario` flag is provided.
110
+ **Important:** At most one scenario per package may have `"default": true`. If a default is set, it is used automatically when no `--scenario` flag is provided, and the game never runs on no scenario: the dev server, `createTestSession` and a hosted runtime all refuse a request for none, naming the default. A custom scenario is still a scenario, whatever it was started from. Without a default, a session may run on no scenario, using the settings defaults alone.
109
111
 
110
112
  A scenario cannot set a setting the game locks with `readOnly`, or a game setting it fixes with `gameSettingsConstraints`: the build refuses it with `SETTINGS_LOCKED`, pointing at the value, even when the value matches the game's own. Remove it from the scenario. See [Lock a setting](./settings.md#lock-a-setting).
111
113
 
@@ -282,6 +284,8 @@ From a terminal, the same thing:
282
284
  pnpm run sdk scenario ai_influence # or `none` for the settings defaults
283
285
  ```
284
286
 
287
+ `none`, and the tab's **None** choice, are only offered when no scenario is the default.
288
+
285
289
  ### Managing scenarios while the server runs
286
290
 
287
291
  The **Scenario** tab is a small manager, and everything it does writes into your