@seriousgaming/sdk-tools 1.2.0 → 1.4.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 +3582 -2834
- package/dist/client.js +1145 -543
- package/dist/core/participant-registry.d.ts +6 -0
- package/dist/core/session-host.d.ts +4 -2
- package/dist/core/session-roster.d.ts +4 -1
- package/dist/core/settings-locks.d.ts +27 -2
- package/dist/dev/console/assets/{index-BNLEVOQA.js → index-BvB-LFQZ.js} +47 -47
- package/dist/dev/console/index.html +1 -1
- package/dist/dev/routes.d.ts +4 -0
- package/dist/dev/view/batch.d.ts +24 -10
- package/dist/dev/view/view.d.ts +2 -1
- package/dist/docs/api/index.md +2 -2
- package/dist/docs/api/sdk-commands.md +4 -0
- package/dist/docs/api/sdk-e2e.md +4 -0
- package/dist/docs/api/sdk-tools-client.md +5 -0
- package/dist/docs/api/sdk-ui-testing.md +1 -0
- package/dist/docs/api/sdk-ui.md +33 -1
- package/dist/docs/api/sdk.md +82 -3
- package/dist/docs/changelog.md +41 -0
- package/dist/docs/concepts/terminology.md +1 -1
- package/dist/docs/guides/capabilities.md +2 -0
- package/dist/docs/guides/endpoints.md +2 -2
- package/dist/docs/guides/engine-testing.md +1 -1
- package/dist/docs/guides/file-handling.md +113 -21
- package/dist/docs/guides/llm-integration.md +1 -1
- package/dist/docs/guides/presentation.md +23 -9
- package/dist/docs/guides/scenario-editor.md +1 -1
- package/dist/docs/guides/scenarios.md +9 -1
- package/dist/docs/guides/session.md +47 -8
- package/dist/docs/guides/settings.md +62 -2
- package/dist/docs/guides/testing.md +9 -0
- package/dist/docs/guides/ui.md +33 -0
- package/dist/docs/guides/upgrading.md +11 -0
- package/dist/docs/guides/validators.md +62 -4
- package/dist/docs/guides/waiting-room.md +2 -0
- package/dist/docs/recipes/upload-and-display-files.md +7 -7
- package/dist/docs/recipes/validate-scenarios.md +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/protocol.d.ts +27 -2
- package/dist/host.js +64 -2
- package/dist/runtime/manifest-version.d.ts +1 -1
- package/dist/runtime.js +9 -2
- package/dist/storage/asset-resolver.d.ts +24 -1
- package/dist/storage/blob-store.d.ts +7 -0
- package/dist/utils/local-refs.d.ts +40 -0
- package/dist/utils/schema-members.d.ts +19 -0
- package/package.json +3 -3
|
@@ -30,6 +30,7 @@ Every callback that works on a file takes a reference:
|
|
|
30
30
|
|
|
31
31
|
- **`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
32
|
- **`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`
|
|
33
|
+
- **`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
34
|
- **`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
35
|
|
|
35
36
|
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 +54,44 @@ A scenario writes references with the prefix in place, usually as values of sett
|
|
|
53
54
|
|
|
54
55
|
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
56
|
|
|
57
|
+
### A file per language
|
|
58
|
+
|
|
59
|
+
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:
|
|
60
|
+
|
|
61
|
+
```json
|
|
62
|
+
"Brief": {
|
|
63
|
+
"title": "Briefing document",
|
|
64
|
+
"description": "The briefing as a PDF, one per language, keyed by locale. A language with no entry reads English",
|
|
65
|
+
"type": "object",
|
|
66
|
+
"default": {},
|
|
67
|
+
"propertyNames": { "enum": ["en", "fr"] },
|
|
68
|
+
"additionalProperties": {
|
|
69
|
+
"type": "string",
|
|
70
|
+
"blob": { "accept": ["application/pdf"], "maxBytes": 5242880 }
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
A scenario sets one entry per language it ships:
|
|
76
|
+
|
|
77
|
+
```json
|
|
78
|
+
"briefing": {
|
|
79
|
+
"Brief": { "en": "asset:brief.pdf", "fr": "asset:brief-fr.pdf" }
|
|
80
|
+
}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
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.
|
|
84
|
+
|
|
85
|
+
The game picks the entry for its locale, falling back to the one it always ships:
|
|
86
|
+
|
|
87
|
+
```tsx
|
|
88
|
+
const { settings } = useUserInterfaceData<Context, Settings>();
|
|
89
|
+
const { locale } = useUserInterfaceLocale();
|
|
90
|
+
const src = useAssetUrl(settings.briefing.Brief[locale] ?? settings.briefing.Brief.en);
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
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)).
|
|
94
|
+
|
|
56
95
|
### How a file moves through a game
|
|
57
96
|
|
|
58
97
|
```
|
|
@@ -193,6 +232,28 @@ export const Run: RunFunction<Context, Settings> = async ({ context, callbacks }
|
|
|
193
232
|
- `data` is a `Uint8Array`. Use `decodeUtf8` for text formats; pass binary directly to downstream APIs
|
|
194
233
|
- The same callback resolves `asset:shared/brief.pdf` and `blob:abc123`: there is no separate API for bundled and uploaded files
|
|
195
234
|
|
|
235
|
+
## Checking a file without reading it
|
|
236
|
+
|
|
237
|
+
`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:
|
|
238
|
+
|
|
239
|
+
```typescript
|
|
240
|
+
const video = await callbacks.describeAsset?.('asset:videos/intro.mp4');
|
|
241
|
+
|
|
242
|
+
if (video === undefined) {
|
|
243
|
+
// the scenario ships no intro video
|
|
244
|
+
} else if (video.size > 50_000_000) {
|
|
245
|
+
// too large to play in the room
|
|
246
|
+
}
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
**Notes:**
|
|
250
|
+
|
|
251
|
+
- Like `readAsset`, it needs no `uses` entry: every engine, hook, tick controller, and endpoint has it
|
|
252
|
+
- 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
|
|
253
|
+
- `mimeType` is what `readAsset` would report: the type a blob was stored with, or the type of a bundled file judged from its extension
|
|
254
|
+
- A reference with none of the three prefixes still throws: that is a mistake rather than a missing file
|
|
255
|
+
- 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)
|
|
256
|
+
|
|
196
257
|
## Extracting text from a document
|
|
197
258
|
|
|
198
259
|
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 +355,7 @@ The field accepts two kinds of string, so the same endpoint serves every caller:
|
|
|
294
355
|
- **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
356
|
- **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
357
|
|
|
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.
|
|
358
|
+
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
359
|
|
|
299
360
|
See [Take a file in an endpoint](../recipes/take-a-file-in-an-endpoint.md).
|
|
300
361
|
|
|
@@ -358,26 +419,57 @@ pnpm run sdk patch \
|
|
|
358
419
|
"[{\"op\":\"replace\",\"path\":\"/upload/DocumentRef\",\"value\":\"$REFERENCE\"}]"
|
|
359
420
|
```
|
|
360
421
|
|
|
361
|
-
##
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
| Extension
|
|
366
|
-
|
|
|
367
|
-
| `.
|
|
368
|
-
| `.
|
|
369
|
-
| `.
|
|
370
|
-
| `.
|
|
371
|
-
| `.
|
|
372
|
-
| `.
|
|
373
|
-
| `.
|
|
374
|
-
| `.
|
|
375
|
-
| `.
|
|
376
|
-
| `.
|
|
377
|
-
| `.
|
|
378
|
-
| `.
|
|
379
|
-
| `.
|
|
380
|
-
|
|
|
422
|
+
## Media types
|
|
423
|
+
|
|
424
|
+
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.
|
|
425
|
+
|
|
426
|
+
| Extension | Media type |
|
|
427
|
+
| ------------------ | --------------------------------------------------------------------------- |
|
|
428
|
+
| `.aac` | `audio/aac` |
|
|
429
|
+
| `.avif` | `image/avif` |
|
|
430
|
+
| `.bmp` | `image/bmp` |
|
|
431
|
+
| `.css` | `text/css` |
|
|
432
|
+
| `.csv` | `text/csv` |
|
|
433
|
+
| `.doc` | `application/msword` |
|
|
434
|
+
| `.docx` | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
|
|
435
|
+
| `.flac` | `audio/flac` |
|
|
436
|
+
| `.gif` | `image/gif` |
|
|
437
|
+
| `.htm`, `.html` | `text/html` |
|
|
438
|
+
| `.ico` | `image/x-icon` |
|
|
439
|
+
| `.jpeg`, `.jpg` | `image/jpeg` |
|
|
440
|
+
| `.js`, `.mjs` | `text/javascript` |
|
|
441
|
+
| `.json` | `application/json` |
|
|
442
|
+
| `.m4a` | `audio/mp4` |
|
|
443
|
+
| `.m4v`, `.mp4` | `video/mp4` |
|
|
444
|
+
| `.md` | `text/markdown` |
|
|
445
|
+
| `.mov` | `video/quicktime` |
|
|
446
|
+
| `.mp3` | `audio/mpeg` |
|
|
447
|
+
| `.odp` | `application/vnd.oasis.opendocument.presentation` |
|
|
448
|
+
| `.ods` | `application/vnd.oasis.opendocument.spreadsheet` |
|
|
449
|
+
| `.odt` | `application/vnd.oasis.opendocument.text` |
|
|
450
|
+
| `.ogg`, `.opus` | `audio/ogg` |
|
|
451
|
+
| `.otf` | `font/otf` |
|
|
452
|
+
| `.pdf` | `application/pdf` |
|
|
453
|
+
| `.png` | `image/png` |
|
|
454
|
+
| `.ppt` | `application/vnd.ms-powerpoint` |
|
|
455
|
+
| `.pptx` | `application/vnd.openxmlformats-officedocument.presentationml.presentation` |
|
|
456
|
+
| `.rtf` | `application/rtf` |
|
|
457
|
+
| `.svg` | `image/svg+xml` |
|
|
458
|
+
| `.tif`, `.tiff` | `image/tiff` |
|
|
459
|
+
| `.ttf` | `font/ttf` |
|
|
460
|
+
| `.txt` | `text/plain` |
|
|
461
|
+
| `.vtt` | `text/vtt` |
|
|
462
|
+
| `.wav` | `audio/wav` |
|
|
463
|
+
| `.webm` | `video/webm` |
|
|
464
|
+
| `.webp` | `image/webp` |
|
|
465
|
+
| `.woff` | `font/woff` |
|
|
466
|
+
| `.woff2` | `font/woff2` |
|
|
467
|
+
| `.xls` | `application/vnd.ms-excel` |
|
|
468
|
+
| `.xlsx` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` |
|
|
469
|
+
| `.xml` | `application/xml` |
|
|
470
|
+
| `.yaml`, `.yml` | `application/yaml` |
|
|
471
|
+
| `.zip` | `application/zip` |
|
|
472
|
+
| Any other, or none | `application/octet-stream` |
|
|
381
473
|
|
|
382
474
|
## Capability design
|
|
383
475
|
|
|
@@ -438,7 +438,7 @@ The mental model is a phone app's permissions: a static declaration, enforced at
|
|
|
438
438
|
| `generateSpeech` | Text-to-speech, returning an audio blob; see [Speech generation](./speech-generation.md) |
|
|
439
439
|
| `writeBlob` | Writes raw bytes to the blob store and returns a `blob:<id>` reference; most useful in an endpoint that returns a file |
|
|
440
440
|
|
|
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.
|
|
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`, `describeAsset` and `getPastState`, and a UI's `getAssetUrl`, `uploadBlob`, `requestTick` and the rest are always there when the surface exposes them.
|
|
442
442
|
|
|
443
443
|
### What happens when a resource calls one it did not declare
|
|
444
444
|
|
|
@@ -53,15 +53,15 @@ const { game, session, settings, theme, locale, getPastState, getAssetUrl } = us
|
|
|
53
53
|
>();
|
|
54
54
|
```
|
|
55
55
|
|
|
56
|
-
| Field | What it holds
|
|
57
|
-
| -------------- |
|
|
58
|
-
| `game` | `name` in the current locale, `maxTicks` (or `null` when the engine or tick controller decides), `mode`, and `scenarioName` (or `null`). Present with or without a session
|
|
59
|
-
| `session` | `null` with no session. Otherwise its `id`, `name`, `completedTicks` (the most rounds any team has completed, 0 before the first), `data` (the shared store and every team, narrowed to `reads`) and `
|
|
60
|
-
| `settings` | The settings resources the presentation declares, resolved for the scenario, and for the session when there is one
|
|
61
|
-
| `theme` | The host's theme, to map onto the deck's colours
|
|
62
|
-
| `locale` | The locale to render in
|
|
63
|
-
| `getPastState` | Reads past rounds, as the session UI does, with `teams` defaulting to every team. Rejects when there is no session
|
|
64
|
-
| `getAssetUrl` | Turns an `asset:`, `shared:` or `blob:` reference into a URL
|
|
56
|
+
| Field | What it holds |
|
|
57
|
+
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
58
|
+
| `game` | `name` in the current locale, `maxTicks` (or `null` when the engine or tick controller decides), `mode`, and `scenarioName` (or `null`). Present with or without a session |
|
|
59
|
+
| `session` | `null` with no session. Otherwise its `id`, `name`, `completedTicks` (the most rounds any team has completed, 0 before the first), `data` (the shared store and every team, narrowed to `reads`), `teams`, and how the room joins: `participants`, `joinLinks` and `joinPin` (see [Showing the room how to join](#showing-the-room-how-to-join)) |
|
|
60
|
+
| `settings` | The settings resources the presentation declares, resolved for the scenario, and for the session when there is one |
|
|
61
|
+
| `theme` | The host's theme, to map onto the deck's colours |
|
|
62
|
+
| `locale` | The locale to render in |
|
|
63
|
+
| `getPastState` | Reads past rounds, as the session UI does, with `teams` defaulting to every team. Rejects when there is no session |
|
|
64
|
+
| `getAssetUrl` | Turns an `asset:`, `shared:` or `blob:` reference into a URL |
|
|
65
65
|
|
|
66
66
|
A presentation sees every team: it is the facilitator's view of the room.
|
|
67
67
|
|
|
@@ -85,6 +85,16 @@ export function useResults(): Results {
|
|
|
85
85
|
}
|
|
86
86
|
```
|
|
87
87
|
|
|
88
|
+
### Showing the room how to join
|
|
89
|
+
|
|
90
|
+
The first slides are often on the projector while the room arrives, so a session carries what a join slide needs:
|
|
91
|
+
|
|
92
|
+
- **`joinLinks`**: one entry per team, in index order, each `{ teamId, joinUrl, fallbackJoinUrl? }`. Encode `joinUrl` in a QR code; offer `fallbackJoinUrl` only on request. There is no observe URL: watching a team is the facilitator's tool, not the room's
|
|
93
|
+
- **`joinPin`**: the code to enter alongside the link, or `null` when joining needs none. Show it beside the link, never inside it
|
|
94
|
+
- **`participants`**: every team's participants, `connected` or not, for a count of who has arrived
|
|
95
|
+
|
|
96
|
+
All three are optional in the type. A host that predates them leaves them out, so render a placeholder there, as you would with no session.
|
|
97
|
+
|
|
88
98
|
### Varying by scenario
|
|
89
99
|
|
|
90
100
|
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)).
|
|
@@ -150,6 +160,10 @@ const brand = {
|
|
|
150
160
|
|
|
151
161
|
Use the light palette whatever mode the facilitator's screen is in: slides are made to be projected, and a projector washes out a dark slide. `useBrand()` gives a custom component the resolved colours, and the CSS variables `--deck-primary`, `--deck-secondary` and `--deck-muted` reach anything inside a slide.
|
|
152
162
|
|
|
163
|
+
## Opening from the session UI
|
|
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).
|
|
166
|
+
|
|
153
167
|
## Coming back to where you were
|
|
154
168
|
|
|
155
169
|
`rememberAs` keeps the facilitator's place in the browser's own storage, so a reload, a closed laptop lid or a break comes back to the same slide and step:
|
|
@@ -49,7 +49,7 @@ An agent writing a scenario changes settings and nothing else, so anything you w
|
|
|
49
49
|
}
|
|
50
50
|
```
|
|
51
51
|
|
|
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,
|
|
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, 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
53
|
|
|
54
54
|
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
55
|
|
|
@@ -123,11 +123,12 @@ The flag says the scenario is for a particular audience. It never says who they
|
|
|
123
123
|
|
|
124
124
|
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
125
|
|
|
126
|
-
|
|
126
|
+
Four things are worth knowing before you rely on it:
|
|
127
127
|
|
|
128
128
|
- **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
129
|
- **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
130
|
- **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/`
|
|
131
|
+
- **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
132
|
|
|
132
133
|
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
134
|
|
|
@@ -454,6 +455,12 @@ The editor is optional. `customScenarios.supported` is what switches custom scen
|
|
|
454
455
|
|
|
455
456
|
A saved scenario keeps every file it references for as long as it exists, whichever route uploaded it.
|
|
456
457
|
|
|
458
|
+
### Files a custom scenario reads
|
|
459
|
+
|
|
460
|
+
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.
|
|
461
|
+
|
|
462
|
+
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).
|
|
463
|
+
|
|
457
464
|
### Writing scenarios with an agent
|
|
458
465
|
|
|
459
466
|
A platform that lets an agent write scenarios gives it four things, and your game decides what each holds:
|
|
@@ -486,6 +493,7 @@ Bump it when a scenario saved against the previous release may no longer be corr
|
|
|
486
493
|
- A setting removed, renamed, or reshaped (an object split in two, a number that becomes an enum)
|
|
487
494
|
- A change in what a value means (a percentage that becomes a fraction, a per-round amount that becomes a total)
|
|
488
495
|
- A change in how the game loads scenario assets (a reference resolved from a different path)
|
|
496
|
+
- 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
497
|
- 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
498
|
- 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
499
|
|
|
@@ -427,9 +427,9 @@ Deliberately, the [tick interval bounds](./tick-controller.md) do not apply. The
|
|
|
427
427
|
|
|
428
428
|
### Opening host overlays
|
|
429
429
|
|
|
430
|
-
Some things a facilitator wants are drawn by the host rather than by your game: the [facilitator guide](./guide.md), a team's print sheet. Your session UI owns the whole canvas, so without a way to ask, a facilitator has to leave it to reach them.
|
|
430
|
+
Some things a facilitator wants are drawn by the host rather than by your game: the [facilitator guide](./guide.md), a team's print sheet, your [presentation](./presentation.md). Your session UI owns the whole canvas, so without a way to ask, a facilitator has to leave it to reach them.
|
|
431
431
|
|
|
432
|
-
`openHostOverlay` asks. The host renders the overlay in its own chrome,
|
|
432
|
+
`openHostOverlay` asks. The host renders the overlay in its own chrome, over your session UI or in a window of its own, where you can neither restyle nor suppress it. Which is the host's choice: a deck usually gets a window, so the facilitator can put it on the projector and keep your session UI on their own screen:
|
|
433
433
|
|
|
434
434
|
```typescript
|
|
435
435
|
import {
|
|
@@ -450,6 +450,9 @@ function OverlayControls() {
|
|
|
450
450
|
{overlays.includes('print-sheets') && (
|
|
451
451
|
<Button onClick={() => void openHostOverlay('print-sheets')}>Print sheets</Button>
|
|
452
452
|
)}
|
|
453
|
+
{overlays.includes('presentation') && (
|
|
454
|
+
<Button onClick={() => void openHostOverlay('presentation')}>Presentation</Button>
|
|
455
|
+
)}
|
|
453
456
|
</Stack>
|
|
454
457
|
);
|
|
455
458
|
}
|
|
@@ -459,13 +462,24 @@ function OverlayControls() {
|
|
|
459
462
|
|
|
460
463
|
The second argument narrows the overlay:
|
|
461
464
|
|
|
462
|
-
| Overlay | Second argument | Omitted means
|
|
463
|
-
| --------------------- | ------------------------------------------------ |
|
|
464
|
-
| `'facilitator-guide'` | None: a game holds one guide, and one is ignored | The game's guide
|
|
465
|
-
| `'print-sheets'` | A team id | Every team
|
|
465
|
+
| Overlay | Second argument | Omitted means |
|
|
466
|
+
| --------------------- | ------------------------------------------------ | --------------------------------- |
|
|
467
|
+
| `'facilitator-guide'` | None: a game holds one guide, and one is ignored | The game's guide |
|
|
468
|
+
| `'print-sheets'` | A team id | Every team |
|
|
469
|
+
| `'presentation'` | None: a game holds one deck, and one is ignored | The game's deck, for this session |
|
|
466
470
|
|
|
467
471
|
It rejects with a `MutationError` carrying `{ kind: 'denied' }` for an overlay the host does not offer and for a team id that is not in the session.
|
|
468
472
|
|
|
473
|
+
**The presentation needs `presentation-overlay` in `requires`.** A host offers `'presentation'` only to a game that ships a `presentation/` slot and lists the feature in `seriousgaming.sdk.json`:
|
|
474
|
+
|
|
475
|
+
```json
|
|
476
|
+
{
|
|
477
|
+
"requires": ["presentation-overlay"]
|
|
478
|
+
}
|
|
479
|
+
```
|
|
480
|
+
|
|
481
|
+
Listing it means a host that cannot open the deck this way refuses the game rather than running it without the button, so list it only if your session UI offers the control. The deck opens for the current session, on the slide the facilitator left it on.
|
|
482
|
+
|
|
469
483
|
**Prefer the host's print sheets to your own.** A host's sheet carries the brand of the organisation running the session, with its join details in the form the host chose, so offer `'print-sheets'` wherever the host does. Draw your own sheet only where it does not, from [`useSessionUserInterfaceTeamLinks`](#usesessionuserinterfaceteamlinks), and put the host's logo on it with `useBrandLogo()` (see [Theming and branding](./theming-and-branding.md)), so a white-label session never prints your game's identity, or nobody's.
|
|
470
484
|
|
|
471
485
|
### Undoing and resetting
|
|
@@ -516,6 +530,28 @@ const { setWaitingRoom } = useSessionUserInterfaceCallbacks();
|
|
|
516
530
|
|
|
517
531
|
The host provides its own toggle too, so building one is optional. Reach for this when you want the control to sit inside your own facilitator layout, or to pair it with a note you set on a shared capability at the same moment.
|
|
518
532
|
|
|
533
|
+
### Changing the language
|
|
534
|
+
|
|
535
|
+
`setLocale` changes the session's language: the locale every surface is sent, and your logic reads, from then on. It is the change the host's own language picker makes, for a session UI that owns the whole canvas:
|
|
536
|
+
|
|
537
|
+
```typescript
|
|
538
|
+
const meta = useSessionUserInterfaceMeta();
|
|
539
|
+
const { locale } = useSessionUserInterfaceLocale();
|
|
540
|
+
const { setLocale } = useSessionUserInterfaceCallbacks();
|
|
541
|
+
|
|
542
|
+
{meta.canSetLocale && (
|
|
543
|
+
<Select value={locale} onChange={(event) => void setLocale(event.target.value)}>
|
|
544
|
+
<MenuItem value="en">English</MenuItem>
|
|
545
|
+
<MenuItem value="it">Italiano</MenuItem>
|
|
546
|
+
</Select>
|
|
547
|
+
)}
|
|
548
|
+
```
|
|
549
|
+
|
|
550
|
+
- **Gate it on `meta.canSetLocale`.** A host that predates `setLocale` leaves it out, and may never answer the call, so a control shown there would hang
|
|
551
|
+
- **Offer only your `supportedLocales`.** Anything else is refused as `denied`, rather than swapped for the nearest language you do support
|
|
552
|
+
- **Render the locale you are sent**, not the one you asked for. The host's picker changes it too, and the last change wins
|
|
553
|
+
- It takes no `teamId`: the language is the session's
|
|
554
|
+
|
|
519
555
|
### Controlling the roster
|
|
520
556
|
|
|
521
557
|
The session UI owns the roster. Five callbacks create, rename and delete teams, and rename and move participants:
|
|
@@ -810,9 +846,12 @@ Read the session itself:
|
|
|
810
846
|
```typescript
|
|
811
847
|
import { useSessionUserInterfaceMeta } from '@seriousgaming/sdk/ui';
|
|
812
848
|
|
|
813
|
-
const { sessionId, name, readOnly, waitingRoomOpen, joinPin } =
|
|
849
|
+
const { sessionId, name, readOnly, waitingRoomOpen, joinPin, canSetLocale } =
|
|
850
|
+
useSessionUserInterfaceMeta();
|
|
814
851
|
```
|
|
815
852
|
|
|
853
|
+
`canSetLocale` is `true` where the host accepts [`setLocale`](#changing-the-language), and absent on a host that predates it.
|
|
854
|
+
|
|
816
855
|
`joinPin` is the code participants enter to join, or `null` when joining needs none. How joining is secured is up to the runtime, so it need not be a PIN and some runtimes never set it: render it as an opaque string, and hide the panel when it is `null`. `readOnly` marks a frozen session, so a surface can disable its own controls and explain why rather than offering affordances that will be denied. `waitingRoomOpen` is the current value of a flag the session UI can also write through `setWaitingRoom`; since the host usually renders its own waiting-room control too, read the result back rather than assuming your write won.
|
|
817
856
|
|
|
818
857
|
### useSessionUserInterfaceTeamLinks
|
|
@@ -836,7 +875,7 @@ Find out which host overlays this host offers, before rendering a control for on
|
|
|
836
875
|
import { useSessionUserInterfaceHostOverlays } from '@seriousgaming/sdk/ui';
|
|
837
876
|
|
|
838
877
|
const overlays = useSessionUserInterfaceHostOverlays();
|
|
839
|
-
// HostOverlay[]: 'facilitator-guide' | 'print-sheets'
|
|
878
|
+
// HostOverlay[]: 'facilitator-guide' | 'print-sheets' | 'presentation'
|
|
840
879
|
```
|
|
841
880
|
|
|
842
881
|
Empty until the host answers, and empty is also the correct answer for a host that delegates none. It can change mid-session. See [Opening host overlays](#opening-host-overlays).
|
|
@@ -62,7 +62,7 @@ Run `pnpm run sdk new settings` with no JSON to be prompted for each property in
|
|
|
62
62
|
}
|
|
63
63
|
```
|
|
64
64
|
|
|
65
|
-
`settingsSchema` is a full JSON Schema Draft 7 object. Two rules are stricter than for a capability's `variablesSchema`:
|
|
65
|
+
`settingsSchema` is a full JSON Schema Draft 7 object, as every schema a game writes is, read the same way whatever `$schema` it names. Two features of later drafts also work: `$defs` beside `definitions`, and keywords written beside a `$ref` (see [Reuse a shape](#reuse-a-shape-or-nest-it-to-any-depth)). Two rules are stricter than for a capability's `variablesSchema`:
|
|
66
66
|
|
|
67
67
|
- Every property needs a `default`. `new settings`, `update settings` and `sdk build` all refuse a property without one
|
|
68
68
|
- Every default must fit its own schema, at any depth. `sdk build` refuses a string default on a number property, a default outside its range or `enum`, and an object default missing a key its own `required` lists, naming the settings resource and the path. The generated `Settings` type comes from the schema, so the compiler cannot catch a default that disagrees with it
|
|
@@ -70,6 +70,43 @@ Run `pnpm run sdk new settings` with no JSON to be prompted for each property in
|
|
|
70
70
|
|
|
71
71
|
A `required` inside an object-valued property is allowed. It holds the property's `default` to its keys, never a scenario or a setup change: those are partial at every depth, so a scenario or a setup UI may set one key of the object and leave the rest to the layer beneath. An array is the exception: it replaces the one beneath whole, so each item an override supplies must be complete.
|
|
72
72
|
|
|
73
|
+
### Reuse a shape, or nest it to any depth
|
|
74
|
+
|
|
75
|
+
Declare a shape once under `$defs` (or `definitions`) and use it with a `$ref`. A shape may contain itself, which is how recursive data, such as a running order whose items hold items or a rule whose branches are rules, is checked to every depth rather than left as a bare object below the first level:
|
|
76
|
+
|
|
77
|
+
```json
|
|
78
|
+
"settingsSchema": {
|
|
79
|
+
"type": "object",
|
|
80
|
+
"properties": {
|
|
81
|
+
"Agenda": {
|
|
82
|
+
"title": "Agenda",
|
|
83
|
+
"$ref": "#/$defs/agendaItem",
|
|
84
|
+
"default": { "title": "Workshop", "children": [] }
|
|
85
|
+
}
|
|
86
|
+
},
|
|
87
|
+
"$defs": {
|
|
88
|
+
"agendaItem": {
|
|
89
|
+
"type": "object",
|
|
90
|
+
"properties": {
|
|
91
|
+
"title": { "type": "string" },
|
|
92
|
+
"children": { "type": "array", "items": { "$ref": "#/$defs/agendaItem" } }
|
|
93
|
+
},
|
|
94
|
+
"required": ["title", "children"],
|
|
95
|
+
"additionalProperties": false
|
|
96
|
+
}
|
|
97
|
+
},
|
|
98
|
+
"additionalProperties": false
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
- **A reference stays inside its own schema.** It names a part of the settings resource that holds it, as `#/$defs/<name>`. The build refuses one that names nothing, another file, a URL or another resource's schema, pointing at it
|
|
103
|
+
- **Write the `default` beside the `$ref`.** Keywords beside a reference apply with it, so the property's `default`, `title` and `description` go there, and so does a constraint for this use alone, such as a `maximum`
|
|
104
|
+
- **Every check follows it.** The defaults, scenarios, setup and scenario editor writes, [file settings](#settings-that-hold-a-file), [locks](#lock-a-setting) and [guide conditions](./guide.md) all reach through a reference, at every depth
|
|
105
|
+
- **Each use keeps its own rule.** Where the shape is an object setting, a scenario may set one key of it and leave the rest; where it is an array's item, each item must be complete
|
|
106
|
+
- **The generated types name it.** `Agenda` is typed `AgendaItem`, one interface whose `children` are `AgendaItem[]`, exported from `types.ts` for your own code. When two resources a file reads both define the same name, the second is prefixed with its identifier (`EngineRule`)
|
|
107
|
+
|
|
108
|
+
A capability's `variablesSchema` takes `$defs` and `$ref` the same way.
|
|
109
|
+
|
|
73
110
|
### Describe every setting
|
|
74
111
|
|
|
75
112
|
A settings schema is read by more than the build. A hosted runtime's generic settings form, a [scenario editor](./scenario-editor.md), and an AI agent authoring a scenario for your released game all work from it, and an agent can edit a game with no editor UI at all if the schema says what each value means. Give every property:
|
|
@@ -112,6 +149,8 @@ Some values are part of the game's design rather than something to tune: a const
|
|
|
112
149
|
- **Nothing can change a locked value.** The build refuses a scenario that sets it, with `SETTINGS_LOCKED` pointing at the value, even when it sets the same value as your default. A setup screen or scenario editor that changes it is refused as `denied`, with a message naming the setting (`"engine.LowProductionThreshold" is read-only`), and none of that write applies
|
|
113
150
|
- **Sending it back unchanged is fine.** An editor that spreads the settings it was given sends the locked value back as it was, and only what changed is applied, so spreading is still safe
|
|
114
151
|
- **Locking an object locks everything in it.** `readOnly` on an object-valued property fixes every key inside it, at any depth
|
|
152
|
+
- **Lock named properties, or a whole list or map.** A list's items and a map's entries come and go as scenarios add and remove them, so there is no single value of yours for a lock inside one to keep. The build refuses `readOnly` beneath `items`, `additionalProperties` or `patternProperties`; put it on the list or map itself instead
|
|
153
|
+
- **A lock reached through a `$ref` counts.** `readOnly` on a shape under `$defs` locks every named property that uses it (see [Reuse a shape, or nest it to any depth](#reuse-a-shape-or-nest-it-to-any-depth))
|
|
115
154
|
- **Saving a scenario leaves locked values out.** The dev console's Save writes every other setting and drops the locked ones, so the scenario still builds
|
|
116
155
|
- **Editors are not sent the schema.** A setup screen or scenario editor receives the values, not the schema, so show a locked field as read-only yourself, as the factory example's scenario editor does
|
|
117
156
|
- **Adding a lock is a scenario-format change.** A custom scenario saved before the lock may hold a value for it, so bump `scenarioFormat` when you lock a setting a released version left open (see [Scenario format: when to bump it](./scenarios.md#scenario-format-when-to-bump-it))
|
|
@@ -136,6 +175,27 @@ A setting can hold a file, such as a client's logo or a briefing document. Mark
|
|
|
136
175
|
- **The build checks your files.** Every file a package scenario or a default names must be shipped, within `maxBytes`, and of a type `accept` lists, judged from its extension. A `blob:` reference in a package scenario fails the build: it is an upload, which no package can carry
|
|
137
176
|
- **Every write is checked against it.** A setup screen, the scenario editor or an agent sets a file by uploading it first and writing the `blob:` reference it gets back. A reference to a file nobody uploaded, or one too large or of the wrong type, is refused as `denied`, naming the setting. So is anything that is not a reference, a `data:` URI or a URL included
|
|
138
177
|
- **It tells an agent what to upload.** A schema alone says only that the value is a string; `blob` says it is a PNG of up to 512 KB
|
|
178
|
+
- **A map can hold a file per key.** Put `blob` on a map's `additionalProperties` (or a `patternProperties` schema), and every entry is a file setting of its own, checked and named by its key (`brand.Cast.ada`, see [How a setting is named](#how-a-setting-is-named)). A file per language is one such map (see [A file per language](./file-handling.md#a-file-per-language))
|
|
179
|
+
|
|
180
|
+
### How a setting is named
|
|
181
|
+
|
|
182
|
+
A refusal, a lock's message, a `Scenario` gate's problem and a guide's `:setting` all name one value by its setting path: the settings identifier, then each key down to the value.
|
|
183
|
+
|
|
184
|
+
```text
|
|
185
|
+
ui.MinPrice
|
|
186
|
+
brand.Cast.ada.portrait
|
|
187
|
+
engine.Rounds.0.Price
|
|
188
|
+
brand.Cast["a.b"].portrait
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
A plain key, one that is not empty and holds no `.`, `[`, `]`, `"` or space, follows a dot, and so does a list's position. Any other key, such as a map entry named `a.b`, goes in brackets as a JSON string, so the path reads back one way only. Build and read paths with `settingPath` and `parseSettingPath` from `@seriousgaming/sdk` rather than joining keys yourself:
|
|
192
|
+
|
|
193
|
+
```typescript
|
|
194
|
+
import { parseSettingPath, settingPath } from '@seriousgaming/sdk';
|
|
195
|
+
|
|
196
|
+
settingPath('brand', 'Cast', 'a.b', 'portrait'); // 'brand.Cast["a.b"].portrait'
|
|
197
|
+
parseSettingPath('brand.Cast["a.b"].portrait'); // { identifier: 'brand', keys: ['Cast', 'a.b', 'portrait'] }
|
|
198
|
+
```
|
|
139
199
|
|
|
140
200
|
### How to divide settings
|
|
141
201
|
|
|
@@ -402,7 +462,7 @@ Options:
|
|
|
402
462
|
Every override source is validated against the `settingsSchema` of the settings resource it names, scenario overrides and session overrides alike. Neither has to name every property, but both are refused for:
|
|
403
463
|
|
|
404
464
|
- A key naming no settings resource the package declares
|
|
405
|
-
- A property the schema does not declare, such as a misspelling
|
|
465
|
+
- A property the schema does not declare, such as a misspelling. An object that lists `properties` and says nothing else of its keys refuses any key it does not list, whether or not it sets `additionalProperties: false`. A bare `{ "type": "object" }`, or an object with `patternProperties`, an `additionalProperties` schema or `allOf`/`anyOf`/`oneOf`, takes whatever its schema admits, so an object meant to hold any keys, such as a map of triggers, is written that way
|
|
406
466
|
- A value of the wrong type, or outside a `minimum`, `maximum` or `enum`
|
|
407
467
|
- A value the schema locks with `readOnly` (see [Lock a setting](#lock-a-setting))
|
|
408
468
|
|
|
@@ -359,6 +359,15 @@ A session UI's `setData` takes the team id first for a team's own capabilities,
|
|
|
359
359
|
|
|
360
360
|
Always render through these helpers. They supply every context a surface reads, with complete defaults, and each option overrides one value, so a test that needs a particular theme, locale, callback or viewer role passes it as an option. A hand-built provider tree has to supply every callback and every field itself, and it silently stops matching the runtime when the SDK adds one.
|
|
361
361
|
|
|
362
|
+
### What a minor release may change
|
|
363
|
+
|
|
364
|
+
A minor release never breaks a type you build yourself: a logic result, a settings value, a `TeamState` or `SessionMeta` you pass as test data, or the options of a `render*` helper. It may add required members to what the runtime implements for you, and these are outside semantic versioning:
|
|
365
|
+
|
|
366
|
+
- The callbacks a surface is handed: `UserInterfaceCallbacks`, `SessionUserInterfaceCallbacks` and `SettingsEditorCallbacks`
|
|
367
|
+
- The React contexts the SDK exports, such as `UserInterfaceCallbacksContext`
|
|
368
|
+
|
|
369
|
+
Read both through their hooks, and test through the helpers above, which fill in anything new. A test that builds either by hand may stop compiling on a minor upgrade.
|
|
370
|
+
|
|
362
371
|
### Testing controlled inputs
|
|
363
372
|
|
|
364
373
|
For inputs that call `setData` on change, use `fireEvent.change` rather than `userEvent.type`. Because `setData` is mocked, the component's displayed value won't update between keystrokes. `fireEvent.change` fires a single synthetic event with the exact target value, which correctly triggers `onChange`:
|
package/dist/docs/guides/ui.md
CHANGED
|
@@ -569,6 +569,39 @@ Points worth knowing:
|
|
|
569
569
|
- **`teams.defaultNames` becomes a starting point**, not a fixed label, in any
|
|
570
570
|
game that offers this
|
|
571
571
|
|
|
572
|
+
## Letting a participant fix their own name
|
|
573
|
+
|
|
574
|
+
A participant who mistyped their name on joining can change it with `renameSelf`,
|
|
575
|
+
where the host lets them. Whose names are theirs to change is the host's call: a
|
|
576
|
+
guest who typed one usually may, and one whose name comes from a sign-in may not.
|
|
577
|
+
`useUserInterfaceCanRenameSelf()` gives the host's answer for the participant
|
|
578
|
+
using this surface:
|
|
579
|
+
|
|
580
|
+
```typescript
|
|
581
|
+
import {
|
|
582
|
+
useUserInterfaceCallbacks,
|
|
583
|
+
useUserInterfaceCanRenameSelf,
|
|
584
|
+
} from '@seriousgaming/sdk/ui';
|
|
585
|
+
|
|
586
|
+
const canRenameSelf = useUserInterfaceCanRenameSelf();
|
|
587
|
+
const { renameSelf } = useUserInterfaceCallbacks();
|
|
588
|
+
|
|
589
|
+
{canRenameSelf && (
|
|
590
|
+
<Button onClick={() => void renameSelf(draftName)}>Change my name</Button>
|
|
591
|
+
)}
|
|
592
|
+
```
|
|
593
|
+
|
|
594
|
+
- **Show the control only where `canRenameSelf` is `true`.** It is `false` for an
|
|
595
|
+
observer, for a participant whose name the host keeps, and on a host that
|
|
596
|
+
predates `renameSelf`, which may never answer the call
|
|
597
|
+
- **It names nobody.** The host works out who is asking, so a surface can only
|
|
598
|
+
rename its own participant
|
|
599
|
+
- **Render the result, not the request.** A facilitator can rename the same
|
|
600
|
+
participant at the same moment. Read the name back from
|
|
601
|
+
`useUserInterfaceParticipant()`
|
|
602
|
+
- **The host owns the limits**, as for a team name: it trims the name and refuses
|
|
603
|
+
a blank or over-long one as a terminal `denied`
|
|
604
|
+
|
|
572
605
|
## Displaying the tick timer
|
|
573
606
|
|
|
574
607
|
When a game uses an automatic [tick controller](./tick-controller.md), the host pushes the current schedule to every UI via the `useUserInterfaceTimer` hook, as a `TimerState`. Use this when you want your UI to show its own countdown: for example, a circular progress bar in the corner of a Decisions panel, or a floating 'Next tick in 12s' badge on a results screen.
|
|
@@ -671,6 +671,17 @@ A minor release that changes a public type a test may build by hand lists it her
|
|
|
671
671
|
|
|
672
672
|
`Brand.icon` is `{ onLight?, onDark? }`, the shape of `logo`, rather than one URL. Only a `Brand` you build yourself, in a test or a mock, needs the change: replace `icon: 'icon.svg'` with `icon: { onLight: 'icon.svg', onDark: 'icon.svg' }`, or a file for each. The wrapper turns a single icon from an older host into both variants, so a game reading the brand through `useBrandIcon()` needs nothing.
|
|
673
673
|
|
|
674
|
+
### 1.3: let the render helpers build your callbacks
|
|
675
|
+
|
|
676
|
+
`UserInterfaceCallbacks` and `SessionUserInterfaceCallbacks` gain `renameSelf` and `setLocale`. A game reading them through `useUserInterfaceCallbacks()` or `useSessionUserInterfaceCallbacks()` needs nothing. A test that builds a callbacks object by hand and passes it to `UserInterfaceCallbacksContext.Provider` or `SessionUserInterfaceCallbacksContext.Provider` stops compiling. Render the surface with `renderUserInterface` or `renderSessionUserInterface` instead, passing only the callbacks the test checks:
|
|
677
|
+
|
|
678
|
+
```tsx
|
|
679
|
+
const requestTick = vi.fn();
|
|
680
|
+
renderUserInterface(<App />, { callbacks: { requestTick } });
|
|
681
|
+
```
|
|
682
|
+
|
|
683
|
+
These types are outside semantic versioning from 1.3, so the helpers are the way to keep up with later additions too. See [What a minor release may change](./testing.md#what-a-minor-release-may-change).
|
|
684
|
+
|
|
674
685
|
## Before you publish
|
|
675
686
|
|
|
676
687
|
A 1.0 build is a manifest version 3 package, and the platform must accept version 3 before you publish one. Until it does, the platform refuses the upload, and a version 2 package you published from 0.6 keeps running as it is. Check with Business Simulations that the platform you publish to accepts version 3 packages, and keep publishing from 0.6 until it does.
|