@seriousgaming/sdk-tools 1.0.0-alpha.4 → 1.1.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 (165) hide show
  1. package/README.md +4 -4
  2. package/dist/brands/awkward/brand.json +16 -0
  3. package/dist/brands/awkward/logo-on-light.svg +4 -0
  4. package/dist/brands/serious-gaming/brand.json +42 -0
  5. package/dist/brands/serious-gaming/fonts/OFL-sora.txt +93 -0
  6. package/dist/brands/serious-gaming/fonts/OFL-work-sans.txt +93 -0
  7. package/dist/brands/serious-gaming/fonts/sora-latin-400-normal.woff2 +0 -0
  8. package/dist/brands/serious-gaming/fonts/sora-latin-600-normal.woff2 +0 -0
  9. package/dist/brands/serious-gaming/fonts/sora-latin-700-normal.woff2 +0 -0
  10. package/dist/brands/serious-gaming/fonts/work-sans-latin-wght-normal.woff2 +0 -0
  11. package/dist/brands/serious-gaming/icon.svg +24 -0
  12. package/dist/brands/serious-gaming/loader-on-dark.svg +25 -0
  13. package/dist/brands/serious-gaming/loader-on-light.svg +25 -0
  14. package/dist/brands/serious-gaming/logo-on-dark.svg +38 -0
  15. package/dist/brands/serious-gaming/logo-on-light.svg +42 -0
  16. package/dist/cli.js +20003 -5523
  17. package/dist/client.js +15534 -1134
  18. package/dist/core/save-scenario.d.ts +25 -0
  19. package/dist/core/session-endpoints.d.ts +12 -13
  20. package/dist/core/session-host.d.ts +9 -1
  21. package/dist/core/session-writes.d.ts +2 -2
  22. package/dist/core/session.d.ts +9 -1
  23. package/dist/dev/brand-summary.d.ts +16 -0
  24. package/dist/dev/brands.d.ts +213 -0
  25. package/dist/dev/console/assets/icon-CRaj5uhr.svg +24 -0
  26. package/dist/dev/console/assets/index-q6-lvlN3.css +1 -0
  27. package/dist/dev/console/assets/index-qxHcu9fJ.js +204 -0
  28. package/dist/dev/console/assets/sora-latin-400-normal-CRt88UEn.woff2 +0 -0
  29. package/dist/dev/console/assets/sora-latin-600-normal-Cdg4DaK0.woff2 +0 -0
  30. package/dist/dev/console/assets/sora-latin-700-normal-9waGdLWo.woff2 +0 -0
  31. package/dist/dev/console/assets/work-sans-latin-wght-normal-Bl-S9Xys.woff2 +0 -0
  32. package/dist/dev/console/index.html +3 -1
  33. package/dist/dev/routes.d.ts +9 -0
  34. package/dist/dev/shell.d.ts +14 -0
  35. package/dist/dev/view/batch.d.ts +0 -2
  36. package/dist/docs/ai-agents.md +75 -0
  37. package/dist/docs/api/deck.md +38 -0
  38. package/dist/docs/api/index.md +5 -5
  39. package/dist/docs/api/sdk-commands.md +1 -1
  40. package/dist/docs/api/sdk-e2e.md +1 -0
  41. package/dist/docs/api/sdk-projection.md +1 -0
  42. package/dist/docs/api/sdk-testing.md +52 -1
  43. package/dist/docs/api/sdk-tools-client.md +1 -0
  44. package/dist/docs/api/sdk-ui-testing.md +30 -4
  45. package/dist/docs/api/sdk-ui.md +166 -0
  46. package/dist/docs/api/sdk.md +70 -4
  47. package/dist/docs/changelog.md +64 -6
  48. package/dist/docs/cli-and-dev-server.md +2 -0
  49. package/dist/docs/cli-error-codes.md +65 -59
  50. package/dist/docs/cli-reference.md +84 -45
  51. package/dist/docs/concepts/index.md +74 -6
  52. package/dist/docs/concepts/terminology.md +17 -11
  53. package/dist/docs/getting-started.md +30 -11
  54. package/dist/docs/guides/ai-facilitation.md +5 -1
  55. package/dist/docs/guides/capabilities.md +3 -1
  56. package/dist/docs/guides/designing-a-game.md +85 -0
  57. package/dist/docs/guides/endpoints.md +57 -13
  58. package/dist/docs/guides/engine-testing.md +4 -13
  59. package/dist/docs/guides/engine.md +14 -2
  60. package/dist/docs/guides/file-handling.md +14 -10
  61. package/dist/docs/guides/games.md +2 -8
  62. package/dist/docs/guides/guide.md +64 -3
  63. package/dist/docs/guides/index.md +3 -4
  64. package/dist/docs/guides/internationalization.md +8 -14
  65. package/dist/docs/guides/llm-integration.md +19 -31
  66. package/dist/docs/guides/multi-team-games.md +9 -14
  67. package/dist/docs/guides/patterns.md +0 -6
  68. package/dist/docs/guides/presentation.md +6 -10
  69. package/dist/docs/guides/production-constraints.md +2 -9
  70. package/dist/docs/guides/scenario-editor.md +11 -11
  71. package/dist/docs/guides/scenarios.md +26 -14
  72. package/dist/docs/guides/session.md +29 -35
  73. package/dist/docs/guides/settings.md +28 -2
  74. package/dist/docs/guides/setup.md +2 -7
  75. package/dist/docs/guides/speech-generation.md +8 -17
  76. package/dist/docs/guides/starter-game.md +2 -1
  77. package/dist/docs/guides/testing.md +45 -43
  78. package/dist/docs/guides/theming-and-branding.md +194 -0
  79. package/dist/docs/guides/tick-controller.md +8 -4
  80. package/dist/docs/guides/type-safety.md +8 -6
  81. package/dist/docs/guides/ui.md +41 -62
  82. package/dist/docs/guides/upgrading.md +28 -3
  83. package/dist/docs/guides/validators.md +64 -3
  84. package/dist/docs/guides/waiting-room.md +3 -10
  85. package/dist/docs/index.md +40 -10
  86. package/dist/docs/recipes/adapt-ui-for-observers.md +1 -1
  87. package/dist/docs/recipes/call-endpoint-from-ui.md +2 -0
  88. package/dist/docs/recipes/create-capability.md +1 -1
  89. package/dist/docs/recipes/create-endpoint.md +7 -2
  90. package/dist/docs/recipes/create-engine.md +1 -1
  91. package/dist/docs/recipes/create-guide.md +2 -2
  92. package/dist/docs/recipes/create-hook.md +1 -1
  93. package/dist/docs/recipes/create-session-ui.md +1 -1
  94. package/dist/docs/recipes/create-settings.md +1 -1
  95. package/dist/docs/recipes/create-tick-controller.md +1 -1
  96. package/dist/docs/recipes/create-user-interface.md +1 -1
  97. package/dist/docs/recipes/create-validator.md +1 -1
  98. package/dist/docs/recipes/declare-api-uses.md +2 -2
  99. package/dist/docs/recipes/design-state-for-concurrent-writes.md +2 -2
  100. package/dist/docs/recipes/distribute-package.md +3 -3
  101. package/dist/docs/recipes/e2e-testing.md +11 -9
  102. package/dist/docs/recipes/index.md +6 -2
  103. package/dist/docs/recipes/make-a-guide-follow-the-scenario.md +89 -0
  104. package/dist/docs/recipes/make-an-endpoint-external.md +1 -1
  105. package/dist/docs/recipes/publish-a-package.md +1 -1
  106. package/dist/docs/recipes/remember-a-viewers-choice.md +1 -1
  107. package/dist/docs/recipes/review-a-past-day.md +4 -2
  108. package/dist/docs/recipes/share-assets-across-scenarios.md +3 -3
  109. package/dist/docs/recipes/share-logic-between-engine-and-ui.md +1 -1
  110. package/dist/docs/recipes/test-a-multi-role-game.md +1 -1
  111. package/dist/docs/recipes/test-user-interface.md +13 -2
  112. package/dist/docs/recipes/validate-scenarios.md +91 -0
  113. package/dist/docs/troubleshooting.md +44 -2
  114. package/dist/execution/blob-inputs.d.ts +7 -2
  115. package/dist/execution/config-resolver.d.ts +10 -0
  116. package/dist/execution/endpoint-runner.d.ts +8 -1
  117. package/dist/execution/executor-callbacks.d.ts +7 -0
  118. package/dist/execution/executor.d.ts +11 -0
  119. package/dist/execution/logic-calls.d.ts +8 -1
  120. package/dist/execution/scenario-gates.d.ts +34 -0
  121. package/dist/guide/effective-guide.d.ts +20 -0
  122. package/dist/guide/locale.d.ts +12 -0
  123. package/dist/guide/settings.d.ts +67 -0
  124. package/dist/host/host-channel.d.ts +11 -2
  125. package/dist/host/index.d.ts +7 -1
  126. package/dist/host/protocol.d.ts +49 -5
  127. package/dist/host/theme.d.ts +28 -2
  128. package/dist/host.js +11490 -15
  129. package/dist/runtime/index.d.ts +1 -1
  130. package/dist/runtime/manifest-version.d.ts +17 -0
  131. package/dist/runtime.js +12 -1
  132. package/dist/schema.json +32 -4
  133. package/dist/storage/blob-store.d.ts +3 -2
  134. package/dist/templates/endpoint/logic.test.ts.liquid +19 -1
  135. package/dist/templates/endpoint/logic.ts.liquid +18 -0
  136. package/dist/templates/hook/logic.test.ts.liquid +2 -2
  137. package/dist/templates/package/CLAUDE.md.template +5 -2
  138. package/dist/templates/package/README.md.liquid +2 -0
  139. package/dist/templates/package/claude/rules/workflow-create-endpoint.md +5 -4
  140. package/dist/templates/package/claude/rules/workflow-create-guide.md +1 -0
  141. package/dist/templates/presentation/src/App.tsx.liquid +5 -11
  142. package/dist/templates/session/src/App.test.tsx.liquid +2 -4
  143. package/dist/templates/session/src/theme.ts.liquid +26 -33
  144. package/dist/templates/settings-editor/src/theme.ts.liquid +13 -18
  145. package/dist/templates/starter-game/hooks/assignproducts/logic/logic.test.ts +2 -8
  146. package/dist/templates/starter-game/session/src/App.test.tsx +6 -10
  147. package/dist/templates/starter-game/session/src/theme.ts +26 -33
  148. package/dist/templates/starter-game/ui/src/App.tsx +2 -0
  149. package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +25 -0
  150. package/dist/templates/starter-game/ui/src/HostLogo.tsx +38 -0
  151. package/dist/templates/starter-game/ui/src/theme.ts +26 -33
  152. package/dist/templates/starter-game/validators/capacity/types.ts +2 -0
  153. package/dist/templates/starter-game/waiting_room/src/theme.ts +26 -33
  154. package/dist/templates/ui/src/App.test.tsx.liquid +7 -19
  155. package/dist/templates/ui/src/theme.ts.liquid +26 -33
  156. package/dist/templates/validator/logic.ts.liquid +4 -0
  157. package/dist/templates/waiting-room/src/App.test.tsx.liquid +17 -31
  158. package/dist/templates/waiting-room/src/theme.ts.liquid +26 -33
  159. package/dist/utils/error-codes.d.ts +15 -3
  160. package/dist/validation/ajv.d.ts +9 -5
  161. package/dist/validation/facilitator-guide-validator.d.ts +6 -0
  162. package/dist/validation/file-settings.d.ts +49 -0
  163. package/dist/validation/guide-settings-validator.d.ts +26 -0
  164. package/package.json +6 -5
  165. package/dist/dev/console/assets/index-DgFglsnA.js +0 -204
