@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.
- package/README.md +4 -4
- package/dist/brands/awkward/brand.json +16 -0
- package/dist/brands/awkward/logo-on-light.svg +4 -0
- package/dist/brands/serious-gaming/brand.json +42 -0
- package/dist/brands/serious-gaming/fonts/OFL-sora.txt +93 -0
- package/dist/brands/serious-gaming/fonts/OFL-work-sans.txt +93 -0
- package/dist/brands/serious-gaming/fonts/sora-latin-400-normal.woff2 +0 -0
- package/dist/brands/serious-gaming/fonts/sora-latin-600-normal.woff2 +0 -0
- package/dist/brands/serious-gaming/fonts/sora-latin-700-normal.woff2 +0 -0
- package/dist/brands/serious-gaming/fonts/work-sans-latin-wght-normal.woff2 +0 -0
- package/dist/brands/serious-gaming/icon.svg +24 -0
- package/dist/brands/serious-gaming/loader-on-dark.svg +25 -0
- package/dist/brands/serious-gaming/loader-on-light.svg +25 -0
- package/dist/brands/serious-gaming/logo-on-dark.svg +38 -0
- package/dist/brands/serious-gaming/logo-on-light.svg +42 -0
- package/dist/cli.js +20003 -5523
- package/dist/client.js +15534 -1134
- package/dist/core/save-scenario.d.ts +25 -0
- package/dist/core/session-endpoints.d.ts +12 -13
- package/dist/core/session-host.d.ts +9 -1
- package/dist/core/session-writes.d.ts +2 -2
- package/dist/core/session.d.ts +9 -1
- package/dist/dev/brand-summary.d.ts +16 -0
- package/dist/dev/brands.d.ts +213 -0
- package/dist/dev/console/assets/icon-CRaj5uhr.svg +24 -0
- package/dist/dev/console/assets/index-q6-lvlN3.css +1 -0
- package/dist/dev/console/assets/index-qxHcu9fJ.js +204 -0
- package/dist/dev/console/assets/sora-latin-400-normal-CRt88UEn.woff2 +0 -0
- package/dist/dev/console/assets/sora-latin-600-normal-Cdg4DaK0.woff2 +0 -0
- package/dist/dev/console/assets/sora-latin-700-normal-9waGdLWo.woff2 +0 -0
- package/dist/dev/console/assets/work-sans-latin-wght-normal-Bl-S9Xys.woff2 +0 -0
- package/dist/dev/console/index.html +3 -1
- package/dist/dev/routes.d.ts +9 -0
- package/dist/dev/shell.d.ts +14 -0
- package/dist/dev/view/batch.d.ts +0 -2
- package/dist/docs/ai-agents.md +75 -0
- package/dist/docs/api/deck.md +38 -0
- package/dist/docs/api/index.md +5 -5
- package/dist/docs/api/sdk-commands.md +1 -1
- package/dist/docs/api/sdk-e2e.md +1 -0
- package/dist/docs/api/sdk-projection.md +1 -0
- package/dist/docs/api/sdk-testing.md +52 -1
- package/dist/docs/api/sdk-tools-client.md +1 -0
- package/dist/docs/api/sdk-ui-testing.md +30 -4
- package/dist/docs/api/sdk-ui.md +166 -0
- package/dist/docs/api/sdk.md +70 -4
- package/dist/docs/changelog.md +64 -6
- package/dist/docs/cli-and-dev-server.md +2 -0
- package/dist/docs/cli-error-codes.md +65 -59
- package/dist/docs/cli-reference.md +84 -45
- package/dist/docs/concepts/index.md +74 -6
- package/dist/docs/concepts/terminology.md +17 -11
- package/dist/docs/getting-started.md +30 -11
- package/dist/docs/guides/ai-facilitation.md +5 -1
- package/dist/docs/guides/capabilities.md +3 -1
- package/dist/docs/guides/designing-a-game.md +85 -0
- package/dist/docs/guides/endpoints.md +57 -13
- package/dist/docs/guides/engine-testing.md +4 -13
- package/dist/docs/guides/engine.md +14 -2
- package/dist/docs/guides/file-handling.md +14 -10
- package/dist/docs/guides/games.md +2 -8
- package/dist/docs/guides/guide.md +64 -3
- package/dist/docs/guides/index.md +3 -4
- package/dist/docs/guides/internationalization.md +8 -14
- package/dist/docs/guides/llm-integration.md +19 -31
- package/dist/docs/guides/multi-team-games.md +9 -14
- package/dist/docs/guides/patterns.md +0 -6
- package/dist/docs/guides/presentation.md +6 -10
- package/dist/docs/guides/production-constraints.md +2 -9
- package/dist/docs/guides/scenario-editor.md +11 -11
- package/dist/docs/guides/scenarios.md +26 -14
- package/dist/docs/guides/session.md +29 -35
- package/dist/docs/guides/settings.md +28 -2
- package/dist/docs/guides/setup.md +2 -7
- package/dist/docs/guides/speech-generation.md +8 -17
- package/dist/docs/guides/starter-game.md +2 -1
- package/dist/docs/guides/testing.md +45 -43
- package/dist/docs/guides/theming-and-branding.md +194 -0
- package/dist/docs/guides/tick-controller.md +8 -4
- package/dist/docs/guides/type-safety.md +8 -6
- package/dist/docs/guides/ui.md +41 -62
- package/dist/docs/guides/upgrading.md +28 -3
- package/dist/docs/guides/validators.md +64 -3
- package/dist/docs/guides/waiting-room.md +3 -10
- package/dist/docs/index.md +40 -10
- package/dist/docs/recipes/adapt-ui-for-observers.md +1 -1
- package/dist/docs/recipes/call-endpoint-from-ui.md +2 -0
- package/dist/docs/recipes/create-capability.md +1 -1
- package/dist/docs/recipes/create-endpoint.md +7 -2
- package/dist/docs/recipes/create-engine.md +1 -1
- package/dist/docs/recipes/create-guide.md +2 -2
- package/dist/docs/recipes/create-hook.md +1 -1
- package/dist/docs/recipes/create-session-ui.md +1 -1
- package/dist/docs/recipes/create-settings.md +1 -1
- package/dist/docs/recipes/create-tick-controller.md +1 -1
- package/dist/docs/recipes/create-user-interface.md +1 -1
- package/dist/docs/recipes/create-validator.md +1 -1
- package/dist/docs/recipes/declare-api-uses.md +2 -2
- package/dist/docs/recipes/design-state-for-concurrent-writes.md +2 -2
- package/dist/docs/recipes/distribute-package.md +3 -3
- package/dist/docs/recipes/e2e-testing.md +11 -9
- package/dist/docs/recipes/index.md +6 -2
- package/dist/docs/recipes/make-a-guide-follow-the-scenario.md +89 -0
- package/dist/docs/recipes/make-an-endpoint-external.md +1 -1
- package/dist/docs/recipes/publish-a-package.md +1 -1
- package/dist/docs/recipes/remember-a-viewers-choice.md +1 -1
- package/dist/docs/recipes/review-a-past-day.md +4 -2
- package/dist/docs/recipes/share-assets-across-scenarios.md +3 -3
- package/dist/docs/recipes/share-logic-between-engine-and-ui.md +1 -1
- package/dist/docs/recipes/test-a-multi-role-game.md +1 -1
- package/dist/docs/recipes/test-user-interface.md +13 -2
- package/dist/docs/recipes/validate-scenarios.md +91 -0
- package/dist/docs/troubleshooting.md +44 -2
- package/dist/execution/blob-inputs.d.ts +7 -2
- package/dist/execution/config-resolver.d.ts +10 -0
- package/dist/execution/endpoint-runner.d.ts +8 -1
- package/dist/execution/executor-callbacks.d.ts +7 -0
- package/dist/execution/executor.d.ts +11 -0
- package/dist/execution/logic-calls.d.ts +8 -1
- package/dist/execution/scenario-gates.d.ts +34 -0
- package/dist/guide/effective-guide.d.ts +20 -0
- package/dist/guide/locale.d.ts +12 -0
- package/dist/guide/settings.d.ts +67 -0
- package/dist/host/host-channel.d.ts +11 -2
- package/dist/host/index.d.ts +7 -1
- package/dist/host/protocol.d.ts +49 -5
- package/dist/host/theme.d.ts +28 -2
- package/dist/host.js +11490 -15
- package/dist/runtime/index.d.ts +1 -1
- package/dist/runtime/manifest-version.d.ts +17 -0
- package/dist/runtime.js +12 -1
- package/dist/schema.json +32 -4
- package/dist/storage/blob-store.d.ts +3 -2
- package/dist/templates/endpoint/logic.test.ts.liquid +19 -1
- package/dist/templates/endpoint/logic.ts.liquid +18 -0
- package/dist/templates/hook/logic.test.ts.liquid +2 -2
- package/dist/templates/package/CLAUDE.md.template +5 -2
- package/dist/templates/package/README.md.liquid +2 -0
- package/dist/templates/package/claude/rules/workflow-create-endpoint.md +5 -4
- package/dist/templates/package/claude/rules/workflow-create-guide.md +1 -0
- package/dist/templates/presentation/src/App.tsx.liquid +5 -11
- package/dist/templates/session/src/App.test.tsx.liquid +2 -4
- package/dist/templates/session/src/theme.ts.liquid +26 -33
- package/dist/templates/settings-editor/src/theme.ts.liquid +13 -18
- package/dist/templates/starter-game/hooks/assignproducts/logic/logic.test.ts +2 -8
- package/dist/templates/starter-game/session/src/App.test.tsx +6 -10
- package/dist/templates/starter-game/session/src/theme.ts +26 -33
- package/dist/templates/starter-game/ui/src/App.tsx +2 -0
- package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +25 -0
- package/dist/templates/starter-game/ui/src/HostLogo.tsx +38 -0
- package/dist/templates/starter-game/ui/src/theme.ts +26 -33
- package/dist/templates/starter-game/validators/capacity/types.ts +2 -0
- package/dist/templates/starter-game/waiting_room/src/theme.ts +26 -33
- package/dist/templates/ui/src/App.test.tsx.liquid +7 -19
- package/dist/templates/ui/src/theme.ts.liquid +26 -33
- package/dist/templates/validator/logic.ts.liquid +4 -0
- package/dist/templates/waiting-room/src/App.test.tsx.liquid +17 -31
- package/dist/templates/waiting-room/src/theme.ts.liquid +26 -33
- package/dist/utils/error-codes.d.ts +15 -3
- package/dist/validation/ajv.d.ts +9 -5
- package/dist/validation/facilitator-guide-validator.d.ts +6 -0
- package/dist/validation/file-settings.d.ts +49 -0
- package/dist/validation/guide-settings-validator.d.ts +26 -0
- package/package.json +6 -5
- 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)
|
|
122
|
-
- [
|
|
123
|
-
- [
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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)
|
|
302
|
-
- [Terminology](../concepts/terminology.md)
|
|
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
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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
|
|
43
|
-
2. **Environment variables
|
|
44
|
-
3. **.env file
|
|
45
|
-
4. **Global settings file
|
|
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
|
|
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)
|
|
632
|
-
- [Environment variables](../environment-variables.md)
|
|
633
|
-
- [User interfaces guide](./ui.md#using-llms-in-user-interfaces)
|
|
634
|
-
- [Call an endpoint from a UI](../recipes/call-endpoint-from-ui.md)
|
|
635
|
-
- [Engine development](./engine.md)
|
|
636
|
-
- [Service callbacks in tests](./engine-testing.md#service-callbacks-are-stubbed)
|
|
637
|
-
- [Declare API uses](../recipes/declare-api-uses.md) -
|
|
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
|
-
|
|
3
|
+
Let teams compete for one market, cooperate on a shared goal, or each play their own copy of the game.
|
|
4
4
|
|
|
5
|
-
|
|
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
|
|
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)
|
|
585
|
-
- [Creating capabilities](./capabilities.md)
|
|
586
|
-
- [Drive a game from the CLI](../cli-simulation-testing.md)
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
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
|
-
|
|
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.
|
|
3
|
+
The `scenario_editor` slot holds the screen people use to build new scenarios for a released game, without rebuilding it.
|
|
4
4
|
|
|
5
|
-
|
|
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
|
|
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
|
-
|
|
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": "
|
|
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.
|
|
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
|
|