@seriousgaming/sdk-tools 1.3.0 → 1.5.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/dist/cli.js +4055 -2646
- package/dist/client.js +807 -172
- package/dist/core/session-host.d.ts +4 -2
- package/dist/core/settings-locks.d.ts +27 -2
- package/dist/dev/console/assets/{index-DEV8N0na.js → index-BVF8exas.js} +22 -22
- package/dist/dev/console/index.html +1 -1
- package/dist/dev/public-origins.d.ts +61 -0
- package/dist/dev/routes.d.ts +4 -0
- package/dist/dev/shell.d.ts +32 -4
- package/dist/dev/view/batch.d.ts +7 -1
- package/dist/docs/ai-agents.md +5 -0
- package/dist/docs/api/index.md +1 -1
- package/dist/docs/api/sdk-tools-client.md +1 -0
- package/dist/docs/api/sdk.md +79 -2
- package/dist/docs/changelog-0.x.md +2 -2
- package/dist/docs/changelog.md +62 -4
- package/dist/docs/cli-and-dev-server.md +58 -0
- package/dist/docs/cli-error-codes.md +39 -36
- package/dist/docs/cli-reference.md +68 -21
- package/dist/docs/concepts/terminology.md +1 -1
- package/dist/docs/environment-variables.md +10 -5
- package/dist/docs/guides/ai-facilitation.md +2 -0
- package/dist/docs/guides/capabilities.md +4 -0
- package/dist/docs/guides/designing-a-game.md +2 -0
- package/dist/docs/guides/designing-screens.md +133 -0
- package/dist/docs/guides/endpoints.md +4 -2
- package/dist/docs/guides/engine-testing.md +6 -2
- package/dist/docs/guides/engine.md +2 -0
- package/dist/docs/guides/file-handling.md +116 -22
- package/dist/docs/guides/games.md +3 -1
- package/dist/docs/guides/global-settings.md +2 -0
- package/dist/docs/guides/guide.md +2 -0
- package/dist/docs/guides/hooks.md +2 -0
- package/dist/docs/guides/index.md +9 -0
- package/dist/docs/guides/internationalization.md +2 -0
- package/dist/docs/guides/llm-integration.md +5 -3
- package/dist/docs/guides/multi-team-games.md +3 -1
- package/dist/docs/guides/patterns.md +2 -0
- package/dist/docs/guides/presentation.md +1 -1
- package/dist/docs/guides/production-constraints.md +2 -0
- package/dist/docs/guides/scenario-editor.md +3 -1
- package/dist/docs/guides/scenarios.md +15 -3
- package/dist/docs/guides/session-game-flow.md +365 -0
- package/dist/docs/guides/session-hooks.md +205 -0
- package/dist/docs/guides/session.md +27 -565
- package/dist/docs/guides/settings.md +64 -2
- package/dist/docs/guides/setup.md +3 -1
- package/dist/docs/guides/speech-generation.md +2 -0
- package/dist/docs/guides/starter-game.md +61 -21
- package/dist/docs/guides/testing.md +2 -0
- package/dist/docs/guides/tick-controller.md +3 -1
- package/dist/docs/guides/type-safety.md +2 -0
- package/dist/docs/guides/ui-files-and-llms.md +328 -0
- package/dist/docs/guides/ui-participants.md +281 -0
- package/dist/docs/guides/ui-styling.md +263 -0
- package/dist/docs/guides/ui-ticks.md +247 -0
- package/dist/docs/guides/ui.md +11 -1092
- package/dist/docs/guides/upgrading.md +2 -0
- package/dist/docs/guides/validators.md +64 -4
- package/dist/docs/guides/waiting-room.md +1 -1
- package/dist/docs/index.md +2 -1
- package/dist/docs/page-index.md +145 -0
- package/dist/docs/recipes/adapt-a-game-for-walkthroughs.md +1 -1
- package/dist/docs/recipes/adapt-ui-for-observers.md +1 -1
- package/dist/docs/recipes/create-presentation.md +11 -0
- package/dist/docs/recipes/create-scenario-editor.md +1 -0
- package/dist/docs/recipes/create-session-ui.md +2 -1
- package/dist/docs/recipes/create-setup.md +1 -0
- package/dist/docs/recipes/create-user-interface.md +1 -0
- package/dist/docs/recipes/create-waiting-room-ui.md +1 -0
- package/dist/docs/recipes/design-state-for-concurrent-writes.md +1 -1
- package/dist/docs/recipes/fix-duplicate-packages.md +2 -2
- package/dist/docs/recipes/index.md +3 -0
- package/dist/docs/recipes/screenshot-a-surface.md +80 -0
- package/dist/docs/recipes/test-a-multi-role-game.md +1 -1
- package/dist/docs/recipes/upload-and-display-files.md +7 -7
- package/dist/docs/recipes/use-request-tick.md +2 -2
- package/dist/docs/recipes/validate-scenarios.md +4 -1
- package/dist/execution/config-resolver.d.ts +4 -1
- package/dist/execution/endpoint-runner.d.ts +6 -0
- package/dist/execution/logic-calls.d.ts +7 -2
- package/dist/execution/scenario-gates.d.ts +21 -1
- package/dist/guide/settings.d.ts +1 -1
- package/dist/host.js +64 -2
- package/dist/runtime/manifest-version.d.ts +1 -1
- package/dist/runtime.js +7 -2
- package/dist/storage/asset-resolver.d.ts +24 -1
- package/dist/storage/blob-store.d.ts +7 -0
- package/dist/templates/package/CLAUDE.md.template +14 -5
- package/dist/templates/package/DESIGN.md.liquid +39 -7
- package/dist/templates/package/README.md.liquid +1 -1
- package/dist/templates/package/claude/rules/workflow-create-user-interface.md +1 -1
- package/dist/templates/package/pnpm-workspace.yaml.template +13 -0
- package/dist/templates/starter-game/capabilities/pacing/capability.sdk.json +18 -0
- package/dist/templates/starter-game/package.json +2 -0
- package/dist/templates/starter-game/presentation/defaults.ts +52 -0
- package/dist/templates/starter-game/presentation/index.html +20 -0
- package/dist/templates/starter-game/presentation/presentation.sdk.json +10 -0
- package/dist/templates/starter-game/presentation/src/App.tsx +55 -0
- package/dist/templates/starter-game/presentation/src/Band.tsx +40 -0
- package/dist/templates/starter-game/presentation/src/Slides.tsx +415 -0
- package/dist/templates/starter-game/presentation/src/WeatherIcon.tsx +21 -0
- package/dist/templates/starter-game/presentation/src/i18n.ts +88 -0
- package/dist/templates/starter-game/presentation/src/main.tsx +15 -0
- package/dist/templates/starter-game/presentation/src/stalls.test.ts +196 -0
- package/dist/templates/starter-game/presentation/src/stalls.ts +199 -0
- package/dist/templates/starter-game/presentation/types.ts +94 -0
- package/dist/templates/starter-game/seriousgaming.sdk.json +2 -1
- package/dist/templates/starter-game/session/defaults.ts +6 -0
- package/dist/templates/starter-game/session/index.html +1 -1
- package/dist/templates/starter-game/session/session.sdk.json +2 -2
- package/dist/templates/starter-game/session/src/App.test.tsx +436 -115
- package/dist/templates/starter-game/session/src/App.tsx +372 -222
- package/dist/templates/starter-game/session/src/JoinCodes.tsx +184 -0
- package/dist/templates/starter-game/session/src/ManagePanel.tsx +188 -0
- package/dist/templates/starter-game/session/src/Results.tsx +340 -0
- package/dist/templates/starter-game/session/src/SessionBar.tsx +179 -0
- package/dist/templates/starter-game/session/src/SessionPanels.tsx +105 -0
- package/dist/templates/starter-game/session/src/SidePanel.tsx +89 -0
- package/dist/templates/starter-game/session/src/StallCard.tsx +253 -0
- package/dist/templates/starter-game/session/src/TopBar.tsx +36 -0
- package/dist/templates/starter-game/session/src/i18n.ts +91 -24
- package/dist/templates/starter-game/session/src/status.ts +28 -0
- package/dist/templates/starter-game/session/types.ts +8 -2
- package/dist/templates/starter-game/shared/Awning.tsx +31 -0
- package/dist/templates/starter-game/shared/HostLogo.test.tsx +38 -0
- package/dist/templates/starter-game/shared/HostLogo.tsx +48 -0
- package/dist/templates/starter-game/shared/StallIcons.tsx +83 -0
- package/dist/templates/starter-game/shared/days.ts +11 -0
- package/dist/templates/starter-game/shared/format.test.ts +13 -0
- package/dist/templates/starter-game/{ui/src → shared}/format.ts +1 -1
- package/dist/templates/starter-game/testing/e2e/game.spec.ts +42 -8
- package/dist/templates/starter-game/ui/defaults.ts +3 -0
- package/dist/templates/starter-game/ui/src/App.test.tsx +197 -29
- package/dist/templates/starter-game/ui/src/App.tsx +176 -99
- package/dist/templates/starter-game/ui/src/DayBar.test.tsx +50 -7
- package/dist/templates/starter-game/ui/src/DayBar.tsx +96 -38
- package/dist/templates/starter-game/ui/src/DaysTable.tsx +69 -0
- package/dist/templates/starter-game/ui/src/FirstDay.tsx +37 -0
- package/dist/templates/starter-game/ui/src/Header.tsx +257 -0
- package/dist/templates/starter-game/ui/src/Lesson.tsx +63 -0
- package/dist/templates/starter-game/ui/src/MakeRow.tsx +98 -71
- package/dist/templates/starter-game/ui/src/Notices.tsx +59 -0
- package/dist/templates/starter-game/ui/src/PastDay.tsx +88 -0
- package/dist/templates/starter-game/ui/src/Section.tsx +26 -26
- package/dist/templates/starter-game/ui/src/ThemeToggle.tsx +25 -11
- package/dist/templates/starter-game/ui/src/TodayPanel.test.tsx +37 -33
- package/dist/templates/starter-game/ui/src/TodayPanel.tsx +66 -52
- package/dist/templates/starter-game/ui/src/WeatherCard.tsx +47 -0
- package/dist/templates/starter-game/ui/src/WeekOver.tsx +145 -0
- package/dist/templates/starter-game/ui/src/YesterdayPanel.tsx +65 -114
- package/dist/templates/starter-game/ui/src/days.ts +58 -0
- package/dist/templates/starter-game/ui/src/i18n.ts +86 -32
- package/dist/templates/starter-game/ui/src/test-helpers.ts +1 -0
- package/dist/templates/starter-game/ui/src/theme.ts +8 -8
- package/dist/templates/starter-game/ui/types.ts +6 -0
- package/dist/templates/starter-game/ui/ui.sdk.json +1 -1
- package/dist/templates/starter-game/validators/daylimit/defaults.ts +13 -0
- package/dist/templates/starter-game/validators/daylimit/logic/logic.test.ts +20 -0
- package/dist/templates/starter-game/validators/daylimit/logic/logic.ts +23 -0
- package/dist/templates/starter-game/validators/daylimit/types.ts +23 -0
- package/dist/templates/starter-game/validators/daylimit/validator.sdk.json +10 -0
- package/dist/templates/starter-game/waiting_room/src/App.test.tsx +83 -5
- package/dist/templates/starter-game/waiting_room/src/App.tsx +262 -119
- package/dist/templates/starter-game/waiting_room/src/i18n.ts +8 -4
- package/dist/utils/error-codes.d.ts +12 -0
- package/dist/utils/local-refs.d.ts +40 -0
- package/dist/utils/schema-members.d.ts +19 -0
- package/package.json +11 -4
- package/dist/templates/starter-game/session/src/Section.tsx +0 -37
- package/dist/templates/starter-game/session/src/TeamDoor.tsx +0 -96
- package/dist/templates/starter-game/session/src/format.ts +0 -8
- package/dist/templates/starter-game/ui/src/HistoryPanel.test.tsx +0 -74
- package/dist/templates/starter-game/ui/src/HistoryPanel.tsx +0 -120
- package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +0 -25
- package/dist/templates/starter-game/ui/src/HostLogo.tsx +0 -38
|
@@ -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:
|
|
@@ -30,6 +32,7 @@ Every callback that works on a file takes a reference:
|
|
|
30
32
|
|
|
31
33
|
- **`getAssetUrl(reference)`** returns a URL the browser can fetch, for `<img>`, `<embed>`, `<video>` and the like. Synchronous, and in a UI only. In a hosted runtime the URL is on the runtime's asset host, cross-origin to the surface's iframe. `useAssetUrl` is the hook form
|
|
32
34
|
- **`readAsset(reference)`** returns the bytes, MIME type, and display name. Asynchronous. In logic the runtime resolves the reference server-side; in a UI the SDK fetches the URL with `credentials: 'include'`. `useAsset` is the hook form that reads text, JSON, or a `Blob`
|
|
35
|
+
- **`describeAsset(reference)`** returns the MIME type and size of a file without reading it, or `undefined` when there is no such file. In logic only: a UI can ask its URL with a `HEAD` request
|
|
33
36
|
- **`extractText(reference)`** returns plain text from a PDF. It is offered to the engine, hooks, tick controllers, and endpoints that declare it in `uses`; a UI reaches it through an endpoint
|
|
34
37
|
|
|
35
38
|
In a UI, `getAssetUrl` strips the prefix and appends the rest to an absolute prefix the host supplies for each scheme. Under `sdk dev` those prefixes are on the asset origin (`--asset-port`), so `asset:shared/hero.jpg` becomes `http://localhost:<asset-port>/assets/scenario/shared/hero.jpg`; a hosted runtime points them at its own asset host. With no scenario active an `asset:` reference still produces a URL, which answers 404. A string with none of the three prefixes throws.
|
|
@@ -53,6 +56,44 @@ A scenario writes references with the prefix in place, usually as values of sett
|
|
|
53
56
|
|
|
54
57
|
Here `briefing` is a settings resource (`settings/briefing/`) declaring `Logo` and `ScenarioBrief` as strings with an empty default, which the engine and UI examples below list in their `settings`. The runtime takes these strings as they are: nothing checks at scenario load that the file exists, and a reference that does not resolve fails when something calls `getAssetUrl`, `readAsset`, or `extractText` with it. See [Scenarios](./scenarios.md#2-add-assets-optional) for where the files go.
|
|
55
58
|
|
|
59
|
+
### A file per language
|
|
60
|
+
|
|
61
|
+
A file setting (see [Settings that hold a file](./settings.md#settings-that-hold-a-file)) holds one file. For a document translated per language, key a map by locale and let its entries hold the files: the `blob` declaration goes on the map's `additionalProperties`, so every entry is checked as a file setting of its own:
|
|
62
|
+
|
|
63
|
+
```json
|
|
64
|
+
"Brief": {
|
|
65
|
+
"title": "Briefing document",
|
|
66
|
+
"description": "The briefing as a PDF, one per language, keyed by locale. A language with no entry reads English",
|
|
67
|
+
"type": "object",
|
|
68
|
+
"default": {},
|
|
69
|
+
"propertyNames": { "enum": ["en", "fr"] },
|
|
70
|
+
"additionalProperties": {
|
|
71
|
+
"type": "string",
|
|
72
|
+
"blob": { "accept": ["application/pdf"], "maxBytes": 5242880 }
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
A scenario sets one entry per language it ships:
|
|
78
|
+
|
|
79
|
+
```json
|
|
80
|
+
"briefing": {
|
|
81
|
+
"Brief": { "en": "asset:brief.pdf", "fr": "asset:brief-fr.pdf" }
|
|
82
|
+
}
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
The build checks every entry, as it checks a single file setting: each file must be shipped, within `maxBytes`, and of a type `accept` lists, and the error names the entry (`briefing.Brief.fr`). A setup screen, the scenario editor or an agent writing one entry is held to the same declaration, and a scenario may set one language and leave the others to the layer beneath, since a map merges key by key.
|
|
86
|
+
|
|
87
|
+
The game picks the entry for its locale, falling back to the one it always ships:
|
|
88
|
+
|
|
89
|
+
```tsx
|
|
90
|
+
const { settings } = useUserInterfaceData<Context, Settings>();
|
|
91
|
+
const { locale } = useUserInterfaceLocale();
|
|
92
|
+
const src = useAssetUrl(settings.briefing.Brief[locale] ?? settings.briefing.Brief.en);
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Use this when a scenario chooses the files. A file the package ships for every scenario alike can instead sit in a directory named for its locale, which `useAsset` finds on its own (see [Internationalization](./internationalization.md)).
|
|
96
|
+
|
|
56
97
|
### How a file moves through a game
|
|
57
98
|
|
|
58
99
|
```
|
|
@@ -149,7 +190,7 @@ const logo = useAssetUrl('asset:shared/logo.svg');
|
|
|
149
190
|
return <img src={logo} alt="Logo" />;
|
|
150
191
|
```
|
|
151
192
|
|
|
152
|
-
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)).
|
|
153
194
|
|
|
154
195
|
## Reading an asset in an engine
|
|
155
196
|
|
|
@@ -193,6 +234,28 @@ export const Run: RunFunction<Context, Settings> = async ({ context, callbacks }
|
|
|
193
234
|
- `data` is a `Uint8Array`. Use `decodeUtf8` for text formats; pass binary directly to downstream APIs
|
|
194
235
|
- The same callback resolves `asset:shared/brief.pdf` and `blob:abc123`: there is no separate API for bundled and uploaded files
|
|
195
236
|
|
|
237
|
+
## Checking a file without reading it
|
|
238
|
+
|
|
239
|
+
`readAsset` returns every byte, which is waste when you only need to know a file is there, or how big it is: a scenario's videos, say. `describeAsset` resolves a reference exactly as `readAsset` does and answers `{ mimeType, size }`, or `undefined` when there is no such file:
|
|
240
|
+
|
|
241
|
+
```typescript
|
|
242
|
+
const video = await callbacks.describeAsset?.('asset:videos/intro.mp4');
|
|
243
|
+
|
|
244
|
+
if (video === undefined) {
|
|
245
|
+
// the scenario ships no intro video
|
|
246
|
+
} else if (video.size > 50_000_000) {
|
|
247
|
+
// too large to play in the room
|
|
248
|
+
}
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
**Notes:**
|
|
252
|
+
|
|
253
|
+
- Like `readAsset`, it needs no `uses` entry: every engine, hook, tick controller, and endpoint has it
|
|
254
|
+
- It is optional in the type, so call it with `?.`: a runtime built before SDK 1.4 does not provide it, and a test that builds its callbacks by hand need not either. Pass your own `describeAsset` in such a test to exercise the code that uses it
|
|
255
|
+
- `mimeType` is what `readAsset` would report: the type a blob was stored with, or the type of a bundled file judged from its extension
|
|
256
|
+
- A reference with none of the three prefixes still throws: that is a mistake rather than a missing file
|
|
257
|
+
- A validator's `Scenario` gate can have it too, with `readAsset`, to check the files a scenario names. There `readAsset` reads no file over 10 MB, so use `describeAsset` to check a large file. See [Checking the files a scenario names](./validators.md#checking-the-files-a-scenario-names)
|
|
258
|
+
|
|
196
259
|
## Extracting text from a document
|
|
197
260
|
|
|
198
261
|
Use the `extractText` callback to convert a document into plain text suitable for passing to an LLM. Available in the engine, hooks, tick controllers, and endpoints that declare `"extractText"` in `uses`. UIs reach it through an endpoint. Currently supports **PDF** files.
|
|
@@ -294,7 +357,7 @@ The field accepts two kinds of string, so the same endpoint serves every caller:
|
|
|
294
357
|
- **A `blob:` reference** to a file already stored. A UI passes the reference `uploadBlob` returned, as in the example above; a script or an agent uploads first (locally, `POST /api/blobs` or `pnpm run sdk blob upload`)
|
|
295
358
|
- **A `data:` URI** carrying the file inline, for a caller with no upload of its own: `data:application/pdf;name=brief.pdf;base64,...`. Up to 5 MB
|
|
296
359
|
|
|
297
|
-
Either way the handler receives a `blob:` reference, typed `` `blob:${string}` ``, that names a file of an accepted type, judged by its bytes, within the size. A URL, a wrong type or an oversized file is refused before the handler runs. Without `blob`, a field is a plain string the handler must check itself.
|
|
360
|
+
A file field may also be the entries of a map, with `blob` on its `additionalProperties` or a `patternProperties` schema, and each entry is checked as a field of its own. Either way the handler receives a `blob:` reference, typed `` `blob:${string}` ``, that names a file of an accepted type, judged by its bytes, within the size. A URL, a wrong type or an oversized file is refused before the handler runs. Without `blob`, a field is a plain string the handler must check itself.
|
|
298
361
|
|
|
299
362
|
See [Take a file in an endpoint](../recipes/take-a-file-in-an-endpoint.md).
|
|
300
363
|
|
|
@@ -358,26 +421,57 @@ pnpm run sdk patch \
|
|
|
358
421
|
"[{\"op\":\"replace\",\"path\":\"/upload/DocumentRef\",\"value\":\"$REFERENCE\"}]"
|
|
359
422
|
```
|
|
360
423
|
|
|
361
|
-
##
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
| Extension
|
|
366
|
-
|
|
|
367
|
-
| `.
|
|
368
|
-
| `.
|
|
369
|
-
| `.
|
|
370
|
-
| `.
|
|
371
|
-
| `.
|
|
372
|
-
| `.
|
|
373
|
-
| `.
|
|
374
|
-
| `.
|
|
375
|
-
| `.
|
|
376
|
-
| `.
|
|
377
|
-
| `.
|
|
378
|
-
| `.
|
|
379
|
-
| `.
|
|
380
|
-
|
|
|
424
|
+
## Media types
|
|
425
|
+
|
|
426
|
+
A package file's media type comes from its extension, compared without regard to case, by the table below. The build checks a file setting's `accept` against it, the dev server serves scenario and shared files under it, `readAsset` reports it, and so does every runtime, so a file the build accepted arrives as the type it was accepted as. An extension the table does not list is `application/octet-stream` everywhere: rename a file to a listed extension if a game or an `accept` depends on its type. A blob keeps the type it was uploaded with, whatever its name, and `sdk blob upload` takes it from the same table.
|
|
427
|
+
|
|
428
|
+
| Extension | Media type |
|
|
429
|
+
| ------------------ | --------------------------------------------------------------------------- |
|
|
430
|
+
| `.aac` | `audio/aac` |
|
|
431
|
+
| `.avif` | `image/avif` |
|
|
432
|
+
| `.bmp` | `image/bmp` |
|
|
433
|
+
| `.css` | `text/css` |
|
|
434
|
+
| `.csv` | `text/csv` |
|
|
435
|
+
| `.doc` | `application/msword` |
|
|
436
|
+
| `.docx` | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
|
|
437
|
+
| `.flac` | `audio/flac` |
|
|
438
|
+
| `.gif` | `image/gif` |
|
|
439
|
+
| `.htm`, `.html` | `text/html` |
|
|
440
|
+
| `.ico` | `image/x-icon` |
|
|
441
|
+
| `.jpeg`, `.jpg` | `image/jpeg` |
|
|
442
|
+
| `.js`, `.mjs` | `text/javascript` |
|
|
443
|
+
| `.json` | `application/json` |
|
|
444
|
+
| `.m4a` | `audio/mp4` |
|
|
445
|
+
| `.m4v`, `.mp4` | `video/mp4` |
|
|
446
|
+
| `.md` | `text/markdown` |
|
|
447
|
+
| `.mov` | `video/quicktime` |
|
|
448
|
+
| `.mp3` | `audio/mpeg` |
|
|
449
|
+
| `.odp` | `application/vnd.oasis.opendocument.presentation` |
|
|
450
|
+
| `.ods` | `application/vnd.oasis.opendocument.spreadsheet` |
|
|
451
|
+
| `.odt` | `application/vnd.oasis.opendocument.text` |
|
|
452
|
+
| `.ogg`, `.opus` | `audio/ogg` |
|
|
453
|
+
| `.otf` | `font/otf` |
|
|
454
|
+
| `.pdf` | `application/pdf` |
|
|
455
|
+
| `.png` | `image/png` |
|
|
456
|
+
| `.ppt` | `application/vnd.ms-powerpoint` |
|
|
457
|
+
| `.pptx` | `application/vnd.openxmlformats-officedocument.presentationml.presentation` |
|
|
458
|
+
| `.rtf` | `application/rtf` |
|
|
459
|
+
| `.svg` | `image/svg+xml` |
|
|
460
|
+
| `.tif`, `.tiff` | `image/tiff` |
|
|
461
|
+
| `.ttf` | `font/ttf` |
|
|
462
|
+
| `.txt` | `text/plain` |
|
|
463
|
+
| `.vtt` | `text/vtt` |
|
|
464
|
+
| `.wav` | `audio/wav` |
|
|
465
|
+
| `.webm` | `video/webm` |
|
|
466
|
+
| `.webp` | `image/webp` |
|
|
467
|
+
| `.woff` | `font/woff` |
|
|
468
|
+
| `.woff2` | `font/woff2` |
|
|
469
|
+
| `.xls` | `application/vnd.ms-excel` |
|
|
470
|
+
| `.xlsx` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` |
|
|
471
|
+
| `.xml` | `application/xml` |
|
|
472
|
+
| `.yaml`, `.yml` | `application/yaml` |
|
|
473
|
+
| `.zip` | `application/zip` |
|
|
474
|
+
| Any other, or none | `application/octet-stream` |
|
|
381
475
|
|
|
382
476
|
## Capability design
|
|
383
477
|
|
|
@@ -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:
|
|
@@ -438,7 +440,7 @@ The mental model is a phone app's permissions: a static declaration, enforced at
|
|
|
438
440
|
| `generateSpeech` | Text-to-speech, returning an audio blob; see [Speech generation](./speech-generation.md) |
|
|
439
441
|
| `writeBlob` | Writes raw bytes to the blob store and returns a `blob:<id>` reference; most useful in an endpoint that returns a file |
|
|
440
442
|
|
|
441
|
-
The list is closed and fixed by the SDK (see [`ApiUse`](../api/sdk.md#apiuse)). Every other callback is runtime plumbing and is never gated: logic always has `readAsset` and `getPastState`, and a UI's `getAssetUrl`, `uploadBlob`, `requestTick` and the rest are always there when the surface exposes them.
|
|
443
|
+
The list is closed and fixed by the SDK (see [`ApiUse`](../api/sdk.md#apiuse)). Every other callback is runtime plumbing and is never gated: logic always has `readAsset`, `describeAsset` and `getPastState`, and a UI's `getAssetUrl`, `uploadBlob`, `requestTick` and the rest are always there when the surface exposes them.
|
|
442
444
|
|
|
443
445
|
### What happens when a resource calls one it did not declare
|
|
444
446
|
|
|
@@ -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.
|
|
@@ -49,7 +51,7 @@ An agent writing a scenario changes settings and nothing else, so anything you w
|
|
|
49
51
|
}
|
|
50
52
|
```
|
|
51
53
|
|
|
52
|
-
Once facilitators have saved scenarios, a release can leave them behind. When you remove, rename, or reshape a setting, change what a value means,
|
|
54
|
+
Once facilitators have saved scenarios, a release can leave them behind. When you remove, rename, or reshape a setting, change what a value means, change how the game loads scenario assets, or move or remove a built-in scenario's files, bump `scenarioFormat` in `seriousgaming.sdk.json` (it starts at 1), and a runtime refuses the older scenarios rather than applying them wrongly. A new setting with a default needs no bump. See [Scenario format: when to bump it](./scenarios.md#scenario-format-when-to-bump-it).
|
|
53
55
|
|
|
54
56
|
Build an editor when a form is not enough: values that only make sense together, uploaded assets, a preview of what participants will see, or guidance a facilitator needs while choosing.
|
|
55
57
|
|
|
@@ -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
|
|
|
@@ -123,11 +125,12 @@ The flag says the scenario is for a particular audience. It never says who they
|
|
|
123
125
|
|
|
124
126
|
What a production runtime does with the flag is its own business, but it must not offer a restricted scenario for selection, list it, resolve it by identifier, or serve its assets to a caller it has not granted it to.
|
|
125
127
|
|
|
126
|
-
|
|
128
|
+
Four things are worth knowing before you rely on it:
|
|
127
129
|
|
|
128
130
|
- **The dev server ignores it.** There are no organisations locally and the package is yours, so restricted scenarios are offered exactly like any other. You cannot test the restriction from here
|
|
129
131
|
- **A restricted scenario cannot also be the default.** A default is what a caller gets when it picks nothing, so it has to be one every caller can be offered. The build refuses a scenario that sets both
|
|
130
132
|
- **It does not cover `shared:` assets.** Files under the package-level `shared-assets/` directory resolve whatever scenario is active, so anything belonging to one client goes under that scenario's own `assets/`, not in `shared-assets/`
|
|
133
|
+
- **Copies of it are restricted too.** A custom scenario copied from a restricted one reads its files, so a runtime offers the copy only to callers it has granted the original to. A client that loses the grant loses the copies built on it
|
|
131
134
|
|
|
132
135
|
The flag protects the scenario only on a runtime that implements grants: one that does not recognise the field offers the scenario normally. What it always does is record the intent in the package, reviewed alongside the content it describes, rather than leaving it to a setting somebody remembers to tick after the upload.
|
|
133
136
|
|
|
@@ -281,6 +284,8 @@ From a terminal, the same thing:
|
|
|
281
284
|
pnpm run sdk scenario ai_influence # or `none` for the settings defaults
|
|
282
285
|
```
|
|
283
286
|
|
|
287
|
+
`none`, and the tab's **None** choice, are only offered when no scenario is the default.
|
|
288
|
+
|
|
284
289
|
### Managing scenarios while the server runs
|
|
285
290
|
|
|
286
291
|
The **Scenario** tab is a small manager, and everything it does writes into your
|
|
@@ -454,6 +459,12 @@ The editor is optional. `customScenarios.supported` is what switches custom scen
|
|
|
454
459
|
|
|
455
460
|
A saved scenario keeps every file it references for as long as it exists, whichever route uploaded it.
|
|
456
461
|
|
|
462
|
+
### Files a custom scenario reads
|
|
463
|
+
|
|
464
|
+
A custom scenario has no `assets/` directory of its own. Copying a scenario converts the `asset:` references in its settings, but not the ones your code builds, such as `` `asset:documents/${locale}/${id}.json` ``. Those resolve against the **built-in scenario the custom one descends from**: the scenario under `scenarios/` it was copied from, followed back through any copies of copies, as the package version the session runs ships it. A scenario draft does the same, so an editor or an agent working on a copy of `northwind` reads `northwind`'s files. A custom scenario begun from the defaults, with no built-in scenario behind it, resolves no `asset:` reference at all.
|
|
465
|
+
|
|
466
|
+
A runtime remembers which built-in scenario each custom scenario descends from, and refuses to apply one whose ancestor your current release no longer ships, naming it. So removing or renaming a built-in scenario retires every custom scenario copied from it, and moving its files breaks those your code reads: bump `scenarioFormat` when you do either (see below).
|
|
467
|
+
|
|
457
468
|
### Writing scenarios with an agent
|
|
458
469
|
|
|
459
470
|
A platform that lets an agent write scenarios gives it four things, and your game decides what each holds:
|
|
@@ -486,6 +497,7 @@ Bump it when a scenario saved against the previous release may no longer be corr
|
|
|
486
497
|
- A setting removed, renamed, or reshaped (an object split in two, a number that becomes an enum)
|
|
487
498
|
- A change in what a value means (a percentage that becomes a fraction, a per-round amount that becomes a total)
|
|
488
499
|
- A change in how the game loads scenario assets (a reference resolved from a different path)
|
|
500
|
+
- A built-in scenario's files moved or removed, or the scenario itself removed or renamed. A custom scenario reads the files your code names from the built-in scenario it was copied from (see [Files a custom scenario reads](#files-a-custom-scenario-reads))
|
|
489
501
|
- 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
502
|
- 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
|
|
491
503
|
|