@@ -90,6 +90,66 @@ id: dQw4w9WgXcQ
90
90
 
91
91
  The id must match YouTube's 11-character format. Unknown providers or malformed blocks render as an inert error block, never a passthrough. The dev server renders the embed from `youtube-nocookie.com` in a sandboxed iframe.
92
92
 
93
+ ## Following the scenario's settings
94
+
95
+ A game usually ships more than one scenario, and one guide has to serve them all. Rather than writing around the differences ('the number of weeks depends on the scenario'), a guide can read settings and say exactly what this session does.
96
+
97
+ List the settings resources the guide reads in `guide.sdk.json`, as any other resource does:
98
+
99
+ ```json
100
+ {
101
+ "definition": {
102
+ "locales": { "en": { "name": "Facilitator guide" } },
103
+ "settings": ["engine", "guide"]
104
+ },
105
+ "rootDirectory": "."
106
+ }
107
+ ```
108
+
109
+ Then three things are available in every chapter.
110
+
111
+ **Show a value.** `:setting[engine.totalWeeks]` is replaced by the resolved value: `engine` is the settings resource and `totalWeeks` the property (a nested property is `engine.timing.seconds`). Numbers are formatted for the chapter's language. A value is always plain text, never markdown. It works inside admonitions, so a `:::say` script reads correctly aloud:
112
+
113
+ ```markdown
114
+ :::say
115
+ 'The order is for :setting[engine.totalWeeks] weeks.'
116
+ :::
117
+ ```
118
+
119
+ **Show a block only sometimes.** `:::when` shows its content when its condition holds and nothing otherwise:
120
+
121
+ ```markdown
122
+ :::when{setting="engine.observers"}
123
+ Seat an observer in each team before the first round.
124
+ :::
125
+
126
+ :::when{setting="engine.mode" is="sandbox"}
127
+ Every tool is open from the start.
128
+ :::
129
+
130
+ :::when{setting="engine.changePlan" not}
131
+ Teams have no change plan in this scenario.
132
+ :::
133
+ ```
134
+
135
+ Without `is` the setting must be true or false. With `is` the block shows when the setting equals that value. `not` turns the result round. That is the whole language: there is no 'and' or 'or', so keep conditions few and coarse. A `:::when` cannot sit inside another `:::when`. To put an admonition inside one, give the outer block more colons:
136
+
137
+ ```markdown
138
+ ::::when{setting="engine.observers"}
139
+ :::tip
140
+ Brief your observers before the first round.
141
+ :::
142
+ ::::
143
+ ```
144
+
145
+ **Show a chapter only sometimes.** Wrap a whole chapter, its title included, in one `:::when`. A chapter that has nothing left to show is left out of the guide and its table of contents. If every chapter is left out, the session has no guide.
146
+
147
+ **What decides the values.** The same settings the game itself runs on: the defaults, then the scenario, then anything changed at setup. Read from a game's page before a session, the guide uses the defaults and the scenario chosen to look at.
148
+
149
+ **Content for one scenario.** The guide reads settings, never which scenario is running. For a section only one scenario needs, add a setting the scenario sets, and condition on that. A settings resource only the guide reads keeps it out of what participants are sent. `examples/factory` does this with `guide.Edition`, which its Northwind scenario sets to `northwind` to show a Northwind-only chapter. A copy of the scenario keeps the chapter, because it carries the setting.
150
+
151
+ `pnpm run sdk build --validate-only` fails when a chapter names a settings resource the guide does not list or a property its schema does not have, shows a value that is not a number or text, conditions without `is` on a setting that is not true or false, or uses an `is` value the setting cannot hold. It warns when a listed settings resource is never used, and when a chapter is hidden under the defaults and every scenario.
152
+
93
153
  ## Rendering and safety
94
154
 
95
155
  The renderer is default-deny:
@@ -118,6 +178,7 @@ The scaffold (`pnpm run sdk new guide`) generates a recommended skeleton: a fron
118
178
 
119
179
  ## See also
120
180
 
121
- - [Create a Facilitator Guide](../recipes/create-guide.md) - step-by-step recipe
122
- - [Internationalisation](internationalization.md) - locale rules across the SDK
123
- - [Scenarios](scenarios.md) - the other data-only resource type
181
+ - [Create a Facilitator Guide](../recipes/create-guide.md): step-by-step recipe
182
+ - [Make a guide follow the scenario](../recipes/make-a-guide-follow-the-scenario.md): show settings values and scenario-specific content
183
+ - [Internationalisation](internationalization.md): locale rules across the SDK
184
+ - [Scenarios](scenarios.md): the other data-only resource type
@@ -2,13 +2,11 @@
2
2
 
3
3
  Each guide is the one page for a resource kind or a topic: it explains the model, then serves as the reference, with every field, every option, and the rules behind them. For how the kinds fit together, see the [core concepts](../concepts/index.md); for a single task done step by step, see the [recipes](../recipes/index.md).
4
4
 
5
- ## Start here
6
-
7
- - **[A tour of the starter game](./starter-game.md)**: every directory and file `new package` gives you, and which guide goes deeper
8
- - **[Common patterns](./patterns.md)**: inventory, revenue and multi-step engine patterns, with the commands and code for each
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.
9
6
 
10
7
  ## The game and its logic
11
8
 
9
+ - **[Common patterns](./patterns.md)**: inventory, revenue and multi-step engine patterns, with the commands and code for each
12
10
  - **[Shaping games](./games.md)**: ticks, teams, locales, and the rest of `seriousgaming.sdk.json`
13
11
  - **[Creating capabilities](./capabilities.md)**: defining the game's state
14
12
  - **[Creating engines](./engine.md)**: the tick logic
@@ -28,6 +26,7 @@ Each guide is the one page for a resource kind or a topic: it explains the model
28
26
  - **[Building a setup screen](./setup.md)**: the short form a facilitator fills in at session creation
29
27
  - **[Building a scenario editor](./scenario-editor.md)**: the screen for authoring lasting scenarios, and when a game needs one
30
28
  - **[Building waiting room UIs](./waiting-room.md)**: the holding screen participants see while the session is held
29
+ - **[Theming and branding](./theming-and-branding.md)**: the host's colours, logo and fonts, the loading screen, and previewing a game in another brand
31
30
  - **[Production security constraints](./production-constraints.md)**: the sandbox and content security policy your UIs run under in production
32
31
  - **[Internationalisation (i18n)](./internationalization.md)**: running a game in more than one language
33
32
 
@@ -1,12 +1,6 @@
1
1
  # Internationalisation (i18n)
2
2
 
3
- This guide shows you how to add multi-language support to your games.
4
-
5
- ## What you'll learn
6
-
7
- - How to add language support to games
8
- - How to localise user interfaces
9
- - How to use i18next in React components
3
+ Run your game in more than one language: declare the locales it supports, then translate its screens, scenario content, dates, and numbers.
10
4
 
11
5
  ## Game localisation
12
6
 
@@ -258,23 +252,23 @@ function SalesReport({ revenue, date }) {
258
252
 
259
253
  ## Best practices
260
254
 
261
- 1. **Complete translations** - Provide all languages for all strings
255
+ 1. **Complete translations**: provide all languages for all strings
262
256
  - ✅ Every English string has Spanish and French
263
257
  - ❌ Missing translations in some languages
264
258
 
265
- 2. **Consistent naming** - Use dot notation for related strings
259
+ 2. **Consistent naming**: use dot notation for related strings
266
260
  - ✅ `"form.submit"`, `"form.cancel"`, `"form.error"`
267
261
  - ❌ `"submitButton"`, `"cancelBtn"`, `"errorMessage"`
268
262
 
269
- 3. **Use namespaces** - Organise large translation sets
263
+ 3. **Use namespaces**: organise large translation sets
270
264
  - ✅ `"nav.home"`, `"dashboard.title"`, `"reports.nodata"`
271
265
  - ❌ All strings in one flat object
272
266
 
273
- 4. **Keep UI in sync** - Update translations when UI changes
267
+ 4. **Keep UI in sync**: update translations when UI changes
274
268
  - ✅ Add new keys to all languages immediately
275
269
  - ❌ Forget to translate new features
276
270
 
277
- 5. **Test all languages** - Switch locale in dev server to test
271
+ 5. **Test all languages**: switch locale in dev server to test
278
272
  - ✅ Verify text displays correctly in each language
279
273
  - ❌ Only test in English
280
274
 
@@ -298,5 +292,5 @@ pnpm run sdk update package --patch '[{"op": "replace", "path": "/locales/en/nam
298
292
 
299
293
  ## Next steps
300
294
 
301
- - [Building user interfaces](./ui.md) - Build localised UIs
302
- - [Terminology](../concepts/terminology.md) - The vocabulary these guides use
295
+ - [Building user interfaces](./ui.md): build localised UIs
296
+ - [Terminology](../concepts/terminology.md): the vocabulary these guides use
@@ -1,20 +1,8 @@
1
1
  # LLM integration guide
2
2
 
3
- The Serious Gaming SDK generates text through the Serious Gaming platform's LLM pipeline, the same `generateText` path production game code runs. The engine can generate content dynamically using LLMs without configuring any provider credentials: all you need is a platform API key. This guide covers setup, usage, and best practices.
4
-
5
- ## Table of contents
6
-
7
- - [Overview](#overview)
8
- - [Configuration](#configuration)
9
- - [LLM tiers](#llm-tiers)
10
- - [Response shape](#response-shape)
11
- - [Using LLMs in engines](#using-llms-in-engines)
12
- - [Tool use](#tool-use)
13
- - [Error handling](#error-handling)
14
- - [Declare the APIs a resource uses](#declare-the-apis-a-resource-uses)
15
- - [Using LLMs in user interfaces](#using-llms-in-user-interfaces)
16
- - [Best practices](#best-practices)
17
- - [Limitations](#limitations)
3
+ Use generated text to give teams feedback, play characters, or write round reports that react to what they did.
4
+
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.
18
6
 
19
7
  ## Overview
20
8
 
@@ -39,10 +27,10 @@ The only required setting is a Serious Gaming platform API key. Issue one from y
39
27
 
40
28
  Configuration follows this priority (highest to lowest):
41
29
 
42
- 1. **CLI flags** - Highest priority, override everything
43
- 2. **Environment variables** - Override .env file
44
- 3. **.env file** - Overrides global settings
45
- 4. **Global settings file** - Lowest priority
30
+ 1. **CLI flags**: highest priority, override everything
31
+ 2. **Environment variables**: override .env file
32
+ 3. **.env file**: overrides global settings
33
+ 4. **Global settings file**: lowest priority
46
34
 
47
35
  ### Method 1: global settings (recommended)
48
36
 
@@ -316,10 +304,10 @@ export const Run: RunFunction<Context, Settings> = async ({ context, callbacks }
316
304
 
317
305
  The loop is:
318
306
 
319
- 1. Invoke `generateText({ messages, tools })`.
320
- 2. If `stopReason === 'toolUse'`, run the tool(s) in your own code and build `toolResult` blocks.
321
- 3. Invoke `generateText` again with the prior messages plus the assistant response plus a user message carrying the `toolResult` blocks.
322
- 4. Repeat until `stopReason !== 'toolUse'`.
307
+ 1. Invoke `generateText({ messages, tools })`
308
+ 2. If `stopReason === 'toolUse'`, run the tool(s) in your own code and build `toolResult` blocks
309
+ 3. Invoke `generateText` again with the prior messages plus the assistant response plus a user message carrying the `toolResult` blocks
310
+ 4. Repeat until `stopReason !== 'toolUse'`
323
311
 
324
312
  Always cap iterations: the loop lives in your code and runaway loops are your responsibility.
325
313
 
@@ -390,7 +378,7 @@ Tool handlers run in caller code. The SDK boundary is unchanged: declaring `gene
390
378
 
391
379
  If no platform API key is configured, `generateText` throws: 'generateText needs a Serious Gaming platform API key, and none is configured.' A CLI command whose tick or endpoint call failed this way exits 5 with the code `LLM_NOT_CONFIGURED`, and its hint lists the ways to set a key (see [Configuration](#configuration)). Restart the dev server after setting one.
392
380
 
393
- A 401 response means the key is invalid or has been revoked. A 403 response means the key works but the account that created it does not have access to the platform LLM API. Ask Business Simulations to grant it.
381
+ A 401 response means the key is invalid or has been revoked. A 403 response means the key works but the account that created it does not have access to the platform LLM API. Ask Serious Gaming support to grant it.
394
382
 
395
383
  ### Handling API errors
396
384
 
@@ -628,10 +616,10 @@ export const Run: RunFunction = async ({ context, callbacks }) => {
628
616
 
629
617
  ## See also
630
618
 
631
- - [The CLI and the dev server](../cli-and-dev-server.md) - what the dev server is and how to drive it
632
- - [Environment variables](../environment-variables.md) - Full env-var reference (LLM, TTS, publishing)
633
- - [User interfaces guide](./ui.md#using-llms-in-user-interfaces) - Building LLM-powered UIs through endpoints
634
- - [Call an endpoint from a UI](../recipes/call-endpoint-from-ui.md) - how a UI reaches LLM, document, and speech services
635
- - [Engine development](./engine.md) - Engine creation and patterns
636
- - [Service callbacks in tests](./engine-testing.md#service-callbacks-are-stubbed) - The offline `generateText` stub, and choosing its answer in a test
637
- - [Declare API uses](../recipes/declare-api-uses.md) - Step-by-step `uses` declaration
619
+ - [The CLI and the dev server](../cli-and-dev-server.md): what the dev server is and how to drive it
620
+ - [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
622
+ - [Call an endpoint from a UI](../recipes/call-endpoint-from-ui.md): how a UI reaches LLM, document, and speech services
623
+ - [Engine development](./engine.md): engine creation and patterns
624
+ - [Service callbacks in tests](./engine-testing.md#service-callbacks-are-stubbed): the offline `generateText` stub, and choosing its answer in a test
625
+ - [Declare API uses](../recipes/declare-api-uses.md): step-by-step `uses` declaration
@@ -1,13 +1,8 @@
1
1
  # Multi-team games
2
2
 
3
- This guide explains how to build and test games where multiple teams compete, cooperate, or operate independently. It covers play modes, shared capabilities, an aggregate engine, team composition, and how to run multi-team simulations via the dev server and CLI.
3
+ Let teams compete for one market, cooperate on a shared goal, or each play their own copy of the game.
4
4
 
5
- ## What you'll learn
6
-
7
- - The two interaction modes: **independent** and **shared-state**
8
- - How to declare your game's interaction mode and set team composition constraints
9
- - How to use shared capabilities and an aggregate engine for cross-team interaction
10
- - How to test multi-team games with `--teams N` in the dev server and CLI
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.
11
6
 
12
7
  ## Play modes
13
8
 
@@ -38,9 +33,9 @@ In your `seriousgaming.sdk.json`:
38
33
  }
39
34
  ```
40
35
 
41
- - A game runs in exactly one interaction mode.
42
- - If `teams.mode` is omitted, it defaults to `independent`.
43
- - The mode is fixed at authoring time. If a single game genuinely needs both topologies, ship two game definitions.
36
+ - A game runs in exactly one interaction mode
37
+ - If `teams.mode` is omitted, it defaults to `independent`
38
+ - The mode is fixed at authoring time. If a single game genuinely needs both topologies, ship two game definitions
44
39
 
45
40
  ### Team composition
46
41
 
@@ -456,7 +451,7 @@ Start the dev server with multiple teams:
456
451
  pnpm run sdk dev --teams 3
457
452
  ```
458
453
 
459
- **Auto-derived team count**: If you don't pass `--teams`, the dev server reads `teams.min` from your game. For example, if your game declares `"teams": { "min": 3 }`, running `pnpm run sdk dev` will automatically start with 3 teams. The `--teams` flag always overrides this, but it must sit within the game's bounds: a count below `min` or above `max` is refused, not adjusted.
454
+ **Auto-derived team count**: If you don't pass `--teams`, the dev server reads `teams.min` from your game. For example, if your game declares `"teams": { "min": 3 }`, running `pnpm run sdk dev` will automatically start with three teams. The `--teams` flag always overrides this, but it must sit within the game's bounds: a count below `min` or above `max` is refused, not adjusted.
460
455
 
461
456
  Each team gets its own game UI URL, and the console at `/` is the session UI:
462
457
 
@@ -581,6 +576,6 @@ Shared-state mode: RunAggregate({ shared, teams: [{ teamId: "team-1", index: 0,
581
576
 
582
577
  ## Next steps
583
578
 
584
- - [Creating engines](./engine.md) - Implement engine logic
585
- - [Creating capabilities](./capabilities.md) - Define shared and per-team variables
586
- - [Drive a game from the CLI](../cli-simulation-testing.md) - Play a multi-team session from the terminal with `--team` and `--teams`
579
+ - [Creating engines](./engine.md): implement engine logic
580
+ - [Creating capabilities](./capabilities.md): define shared and per-team variables
581
+ - [Drive a game from the CLI](../cli-simulation-testing.md): play a multi-team session from the terminal with `--team` and `--teams`
@@ -4,12 +4,6 @@ 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
- ## Table of contents
8
-
9
- - [Basic inventory system](#basic-inventory-system)
10
- - [Pricing and revenue](#pricing-and-revenue)
11
- - [Complex state management](#complex-state-management)
12
-
13
7
  ## Basic inventory system
14
8
 
15
9
  A simple system that tracks stock and prevents negative inventory.
@@ -1,16 +1,10 @@
1
1
  # Building presentations
2
2
 
3
- Ship the facilitator's slide deck as part of the game: an introduction, the briefing, a divider before each block of rounds, the debriefs and the results, localised, aware of the scenario, live with the session's results, and exportable for anyone who wants to take it away and edit it.
3
+ Ship the facilitator's slide deck as part of the game, live with the session's results and exportable for anyone who wants to edit it.
4
4
 
5
- **Keywords:** presentation, slides, slide deck, deck, briefing, debrief, results, PowerPoint, PDF, PNG, export, usePresentation, PresentationWrapper, @seriousgaming/deck, Deck, Slide, Step
6
-
7
- ## What you'll learn
5
+ A deck holds the introduction, the briefing, a divider before each block of rounds, the debriefs, and the results. It is localised and aware of the scenario.
8
6
 
9
- - What a presentation is, and what a runtime does with it
10
- - How a deck reads the game and the session, and why `session` can be `null`
11
- - How to build slides with `Deck`, `Slide`, `Step` and the building blocks
12
- - How a deck remembers where the facilitator was
13
- - What export produces, and the habits that keep an export faithful
7
+ **Keywords:** presentation, slides, slide deck, deck, briefing, debrief, results, PowerPoint, PDF, PNG, export, usePresentation, PresentationWrapper, @seriousgaming/deck, Deck, Slide, Step
14
8
 
15
9
  ## What is a presentation?
16
10
 
@@ -22,6 +16,8 @@ Every runtime offers it, so a game can rely on its deck being there for the brie
22
16
  - **Facilitator only.** It is never shown on a participant's or an observer's device. The room sees it because the facilitator shares or projects their screen
23
17
  - **Shown with or without a session.** It is the one surface a runtime shows with no session at all: from a game's page in a library, while a facilitator rehearses, or to export it before the day
24
18
 
19
+ The debrief is where the learning lands, so build it from the session's own results rather than from slides that would read the same for any room.
20
+
25
21
  ## Creating one
26
22
 
27
23
  ```bash
@@ -91,7 +87,7 @@ export function useResults(): Results {
91
87
 
92
88
  ### Varying by scenario
93
89
 
94
- Branch on settings, scenario assets and `game.maxTicks`, never on `game.scenarioName`. A facilitator who saves their own scenario from one of yours gets a new identity, so a deck that branched on the name would show the wrong slides to exactly the facilitators who customised. `scenarioName` is for display.
90
+ Branch on settings, scenario assets and `game.maxTicks`, never on `game.scenarioName`. A facilitator who saves their own scenario from one of yours gets a new identity, so a deck that branched on the name would show the wrong slides to exactly the facilitators who customised. `scenarioName` is for display, as it is everywhere else a game is told it (see [Showing the scenario](./engine.md#showing-the-scenario)).
95
91
 
96
92
  ## Slides
97
93
 
@@ -1,15 +1,8 @@
1
1
  # Production security constraints
2
2
 
3
- In production your UI bundle runs cross-origin, behind a strict content security policy and a short-lived auth cookie, and talks to the host only through a typed message channel. 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.
3
+ In production your UI bundle runs cross-origin, behind a strict content security policy and a short-lived auth cookie, and talks to the host only through a typed message channel.
4
4
 
5
- ## What you'll learn
6
-
7
- - Why your UI is sandboxed in production and what that means in practice
8
- - What your UI is allowed to do inside its frame, and what it is not
9
- - The exact content security policy your bundle runs under
10
- - What to do and what to avoid when building UIs
11
- - How to recognise and fix the most common policy violations
12
- - The write, retry and logic rules that hold beyond the frame
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.
13
6
 
14
7
  ## The two-origin model
15
8
 
@@ -1,14 +1,8 @@
1
1
  # Building a scenario editor
2
2
 
3
- The `scenario_editor` slot holds the screen people use to build new scenarios for a released game, without rebuilding it. 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.
3
+ The `scenario_editor` slot holds the screen people use to build new scenarios for a released game, without rebuilding it.
4
4
 
5
- ## What you'll learn
6
-
7
- - What the scenario editor is for, and how it differs from setup
8
- - When a game needs one, and when descriptive settings schemas are enough
9
- - How to create an editor and choose the settings it edits
10
- - Which endpoints the editor may call, and what they receive
11
- - How saving works in a hosted runtime and in the dev server
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.
12
6
 
13
7
  ## What the scenario editor is
14
8
 
@@ -40,6 +34,9 @@ With it, a hosted runtime persists scenarios authored for the game and lists the
40
34
  - Units in the description or title ('in pounds', 'per tick', 'as a fraction of revenue')
41
35
  - `minimum` and `maximum` (or `exclusiveMinimum` and `exclusiveMaximum`) for ranges
42
36
  - `enum` for a closed set of choices
37
+ - `blob` on a value that holds a file, saying what it takes (see [Settings that hold a file](./settings.md#settings-that-hold-a-file))
38
+
39
+ An agent writing a scenario changes settings and nothing else, so anything you want written per scenario has to be a setting. It works on a draft, uploading any file first and writing its reference, and the scenario gate judges the result when it is saved. To tell it what it cannot work out from the schemas, such as what a round would come to under its draft, give it [scenario-scoped endpoints](./endpoints.md#scenario-scoped-endpoints) marked external (see [Writing scenarios with an agent](./scenarios.md#writing-scenarios-with-an-agent)).
43
40
 
44
41
  ```json
45
42
  "BaseDemand": {
@@ -91,19 +88,22 @@ Two differences:
91
88
 
92
89
  - **No `requestPlay`.** There may be no session to start. The callback exists on `useSettingsEditorCallbacks()`, because one wrapper serves both slots, but the host ignores it from the editor
93
90
  - **No save button of your own.** The host owns saving: it supplies the name, decides where the scenario is stored, and offers the action in its own chrome. The editor only edits values
91
+ - **Show your game's scenario rules as the author edits.** A validator's `Scenario` gate refuses a save that breaks your rules, such as a lowest price above the highest. Import the same rules into the editor and mark each field a problem names, so the author fixes it before saving rather than after (see [Gating scenarios](./validators.md#gating-scenarios))
94
92
 
95
93
  `useSettingsEditorCallbacks()` also gives `uploadBlob`, `getAssetUrl`, `readAsset`, and the `endpoints` the bundle declares. An uploaded `blob:` reference stored in a setting travels with the saved scenario.
96
94
 
97
95
  ## Calling endpoints
98
96
 
99
- The editor has no session, so an endpoint it lists must be session-scoped and declare no `reads`, `writes` or `actions`: there is no game state for it to read, change or act on. The build refuses one that does with `EDITOR_ENDPOINT_STATEFUL`, pointing at the entry in `endpoints`. To use one that needs game state elsewhere, give the editor an endpoint of its own.
97
+ The editor writes a scenario rather than playing one, so it lists [scenario-scoped endpoints](./endpoints.md#scenario-scoped-endpoints) alone: `"scope": "scenario"`, declaring no `reads`, `writes`, `actions` or `roster`. The build refuses any other with `EDITOR_ENDPOINT_NOT_SCENARIO`, pointing at the entry in `endpoints`.
98
+
99
+ Such an endpoint receives its declared `settings`, resolved from the scenario being edited with the editor's unsaved changes over it, so it sees the draft without the editor sending the values in the request. It is handed no `context`, `participants` or `session`, and `caller` is `{ role: 'author', userInterfaceIdentifier: 'scenario_editor' }`. The person editing a scenario may not be a facilitator, so the editor's calls never report `'facilitator'`. A file it makes, through `writeBlob` or `generateSpeech`, belongs to the draft, as the editor's own uploads do.
100
100
 
101
- What such an endpoint receives is its declared `settings`, resolved from the scenario being edited with the editor's unsaved changes over it, so it sees the draft without the editor sending the values in the request. `context` and `participants` are empty, `session` has played nothing and holds no teams, and `caller` is `{ role: 'author', userInterfaceIdentifier: 'scenario_editor' }`, with no `sessionId`. The person editing a scenario may not be a facilitator, so the editor's calls never report `'facilitator'`. See [Calls from the scenario editor](./endpoints.md#calls-from-the-scenario-editor).
101
+ Mark one `"visibility": "external"` and an agent writing a scenario can call it on its draft too, as the same `'author'`.
102
102
 
103
103
  ```json
104
104
  {
105
105
  "definition": {
106
- "scope": "session",
106
+ "scope": "scenario",
107
107
  "settings": ["engine", "ui"],
108
108
  "uses": ["generateText"],
109
109
  "requestSchema": { "type": "object", "properties": {}, "additionalProperties": false },
@@ -1,11 +1,15 @@
1
1
  # Scenarios
2
2
 
3
- A scenario is a named set of settings overrides and static assets that makes a distinct flavour of a game: a different storyline, difficulty preset, or themed variant. This guide explains the model, then covers creating, running, and authoring scenarios.
3
+ A scenario is a named set of settings overrides and static assets that makes a distinct flavour of a game: a different storyline, difficulty preset, or themed variant.
4
+
5
+ This guide explains the model, then covers creating, running, and authoring scenarios.
4
6
 
5
7
  ## The model
6
8
 
7
9
  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.
8
10
 
11
+ The same game can then serve different audiences and learning objectives, or run again for a returning group with a twist.
12
+
9
13
  A scenario packages the differences as one selectable unit. It holds two things:
10
14
 
11
15
  1. **Settings overrides**: values that override the game's [settings](./settings.md) for this variant, keyed by settings identifier
@@ -32,14 +36,6 @@ Use scenarios when:
32
36
 
33
37
  You do not need scenarios if your game has only one variant, if the differences are small enough for a single [setup screen](./setup.md), or if you need to switch variants in the middle of play (a scenario is fixed for the session).
34
38
 
35
- ## What you'll learn
36
-
37
- - How to create a scenario with settings overrides and assets
38
- - How to initialise a game with a specific scenario
39
- - How to load scenario assets in UIs
40
- - How to test scenarios with the dev server and CLI
41
- - When to bump `scenarioFormat` so a saved custom scenario is never applied to a game it no longer fits
42
-
43
39
  ## Prerequisites
44
40
 
45
41
  You need an existing game with at least one engine. If you don't have one:
@@ -427,15 +423,15 @@ When you run `pnpm run sdk build`, scenarios are included in the output:
427
423
 
428
424
  ## Best practices
429
425
 
430
- 1. **Use scenarios for variant bundles, not minor tweaks.** If the difference is a single settings value, a setup screen is simpler.
426
+ 1. **Use scenarios for variant bundles, not minor tweaks.** If the difference is a single settings value, a setup screen is simpler
431
427
 
432
- 2. **Keep scenarios data-only.** Don't put logic in scenarios: use settings to drive conditional behaviour.
428
+ 2. **Keep scenarios data-only.** Don't put logic in scenarios: use settings to drive conditional behaviour
433
429
 
434
- 3. **Organise assets by purpose.** Use `shared/` for locale-independent files. If you need locale-specific assets, use locale subdirectories (e.g. `en/`, `fr/`) and reference the appropriate path from a settings value.
430
+ 3. **Organise assets by purpose.** Use `shared/` for locale-independent files. If you need locale-specific assets, use locale subdirectories (e.g. `en/`, `fr/`) and reference the appropriate path from a settings value
435
431
 
436
- 4. **Mark a default.** If your game has scenarios, mark one as `default: true` so facilitators don't have to remember the identifier.
432
+ 4. **Mark a default.** If your game has scenarios, mark one as `default: true` so facilitators don't have to remember the identifier
437
433
 
438
- 5. **Validate overrides against settings schemas.** Scenario settings values are validated against each named settings resource's `settingsSchema` during build. If a value doesn't match, the build will fail.
434
+ 5. **Validate overrides against settings schemas.** Scenario settings values are validated against each named settings resource's `settingsSchema` during build. If a value doesn't match, the build will fail
439
435
 
440
436
  ## Custom scenarios (production runtimes)
441
437
 
@@ -456,6 +452,21 @@ Save-as-scenario is offered from the game's [`scenario_editor`](./scenario-edito
456
452
 
457
453
  The editor is optional. `customScenarios.supported` is what switches custom scenarios on, and a game whose settings schemas describe each value well (a title, a description with units, a range, an `enum` where the choices are closed) can be edited by an AI agent, or in a runtime's generic form, with no editor UI at all. See [Describe every setting](./settings.md#describe-every-setting).
458
454
 
455
+ A saved scenario keeps every file it references for as long as it exists, whichever route uploaded it.
456
+
457
+ ### Writing scenarios with an agent
458
+
459
+ A platform that lets an agent write scenarios gives it four things, and your game decides what each holds:
460
+
461
+ 1. **The settings schemas**, to know what it may change. Describe every setting, and declare `blob` on each one that holds a file ([Describe every setting](./settings.md#describe-every-setting))
462
+ 2. **The draft's settings to change**, held to the same checks as an editor's edit: the schema, ranges and [locks](./settings.md#lock-a-setting)
463
+ 3. **Uploads to the draft**, for a [setting that holds a file](./settings.md#settings-that-hold-a-file): the agent uploads the file and writes the `blob:` reference it gets back
464
+ 4. **Your external [scenario-scoped endpoints](./endpoints.md#scenario-scoped-endpoints)**, called on the draft, for what it cannot work out from the schemas, such as what a round would come to
465
+
466
+ Endpoints never change the draft; the agent does. A validator's [`Scenario` gate](./validators.md#gating-scenarios) judges the result when the scenario is saved, and its messages are what the agent has to go on, so say what is allowed as well as what is wrong.
467
+
468
+ Try your endpoints the way an agent calls them with `pnpm run sdk endpoint call <identifier> --draft <scenario> --external`. The factory example's `previewround` endpoint is one: it works out a round under the scenario being written with the engine's own maths. In your own source tree a scenario is a file, so a file it holds ships under the scenario's `assets/` and is referenced as `asset:`, which the build checks against the setting's `blob` declaration.
469
+
459
470
  ### Scenario format: when to bump it
460
471
 
461
472
  A custom scenario outlives the release it was saved against: a facilitator saves one today and runs it after your next update. Schema validation catches a setting that was renamed or removed, but not one whose meaning changed, so you tell the runtime with `scenarioFormat` in `seriousgaming.sdk.json`:
@@ -476,6 +487,7 @@ Bump it when a scenario saved against the previous release may no longer be corr
476
487
  - A change in what a value means (a percentage that becomes a fraction, a per-round amount that becomes a total)
477
488
  - A change in how the game loads scenario assets (a reference resolved from a different path)
478
489
  - A lock or a narrower range on a setting a saved scenario may already set: a new `readOnly` in a settings schema, or a new or tighter entry in `gameSettingsConstraints` (see [Lock a setting](./settings.md#lock-a-setting)). A lock is enforced when a value is written, so the format is what stops an older scenario that carries the value from applying
490
+ - A new or stricter `Scenario` gate on a validator (see [Gating scenarios](./validators.md#gating-scenarios)). The gate runs when a scenario is saved, so the format is what stops one saved before the rule from applying
479
491
 
480
492
  Do not bump it for a purely additive change, such as a new setting with a default: an older scenario leaves the new setting at its default and still applies. Bumping when you did not need to costs facilitators their saved scenarios, so bump only for a change that would make an old scenario wrong.
481
493