@seriousgaming/sdk-tools 1.4.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 +830 -99
- package/dist/client.js +114 -11
- package/dist/dev/console/assets/{index-BvB-LFQZ.js → index-BVF8exas.js} +21 -21
- package/dist/dev/console/index.html +1 -1
- package/dist/dev/public-origins.d.ts +61 -0
- package/dist/dev/shell.d.ts +32 -4
- package/dist/docs/ai-agents.md +5 -0
- package/dist/docs/changelog-0.x.md +2 -2
- package/dist/docs/changelog.md +37 -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/environment-variables.md +10 -5
- package/dist/docs/guides/ai-facilitation.md +2 -0
- package/dist/docs/guides/capabilities.md +2 -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 +2 -0
- package/dist/docs/guides/engine-testing.md +5 -1
- package/dist/docs/guides/engine.md +2 -0
- package/dist/docs/guides/file-handling.md +3 -1
- 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 +4 -2
- 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 +2 -0
- package/dist/docs/guides/scenarios.md +6 -2
- 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 +2 -0
- 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 +2 -0
- 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/use-request-tick.md +2 -2
- package/dist/execution/config-resolver.d.ts +4 -1
- package/dist/runtime/manifest-version.d.ts +1 -1
- package/dist/runtime.js +1 -1
- 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/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
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
6
6
|
<link rel="icon" type="image/svg+xml" href="/assets/icon-CRaj5uhr.svg" />
|
|
7
7
|
<title>Serious Gaming</title>
|
|
8
|
-
<script type="module" crossorigin src="/assets/index-
|
|
8
|
+
<script type="module" crossorigin src="/assets/index-BVF8exas.js"></script>
|
|
9
9
|
<link rel="stylesheet" crossorigin href="/assets/index-q6-lvlN3.css">
|
|
10
10
|
</head>
|
|
11
11
|
<body>
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The addresses a dev server behind a proxy is reached at (#788).
|
|
3
|
+
*
|
|
4
|
+
* The server otherwise names itself from the request: `http://`, the `Host`
|
|
5
|
+
* the browser sent, and the asset or hot-reload port in place of its own. A
|
|
6
|
+
* gateway that serves each origin on its own HTTPS hostname breaks every one
|
|
7
|
+
* of those guesses, so a server behind one is told its addresses instead.
|
|
8
|
+
*/
|
|
9
|
+
export declare const PUBLIC_URL_ENV_VAR = "SERIOUSGAMING_DEV_PUBLIC_URL";
|
|
10
|
+
export declare const PUBLIC_ASSET_URL_ENV_VAR = "SERIOUSGAMING_DEV_PUBLIC_ASSET_URL";
|
|
11
|
+
export declare const PUBLIC_HMR_URL_ENV_VAR = "SERIOUSGAMING_DEV_PUBLIC_HMR_URL";
|
|
12
|
+
/** The origins as given, each already parsed by {@link parsePublicOrigin}. */
|
|
13
|
+
export interface PublicOrigins {
|
|
14
|
+
/** The console, its API and every link a participant is handed. */
|
|
15
|
+
publicUrl?: string;
|
|
16
|
+
/** Game bundles and the files a frame reads. */
|
|
17
|
+
publicAssetUrl?: string;
|
|
18
|
+
/** Vite's hot-reload socket, as `ws:` or `wss:`. */
|
|
19
|
+
publicHmrUrl?: string;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* An origin from a flag or an environment variable, normalised.
|
|
23
|
+
*
|
|
24
|
+
* Only an origin: a path would suggest the server can be mounted under one,
|
|
25
|
+
* and it cannot, since every route it serves is absolute.
|
|
26
|
+
*
|
|
27
|
+
* @throws {CliError} when the value is not an origin of the kind `flag` takes.
|
|
28
|
+
*/
|
|
29
|
+
export declare function parsePublicOrigin(value: string, flag: string, kind: 'http' | 'ws'): string;
|
|
30
|
+
/**
|
|
31
|
+
* The public origins for `sdk dev`: each flag, else its environment variable,
|
|
32
|
+
* parsed. Unset where neither gives one.
|
|
33
|
+
*
|
|
34
|
+
* @throws {CliError} when a value is not an origin.
|
|
35
|
+
*/
|
|
36
|
+
export declare function resolvePublicOrigins(flags: {
|
|
37
|
+
publicUrl?: string;
|
|
38
|
+
publicAssetUrl?: string;
|
|
39
|
+
publicHmrUrl?: string;
|
|
40
|
+
}, env?: NodeJS.ProcessEnv): PublicOrigins;
|
|
41
|
+
/**
|
|
42
|
+
* The asset origin: as given, else the public console's scheme and host on
|
|
43
|
+
* the asset port, which is what a proxy forwarding each port as it is serves.
|
|
44
|
+
* Null when neither is given, so the server goes on naming it from the request.
|
|
45
|
+
*/
|
|
46
|
+
export declare function publicAssetOrigin(origins: PublicOrigins, assetPort: number): string | null;
|
|
47
|
+
/**
|
|
48
|
+
* Where a frame's hot-reload client connects: as given, else the asset
|
|
49
|
+
* origin's host on the Vite port, over `wss:` when the asset origin is HTTPS.
|
|
50
|
+
* That default is where Vite's client connects when told nothing, so it
|
|
51
|
+
* changes only the scheme and the name. Null when no public origin is given.
|
|
52
|
+
*/
|
|
53
|
+
export declare function publicHmrOrigin(origins: PublicOrigins, assetPort: number, vitePort: number): string | null;
|
|
54
|
+
/** What Vite's client is told to connect to, from a `ws:` or `wss:` origin. */
|
|
55
|
+
export declare function hmrClientTarget(origin: string): {
|
|
56
|
+
protocol: 'ws' | 'wss';
|
|
57
|
+
host: string;
|
|
58
|
+
clientPort: number;
|
|
59
|
+
};
|
|
60
|
+
/** The hostnames a public origin names, which Vite must accept in a `Host` header. */
|
|
61
|
+
export declare function publicHostnames(origins: (string | null | undefined)[]): string[];
|
package/dist/dev/shell.d.ts
CHANGED
|
@@ -18,7 +18,14 @@ import type { RunKind } from '@seriousgaming/sdk';
|
|
|
18
18
|
import type { MutationResult } from '@seriousgaming/sdk/projection';
|
|
19
19
|
import type { Command } from '../core/protocol';
|
|
20
20
|
import { Session, type SessionOptions } from '../core/session';
|
|
21
|
-
|
|
21
|
+
import { type PublicOrigins } from './public-origins';
|
|
22
|
+
/**
|
|
23
|
+
* `publicUrl`, `publicAssetUrl` and `publicHmrUrl` are the addresses a server
|
|
24
|
+
* behind a proxy is reached at (#788), each an origin as
|
|
25
|
+
* `parsePublicOrigin` leaves it. Unset, every address is named from the
|
|
26
|
+
* request that asked for it.
|
|
27
|
+
*/
|
|
28
|
+
export interface ShellOptions extends SessionOptions, PublicOrigins {
|
|
22
29
|
port?: number;
|
|
23
30
|
/** Port the Vite HMR socket binds to. Defaults to `port + 1`. */
|
|
24
31
|
vitePort?: number;
|
|
@@ -108,6 +115,8 @@ export declare class DevShell {
|
|
|
108
115
|
private viteFailure;
|
|
109
116
|
/** Serialises the first requests for a surface so they share one Vite. */
|
|
110
117
|
private viteStarting;
|
|
118
|
+
/** The hot-reload socket's own listener, when a public origin moves its client. */
|
|
119
|
+
private hmrServer;
|
|
111
120
|
private port;
|
|
112
121
|
private vitePort;
|
|
113
122
|
private assetPort;
|
|
@@ -171,14 +180,23 @@ export declare class DevShell {
|
|
|
171
180
|
get url(): string;
|
|
172
181
|
/** Where bundles are served from, once listening. */
|
|
173
182
|
get assetUrl(): string;
|
|
183
|
+
/** Where people reach the console, when a proxy stands in front of it. */
|
|
184
|
+
get publicUrl(): string | null;
|
|
185
|
+
/** Where people's browsers load bundles from, when a proxy stands in front. */
|
|
186
|
+
get publicAssetUrl(): string | null;
|
|
174
187
|
/**
|
|
175
|
-
* The asset origin as a client that reached `host` must name it: the
|
|
176
|
-
*
|
|
177
|
-
* address `localhost` would not
|
|
188
|
+
* The asset origin as a client that reached `host` must name it: the
|
|
189
|
+
* public one where given, else the same host on the asset port. A browser
|
|
190
|
+
* on another machine reached us by an address `localhost` would not
|
|
191
|
+
* resolve to on its side.
|
|
178
192
|
*/
|
|
179
193
|
assetOrigin(host: string | undefined): string;
|
|
180
194
|
/** The console's own origin, as a client that reached `host` names it. */
|
|
181
195
|
private consoleOrigin;
|
|
196
|
+
/** Where a frame's hot-reload client connects, when a public origin decides it. */
|
|
197
|
+
private get publicHmrUrl();
|
|
198
|
+
/** What the bundle policy's `connect-src` admits for hot reload. */
|
|
199
|
+
private hmrSources;
|
|
182
200
|
/** The session this shell wraps, for tests and for the CLI in-process path. */
|
|
183
201
|
get runtime(): Session;
|
|
184
202
|
/**
|
|
@@ -222,6 +240,16 @@ export declare class DevShell {
|
|
|
222
240
|
*/
|
|
223
241
|
private ensureVite;
|
|
224
242
|
private createVite;
|
|
243
|
+
/**
|
|
244
|
+
* Vite's server options: its own hot-reload socket on the Vite port, as
|
|
245
|
+
* before, unless a public origin says where the client connects.
|
|
246
|
+
*
|
|
247
|
+
* Vite takes one `host` for both where its socket listens and where its
|
|
248
|
+
* client connects, and a public hostname is no address to listen on. So
|
|
249
|
+
* behind a proxy the socket's listener is opened here, on the Vite port
|
|
250
|
+
* as usual, and Vite only attaches to it.
|
|
251
|
+
*/
|
|
252
|
+
private viteServerOptions;
|
|
225
253
|
private attachSockets;
|
|
226
254
|
private receive;
|
|
227
255
|
/** What one viewer page is owed, now. */
|
package/dist/docs/ai-agents.md
CHANGED
|
@@ -14,10 +14,15 @@ The site describes the newest release. Inside a package, read the docs that ship
|
|
|
14
14
|
|
|
15
15
|
```bash
|
|
16
16
|
pnpm run --silent sdk docs view # the documentation tree
|
|
17
|
+
pnpm run --silent sdk docs view page-index.md # every page: summary and length
|
|
17
18
|
pnpm run --silent sdk docs view recipes/index.md # every recipe, one line each
|
|
19
|
+
pnpm run --silent sdk docs view guides/ui.md --outline # the headings of a page, with section lengths
|
|
20
|
+
pnpm run --silent sdk docs view guides/ui.md --section 'Writing to context' # one section
|
|
18
21
|
pnpm run sdk docs export # copy every page into the package, to search with grep
|
|
19
22
|
```
|
|
20
23
|
|
|
24
|
+
Some guides run past 50,000 characters. Rather than reading one whole, find it in the [page index](./page-index.md), list its headings with `--outline`, and read the section you need with `--section`, which takes a heading's text or the slug the outline prints. Every guide and recipe carries a `**Keywords:**` line, so `grep -rn` over the docs lands on the right page.
|
|
25
|
+
|
|
21
26
|
On the site, [llms.txt](https://sdk.seriousgaming.com/llms.txt) lists every page, [llms-small.txt](https://sdk.seriousgaming.com/llms-small.txt) holds the core pages in one file, and [llms-full.txt](https://sdk.seriousgaming.com/llms-full.txt) holds them all. Start from a recipe for a task and from a guide for a whole subject.
|
|
22
27
|
|
|
23
28
|
## 1. Scaffold without a prompt
|
|
@@ -563,8 +563,8 @@ Work through step 5 of the upgrade guide: it gives the five in order, with the e
|
|
|
563
563
|
### Added
|
|
564
564
|
|
|
565
565
|
- A scenario can configure the session user interface, through a `sessionUserInterfaces` bucket in its `configuration` alongside `modules` and `userInterfaces`. The surface's configuration now resolves through all four layers like any other resource: schema defaults, the game's `sessionUserInterface` reference, the active scenario, then the centralized layer. Session UIs get their own bucket rather than sharing `userInterfaces`, so a player UI and a session UI may carry the same identifier without crossing. See the [session UI guide](guides/session.md#configuring-the-surface)
|
|
566
|
-
- A session user interface can open the host's own overlays with `openHostOverlay()`, so a facilitator does not have to leave the surface to reach the facilitator guide or a team's print sheet. The host still renders them, in its chrome above the surface, and reports which ones it offers through `useSessionUserInterfaceHostOverlays()`. Render a control only for an overlay in that list: a production host and the dev server do not offer the same set. See the [session UI guide](guides/session.md#opening-host-overlays)
|
|
567
|
-
- `extendTick(seconds)` moves the deadline of the currently scheduled tick from a session user interface, so 'give them two more minutes' no longer means pausing the timer and remembering to resume it. It moves that one window: the interval your tick controller returns for later ticks is untouched, a negative value pulls the deadline in, and the adjustment reads back as `extendedMs` on the team's timer. See the [session UI guide](guides/session.md#extending-a-tick)
|
|
566
|
+
- A session user interface can open the host's own overlays with `openHostOverlay()`, so a facilitator does not have to leave the surface to reach the facilitator guide or a team's print sheet. The host still renders them, in its chrome above the surface, and reports which ones it offers through `useSessionUserInterfaceHostOverlays()`. Render a control only for an overlay in that list: a production host and the dev server do not offer the same set. See the [session UI guide](guides/session-game-flow.md#opening-host-overlays)
|
|
567
|
+
- `extendTick(seconds)` moves the deadline of the currently scheduled tick from a session user interface, so 'give them two more minutes' no longer means pausing the timer and remembering to resume it. It moves that one window: the interval your tick controller returns for later ticks is untouched, a negative value pulls the deadline in, and the adjustment reads back as `extendedMs` on the team's timer. See the [session UI guide](guides/session-game-flow.md#extending-a-tick)
|
|
568
568
|
- The dev server serves team print sheets at `/print-sheets`, one card per team with its join and observe URLs behind a print stylesheet. Print every team from the session menu, or one team from its card's own menu; a session UI reaches both through `openHostOverlay('print-sheets', teamId?)`. The sheets carry no QR code and no PIN, because the dev server has neither; a production host prints both
|
|
569
569
|
- A game can start its sessions with the waiting room already open, by setting `"openOnStart": true` on its `waitingRoom` reference. Without it the room is closed at the start, so the first player to follow a join link lands in the game rather than the holding screen unless the facilitator opened the room first. It seeds the session and nothing more: the facilitator owns the flag from then on, a reset does not re-park the session, and a dev server restart restores the flag the session was left with. Available to a game that authors its own waiting room UI. See the [waiting room guide](guides/waiting-room.md#starting-held)
|
|
570
570
|
- `new`, `update` and `delete` accept `-j, --json`, matching every other command in the CLI. The envelope names the command, the resource type, the identifier, and every file, reference and directory the operation touched; a failure reports the same shape with `"success": false` and an `error`, and exits non-zero. Because prompts cannot produce JSON, `new` and `update` need a definition or a `--patch` under the flag, and `delete` needs `--force`. See the [CLI reference](cli-reference.md#json-output)
|
package/dist/docs/changelog.md
CHANGED
|
@@ -31,6 +31,39 @@ are in the [0.x changelog](changelog-0.x.md).
|
|
|
31
31
|
|
|
32
32
|
## [Unreleased]
|
|
33
33
|
|
|
34
|
+
## [1.5.0] — 2026-10-29
|
|
35
|
+
|
|
36
|
+
### Added
|
|
37
|
+
|
|
38
|
+
- **`sdk dev` can run behind a proxy or gateway.** `--public-url`, `--public-asset-url` and `--public-hmr-url` (or `SERIOUSGAMING_DEV_PUBLIC_URL`, `SERIOUSGAMING_DEV_PUBLIC_ASSET_URL` and `SERIOUSGAMING_DEV_PUBLIC_HMR_URL`) name the addresses people reach it at, and every link and origin the server hands out uses them, where join links used to read `http://localhost:<port>`. With none set, nothing changes. See [Embedding the dev server](cli-and-dev-server.md#embedding-the-dev-server)
|
|
39
|
+
- **A page framing the dev console can set its colour scheme and brand.** Open it with `?scheme=light|dark|system` or `?brand=<id>`, or post `{ type: 'sg-dev-scheme', scheme }` to the frame to change the scheme without a reload. Neither overwrites the viewer's own stored choice, and the scheme reaches the game's surfaces as the dev drawer's does
|
|
40
|
+
- **The starter game has a presentation.** `new package` now writes Lemonade Stand with a `presentation/` slot: a title slide, a slide for each day with the forecast and how the room did the day before, and a results slide for the room. It shows the room rather than any stall by name, with each stall's figures in the speaker notes, renders with no session, and tests its figures as plain functions. See [A tour of the starter game](guides/starter-game.md#presentation)
|
|
41
|
+
- **A guide to designing screens.** [Designing screens](guides/designing-screens.md) sets out what a good simulation screen looks like whatever the brand: one main action, a spacing and type scale, a design for the phone, laptop or projector it is used on, every state from empty to end of game, feedback on a refused write, accessibility, and an identity of the game's own over the host's theme. New packages put it to work: `DESIGN.md.liquid` replaces the 'User interfaces' prompts with a screen brief (who plays and on what, tone, key screens and each one's main action, layout, states and identity), and `CLAUDE.md.template` asks for the brief before a surface is built and a check at phone and desktop size after. An existing package can copy both sections from the templates shipped in `@seriousgaming/sdk-tools`
|
|
42
|
+
- **Read a long page a section at a time.** `pnpm run sdk docs view <page> --outline` lists a page's headings, each with its slug and its section's length in characters, and `--section <heading>` prints only that section, named by its text or its slug. Both work with `--json`, and an unknown section fails with `DOCS_SECTION_NOT_FOUND`, listing the ones the page has. The installed docs gain `page-index.md`, every page with a one-sentence summary and its length, and every guide now carries a `**Keywords:**` line for `grep`. A new package's `CLAUDE.md` (`CLAUDE.md.template`) points to all three; merge its Documentation section into an existing package's. See [Read the docs for the installed version](ai-agents.md#read-the-docs-for-the-installed-version)
|
|
43
|
+
- **`pnpm run sdk screenshot <path>` captures a surface as a PNG**, as a participant sees it, once the surface reports its first paint rather than after a fixed delay. `--width` and `--height` set the viewport, `--scheme`, `--brand` and `--locale` what it shows, and `--full-page` its whole height; `--json` also lists the page's console errors, failed requests and uncaught exceptions, from inside the surface's frame too. It uses the running dev server, or starts one for the capture and stops it after. It drives the game's own Playwright, an optional peer of `@seriousgaming/sdk-tools` that every scaffolded game already has: without it, or without its Chromium, it fails with `BROWSER_MISSING`, and a surface that never renders fails with `SURFACE_NOT_RENDERED`. The starter's `CLAUDE.md.template` now tells agents to screenshot each screen at phone and desktop size. See [Screenshot a surface](recipes/screenshot-a-surface.md)
|
|
44
|
+
|
|
45
|
+
### Changed
|
|
46
|
+
|
|
47
|
+
- **A new game installs under a seven-day release-age policy.** `pnpm run sdk new package` writes `minimumReleaseAge: 10080` into the game's `pnpm-workspace.yaml`, the policy the SDK itself builds under, so pnpm refuses any dependency published in the last week and picks the newest older release in its range instead. The SDK's own packages (`@seriousgaming/*`) are exempt, so a game scaffolded on the day of an SDK release still installs. An existing game is unchanged: to opt in, copy `minimumReleaseAge` and `minimumReleaseAgeExclude`, with their comment, from the scaffold template `templates/package/pnpm-workspace.yaml.template` in the installed `@seriousgaming/sdk-tools` into your `pnpm-workspace.yaml`
|
|
48
|
+
- **A game with a default scenario always runs on a scenario.** Asking for none, with `pnpm run sdk scenario none`, `createTestSession({ scenarioId: null })` or a hosted runtime's equivalent, is refused with an error naming the default, where it used to run the game on its settings defaults alone, and the dev drawer's **Scenario** tab offers **None** only to a game with no default. If an engine test passes `scenarioId: null` to a game with a default, pin one of its scenarios instead. A game with no default runs on none as before. See [Scenarios](guides/scenarios.md)
|
|
49
|
+
- **The user interface and session UI guides are split into topic pages.** [Building user interfaces](guides/ui.md) and [Building session UIs](guides/session.md) keep their paths as entry pages that link to the rest: participants, ticks and the timer, styling, and files and LLMs for a game UI; running the game and the hooks reference for a session UI. A link to a section that moved needs its new page. The `docs view --section` examples in `CLAUDE.md.template` and the hook pointer in `workflow-create-user-interface.md` follow the new pages
|
|
50
|
+
|
|
51
|
+
- **The starter game's screens are redesigned to the [Designing screens](guides/designing-screens.md) guide.** A game made with `new package` now:
|
|
52
|
+
- Leads each participant screen with the day's decision, with the button that opens the stall in a bar at the foot of the layout and a timeline for looking back at earlier days
|
|
53
|
+
- Gives the facilitator one line of session controls, a card per stall, a side panel with no backdrop for managing one, results for the room, and join links in large type for the room to read
|
|
54
|
+
- Lets the facilitator hold the room at a day: a shared `pacing` capability, enforced by a `RequestTick` gate in `validators/daylimit`
|
|
55
|
+
- Takes its icons from `@mui/icons-material`, keeps its one drawn motif (the awning) and the host's logo in a new `shared/` folder, and lists `presentation-overlay` in `requires`, so the facilitator can open the slides from their screen
|
|
56
|
+
|
|
57
|
+
An existing game is unchanged. See [A tour of the starter game](guides/starter-game.md)
|
|
58
|
+
|
|
59
|
+
### Fixed
|
|
60
|
+
|
|
61
|
+
- **The starter game's facilitator screen shows the purse in pounds.** Lemonade Stand holds money in pence, and its session screen showed a purse of 2,200 pence as '£2,200' where the player's screen showed '£22.00'. A game made from an earlier starter can copy `money` from `ui/src/format.ts` into `session/src/format.ts`; the new starter keeps one copy, in `shared/format.ts`
|
|
62
|
+
|
|
63
|
+
### Security
|
|
64
|
+
|
|
65
|
+
- **The `fast-uri` advisories are cleared.** The SDK's lockfile now takes `fast-uri` 3.1.9 through `ajv`. `body-parser` 2.4.0, through `express` in the dev server, clears the seven-day gate later on 29 October and is taken by the next release; a game's own install already resolves it once it is old enough
|
|
66
|
+
|
|
34
67
|
## [1.4.0] — 2026-10-26
|
|
35
68
|
|
|
36
69
|
### Added
|
|
@@ -60,9 +93,9 @@ are in the [0.x changelog](changelog-0.x.md).
|
|
|
60
93
|
|
|
61
94
|
### Added
|
|
62
95
|
|
|
63
|
-
- **A session UI can open the presentation.** `openHostOverlay('presentation')` opens your deck for the current session in the host's own chrome, usually in a window the facilitator can put on the projector. List `presentation-overlay` in `requires` to be offered it, and show the button only where `useSessionUserInterfaceHostOverlays()` includes `'presentation'`. `examples/factory` has one. See [Opening host overlays](guides/session.md#opening-host-overlays)
|
|
64
|
-
- **A session UI can change the session's language** with `setLocale(locale)`, where `useSessionUserInterfaceMeta().canSetLocale` is `true`. A locale your game does not support is refused. See [Changing the language](guides/session.md#changing-the-language)
|
|
65
|
-
- **A participant can fix their own name** with `renameSelf(name)` from a game or waiting room UI, where `useUserInterfaceCanRenameSelf()` is `true`. The host decides whose names are theirs to change. See [Letting a participant fix their own name](guides/ui.md#letting-a-participant-fix-their-own-name)
|
|
96
|
+
- **A session UI can open the presentation.** `openHostOverlay('presentation')` opens your deck for the current session in the host's own chrome, usually in a window the facilitator can put on the projector. List `presentation-overlay` in `requires` to be offered it, and show the button only where `useSessionUserInterfaceHostOverlays()` includes `'presentation'`. `examples/factory` has one. See [Opening host overlays](guides/session-game-flow.md#opening-host-overlays)
|
|
97
|
+
- **A session UI can change the session's language** with `setLocale(locale)`, where `useSessionUserInterfaceMeta().canSetLocale` is `true`. A locale your game does not support is refused. See [Changing the language](guides/session-game-flow.md#changing-the-language)
|
|
98
|
+
- **A participant can fix their own name** with `renameSelf(name)` from a game or waiting room UI, where `useUserInterfaceCanRenameSelf()` is `true`. The host decides whose names are theirs to change. See [Letting a participant fix their own name](guides/ui-participants.md#letting-a-participant-fix-their-own-name)
|
|
66
99
|
- **A deck can show the room how to join.** A presentation's `session` carries every team's `participants`, a `joinLinks` entry per team and the session's `joinPin`, so a slide can put the join links on the projector and count who has arrived. See [Showing the room how to join](guides/presentation.md#showing-the-room-how-to-join)
|
|
67
100
|
- **`renderUserInterface` takes `canRenameSelf`**, and `renderSessionUserInterface`'s `sessionMeta` takes `canSetLocale`, for testing these controls
|
|
68
101
|
|
|
@@ -260,7 +293,7 @@ are in the [0.x changelog](changelog-0.x.md).
|
|
|
260
293
|
- **`failure.retry()` on `useMutationReporter`** after a `conflict`, for a person-initiated 'Try again'
|
|
261
294
|
- **Typed session writes and test fixtures.** A session UI's generated `types.ts` adds `TeamWrites`, the team-scope capabilities in its `writes`, and `useSessionUserInterfaceData<SessionData, Settings, SharedWrites, TeamWrites>()` types the per-team `setData(teamId, update)` with it, so a team write naming a shared capability fails to compile. `createMockTeamState<TeamContext>`, `createMockSharedState<SharedContext>` and `renderSessionUserInterface<SessionData>` type a test's fixtures the same way. Every parameter defaults to today's untyped form, so existing code compiles unchanged. See [Session UIs](guides/testing.md#session-uis)
|
|
262
295
|
- **A session UI can delete keys.** Both forms of a session surface's `setData` take `{ deletes }` last, as a player surface's does: `setData(teamId, {}, { deletes })` removes from one team and `setData({}, { deletes })` from the shared store. Each path must fall under a capability the surface writes, of the form's scope, or the write is refused as `denied`. `mergingSetData` in `@seriousgaming/sdk/ui/testing` takes the same options and applies them after the merge, as the host does. See [Removing a key](guides/session.md#removing-a-key)
|
|
263
|
-
- **A session UI can delete an empty team** with `callbacks.deleteTeam(teamId)` in an independent session, once its participants have been moved out. The index is left as a gap, and undo never brings the team back. The dev console has a Delete team button. See [Deleting a team](guides/session.md#deleting-a-team)
|
|
296
|
+
- **A session UI can delete an empty team** with `callbacks.deleteTeam(teamId)` in an independent session, once its participants have been moved out. The index is left as a gap, and undo never brings the team back. The dev console has a Delete team button. See [Deleting a team](guides/session-game-flow.md#deleting-a-team)
|
|
264
297
|
- **`pauseTimer` and `resumeTimer` are awaitable**, resolving once the host has applied the change and rejecting with a `MutationError` when it refuses
|
|
265
298
|
- **Every past-state entry carries `index` and `name`**, and the mode-colour theme types (`UserInterfaceModeColors` and siblings) are exported
|
|
266
299
|
|
|
@@ -80,6 +80,64 @@ can move it to any corner (remembered per browser).
|
|
|
80
80
|
Everything the drawer does, the CLI does too, because both send the same
|
|
81
81
|
commands.
|
|
82
82
|
|
|
83
|
+
## Embedding the dev server
|
|
84
|
+
|
|
85
|
+
On your own machine, the server works out every address it hands out from the
|
|
86
|
+
request: the host your browser used, `http://`, and its own ports. Behind a
|
|
87
|
+
proxy or gateway, such as a sandbox that serves the console on an HTTPS
|
|
88
|
+
hostname and shows it in a frame, those addresses come out wrong, and join
|
|
89
|
+
links read `http://localhost:47100/team/1/join`. Tell the server where it is
|
|
90
|
+
reached instead:
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
pnpm run sdk dev --no-open \
|
|
94
|
+
--public-url https://console.example.com \
|
|
95
|
+
--public-asset-url https://assets.example.com \
|
|
96
|
+
--public-hmr-url wss://hmr.example.com
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
| Option | Environment variable | What it names | Default when unset |
|
|
100
|
+
| -------------------- | ------------------------------------ | ------------------------------------------------- | ------------------------------------------------------------------------ |
|
|
101
|
+
| `--public-url` | `SERIOUSGAMING_DEV_PUBLIC_URL` | The console, its API, and every link it hands out | The request's host |
|
|
102
|
+
| `--public-asset-url` | `SERIOUSGAMING_DEV_PUBLIC_ASSET_URL` | Where browsers load game surfaces and their files | The `--public-url` host on the asset port, else the request's host |
|
|
103
|
+
| `--public-hmr-url` | `SERIOUSGAMING_DEV_PUBLIC_HMR_URL` | Where a surface's hot-reload client connects | The public asset host on the Vite port, `wss://` when that host is HTTPS |
|
|
104
|
+
|
|
105
|
+
Each takes an origin only: a scheme, a host and, where it is not the default,
|
|
106
|
+
a port, with no path. The asset origin must differ from the console's, as it
|
|
107
|
+
does in production, so a game's code cannot call the console's API. A gateway
|
|
108
|
+
that serves each port on its own hostname needs all three set; one that keeps
|
|
109
|
+
the ports and adds TLS needs only `--public-url`. With none set, nothing
|
|
110
|
+
changes.
|
|
111
|
+
|
|
112
|
+
The server still listens on the ports it prints, so point the gateway at those:
|
|
113
|
+
the console's port, the asset port, and the Vite port for hot reload.
|
|
114
|
+
|
|
115
|
+
### Colour scheme and brand
|
|
116
|
+
|
|
117
|
+
The console keeps its colour scheme and brand in its own browser storage,
|
|
118
|
+
which a page on another origin cannot write. So the framing page says what it
|
|
119
|
+
wants in the console's URL:
|
|
120
|
+
|
|
121
|
+
- `?scheme=light`, `?scheme=dark` or `?scheme=system`: the colour scheme
|
|
122
|
+
- `?brand=<id>`: one of the brands the server offers, by the identifier its
|
|
123
|
+
**Brand** menu shows
|
|
124
|
+
|
|
125
|
+
Both apply from the first paint, last for the rest of that tab as the console
|
|
126
|
+
moves between its own pages, and never overwrite the viewer's stored choice.
|
|
127
|
+
Picking a scheme or brand in the dev drawer takes over from them. The scheme
|
|
128
|
+
reaches the game's surfaces exactly as the drawer's own scheme menu does.
|
|
129
|
+
|
|
130
|
+
To change the scheme later without a reload, post a message to the frame:
|
|
131
|
+
|
|
132
|
+
```ts
|
|
133
|
+
frame.contentWindow?.postMessage({ type: 'sg-dev-scheme', scheme: 'dark' }, consoleOrigin);
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
The console acts on it only when it is framed, and only from the page directly
|
|
137
|
+
around it. It does not check that page's origin, so any page that frames the
|
|
138
|
+
console can change its scheme: harmless for a colour scheme, and the reason the
|
|
139
|
+
message carries nothing else.
|
|
140
|
+
|
|
83
141
|
## How a command finds the session
|
|
84
142
|
|
|
85
143
|
`.seriousgaming-sdk/session.json` is a **lock file**, not state:
|
|
@@ -11,10 +11,10 @@ The codes are the contract: branch on the code, never on the message. A code is
|
|
|
11
11
|
| Exit code | Category | Meaning | Codes |
|
|
12
12
|
| --------- | ------------- | ------------------- | ----- |
|
|
13
13
|
| 1 | `internal` | Internal error | 1 |
|
|
14
|
-
| 2 | `usage` | Usage error |
|
|
14
|
+
| 2 | `usage` | Usage error | 16 |
|
|
15
15
|
| 3 | `package` | Invalid package | 32 |
|
|
16
|
-
| 4 | `refused` | Refused by the game |
|
|
17
|
-
| 5 | `environment` | Environment |
|
|
16
|
+
| 4 | `refused` | Refused by the game | 12 |
|
|
17
|
+
| 5 | `environment` | Environment | 19 |
|
|
18
18
|
|
|
19
19
|
## Codes
|
|
20
20
|
|
|
@@ -40,6 +40,7 @@ A code marked as a diagnostic also appears in a failure's `diagnostics`, one fin
|
|
|
40
40
|
| `PROMPT_REQUIRED` | The command would have to ask a question, and prompts are off: there is no terminal, --json or SERIOUSGAMING_JSON is set, or CI is set. | |
|
|
41
41
|
| `INPUT_INVALID` | Input given to the command is not valid JSON, or does not match the shape it must have. | |
|
|
42
42
|
| `FILE_NOT_FOUND` | A file named on the command line does not exist or cannot be read. | |
|
|
43
|
+
| `DOCS_SECTION_NOT_FOUND` | The page `docs view --section` reads has no heading by that name; the details list the ones it has. | |
|
|
43
44
|
| `RESOURCE_TYPE_UNKNOWN` | The resource type does not exist, or does not support this operation. | |
|
|
44
45
|
| `RESOURCE_NOT_FOUND` | The package has no resource of that type with that identifier. | |
|
|
45
46
|
| `RESOURCE_EXISTS` | A resource with that identifier, or in that slot, already exists. | |
|
|
@@ -85,42 +86,44 @@ A code marked as a diagnostic also appears in a failure's `diagnostics`, one fin
|
|
|
85
86
|
|
|
86
87
|
### Exit 4: refused by the game
|
|
87
88
|
|
|
88
|
-
| Code
|
|
89
|
-
|
|
|
90
|
-
| `REFUSED_DENIED`
|
|
91
|
-
| `REFUSED_VALIDATION`
|
|
92
|
-
| `REFUSED_CONFLICT`
|
|
93
|
-
| `REFUSED_SUPERSEDED`
|
|
94
|
-
| `TICK_FAILED`
|
|
95
|
-
| `SESSION_ERROR`
|
|
96
|
-
| `INVALID_REQUEST`
|
|
97
|
-
| `HANDLER_ERROR`
|
|
98
|
-
| `INVALID_RESPONSE`
|
|
99
|
-
| `LOGIC_ERROR`
|
|
100
|
-
| `
|
|
89
|
+
| Code | When | Also a diagnostic |
|
|
90
|
+
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
|
|
91
|
+
| `REFUSED_DENIED` | The session refused the command (the 'denied' outcome). | |
|
|
92
|
+
| `REFUSED_VALIDATION` | A validator rejected the write (the 'validation-rejected' outcome). error.details.rejections lists why. | |
|
|
93
|
+
| `REFUSED_CONFLICT` | The write conflicted with a concurrent tick (the 'conflict' outcome). | |
|
|
94
|
+
| `REFUSED_SUPERSEDED` | The write arrived after the tick it was for (the 'superseded' outcome). | |
|
|
95
|
+
| `TICK_FAILED` | The tick failed, usually because game logic threw (the 'tick-failed' outcome). | |
|
|
96
|
+
| `SESSION_ERROR` | The session failed the command unexpectedly (the 'error' outcome). | |
|
|
97
|
+
| `INVALID_REQUEST` | The endpoint request failed its requestSchema, so the handler did not run. | |
|
|
98
|
+
| `HANDLER_ERROR` | The endpoint's handler threw, or ran past its execution bound. | |
|
|
99
|
+
| `INVALID_RESPONSE` | What the endpoint's handler returned broke its declaration. | |
|
|
100
|
+
| `LOGIC_ERROR` | Game logic (an engine, hook, endpoint, validator or tick controller) threw. A diagnostic, not an error code: it sits in `diagnostics` under the command's TICK_FAILED, SESSION_ERROR or HANDLER_ERROR, with the file, line and column it threw at. | Yes |
|
|
101
|
+
| `SURFACE_NOT_RENDERED` | `sdk screenshot` gave up on the page: its surface did not connect, or did not report its first paint before the timeout. error.details carries the page's console errors, failed requests and uncaught exceptions. | |
|
|
102
|
+
| `SETTINGS_STALE` | The package changed on disk since the session started in a way that applies only at initialisation (a setting, a manifest field such as `teams`, or a capability removed or moved to another scope), so a command that advances or changes play was refused. Run `sdk init`. | |
|
|
101
103
|
|
|
102
104
|
### Exit 5: environment
|
|
103
105
|
|
|
104
|
-
| Code | When
|
|
105
|
-
| ------------------------- |
|
|
106
|
-
| `NO_SESSION` | No dev server is running for this package, and the command will not start one.
|
|
107
|
-
| `SESSION_STALE` | The running session was started from an out-of-date package and must restart.
|
|
108
|
-
| `LOCK_HELD` | A dev server is already running for this package.
|
|
109
|
-
| `PORT_IN_USE` | No free port was found to listen on.
|
|
110
|
-
| `DEV_SERVER_OUTDATED` | The running dev server does not understand the command: it is older than this CLI. Restart it.
|
|
111
|
-
| `DEV_SERVER_UNREACHABLE` | The dev server the lock file names does not answer.
|
|
112
|
-
| `DEV_SERVER_UNRESPONSIVE` | A dev server holds the lock and accepts connections but does not answer, most often because logic is stuck in a synchronous loop. Run `sdk dev stop`.
|
|
113
|
-
| `DEV_SERVER_START_FAILED` | A dev server could not be started.
|
|
114
|
-
| `DEV_SERVER_STOP_FAILED` | The dev server could not be stopped.
|
|
115
|
-
| `
|
|
116
|
-
| `
|
|
117
|
-
| `
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
120
|
-
| `
|
|
121
|
-
| `
|
|
122
|
-
| `
|
|
123
|
-
| `
|
|
106
|
+
| Code | When | Also a diagnostic |
|
|
107
|
+
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
|
|
108
|
+
| `NO_SESSION` | No dev server is running for this package, and the command will not start one. | |
|
|
109
|
+
| `SESSION_STALE` | The running session was started from an out-of-date package and must restart. | |
|
|
110
|
+
| `LOCK_HELD` | A dev server is already running for this package. | |
|
|
111
|
+
| `PORT_IN_USE` | No free port was found to listen on. | |
|
|
112
|
+
| `DEV_SERVER_OUTDATED` | The running dev server does not understand the command: it is older than this CLI. Restart it. | |
|
|
113
|
+
| `DEV_SERVER_UNREACHABLE` | The dev server the lock file names does not answer. | |
|
|
114
|
+
| `DEV_SERVER_UNRESPONSIVE` | A dev server holds the lock and accepts connections but does not answer, most often because logic is stuck in a synchronous loop. Run `sdk dev stop`. | |
|
|
115
|
+
| `DEV_SERVER_START_FAILED` | A dev server could not be started. | |
|
|
116
|
+
| `DEV_SERVER_STOP_FAILED` | The dev server could not be stopped. | |
|
|
117
|
+
| `BROWSER_MISSING` | `sdk screenshot` found no Playwright in the package's dependencies, or no Chromium installed for it. Add `@playwright/test` and run `pnpm exec playwright install chromium`. | |
|
|
118
|
+
| `LLM_NOT_CONFIGURED` | Logic called generateText, and the dev server or in-process session running it has no platform API key configured. | |
|
|
119
|
+
| `PLATFORM_UNREACHABLE` | The Serious Gaming platform could not be reached. | |
|
|
120
|
+
| `PLATFORM_UNAUTHORISED` | The platform refused the API key, or its holder lacks the role the call needs. | |
|
|
121
|
+
| `PLATFORM_ERROR` | The platform failed the request. | |
|
|
122
|
+
| `API_KEY_MISSING` | No API key is configured: set SERIOUSGAMING_API_KEY, add it to .env, or pass --api-key. | |
|
|
123
|
+
| `INSTALL_FAILED` | Installing a new package's dependencies failed. | |
|
|
124
|
+
| `SDK_INCOMPLETE` | This install of the SDK tools is missing files it ships with, such as its docs. | |
|
|
125
|
+
| `SETTINGS_FILE_INVALID` | The global settings file (~/.seriousgaming-sdk/config.json) cannot be parsed. | |
|
|
126
|
+
| `WRITE_FAILED` | A file or directory could not be written, moved or removed. | |
|
|
124
127
|
|
|
125
128
|
## Diagnostic codes
|
|
126
129
|
|
|
@@ -1641,7 +1641,7 @@ Open or close the session waiting room.
|
|
|
1641
1641
|
pnpm run sdk scenario [identifier] [options]
|
|
1642
1642
|
```
|
|
1643
1643
|
|
|
1644
|
-
Activate a scenario, or `none` to run on the settings defaults.
|
|
1644
|
+
Activate a scenario, or `none` to run on the settings defaults when no scenario is the default.
|
|
1645
1645
|
|
|
1646
1646
|
| Option | Default | Description |
|
|
1647
1647
|
| -------------------------- | --------------------- | ----------------------------------------------------- |
|
|
@@ -1740,7 +1740,7 @@ pnpm run sdk reset --walkthrough # back to tick 0
|
|
|
1740
1740
|
|
|
1741
1741
|
The run is built the first time something asks for it, so there is nothing to create. In `sdk dev` it is also a surface, at `/walkthrough`, listed in the drawer's Surfaces tab.
|
|
1742
1742
|
|
|
1743
|
-
Your logic reads `meta.runKind` and your surfaces read `useRunKind()` to tell the two apart. See [Engines](./guides/engine.md#walkthroughs) and [User interfaces](./guides/ui.md#walkthroughs).
|
|
1743
|
+
Your logic reads `meta.runKind` and your surfaces read `useRunKind()` to tell the two apart. See [Engines](./guides/engine.md#walkthroughs) and [User interfaces](./guides/ui-participants.md#walkthroughs).
|
|
1744
1744
|
|
|
1745
1745
|
### Upload a blob
|
|
1746
1746
|
|
|
@@ -1973,23 +1973,26 @@ pnpm run sdk dev [options]
|
|
|
1973
1973
|
|
|
1974
1974
|
Start the Serious Gaming development server with hot reload.
|
|
1975
1975
|
|
|
1976
|
-
| Option
|
|
1977
|
-
|
|
|
1978
|
-
| `-w, --working-dir [PATH]`
|
|
1979
|
-
| `-p, --port [PORT]`
|
|
1980
|
-
| `--vite-port [VITE_PORT]`
|
|
1981
|
-
| `--asset-port [ASSET_PORT]`
|
|
1982
|
-
| `--no-open`
|
|
1983
|
-
| `--api-key [KEY]`
|
|
1984
|
-
| `--host [URL]`
|
|
1985
|
-
| `--lan`
|
|
1986
|
-
| `--teams [NUMBER]`
|
|
1987
|
-
| `--participants [COUNT]`
|
|
1988
|
-
| `--scenario [ID]`
|
|
1989
|
-
| `--fake-clock`
|
|
1990
|
-
| `--reinit-on-change`
|
|
1991
|
-
| `--isolated`
|
|
1992
|
-
| `--brand <FILE>`
|
|
1976
|
+
| Option | Default | Description |
|
|
1977
|
+
| ----------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1978
|
+
| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in. |
|
|
1979
|
+
| `-p, --port [PORT]` | `3000` | Port to run the dev server on, or auto for any free port (can also be set via SERIOUSGAMING_DEV_PORT env var or .env file). |
|
|
1980
|
+
| `--vite-port [VITE_PORT]` | | Port to run the Vite dev server on (defaults to PORT + 1). |
|
|
1981
|
+
| `--asset-port [ASSET_PORT]` | | Port game UI bundles and their assets are served from, which is a separate origin from the console (defaults to the next free port after the Vite port). |
|
|
1982
|
+
| `--no-open` | | Do not automatically open browser. |
|
|
1983
|
+
| `--api-key [KEY]` | | Serious Gaming platform API key for LLM calls (can also be set via SERIOUSGAMING_API_KEY env var or .env file). |
|
|
1984
|
+
| `--host [URL]` | | Serious Gaming platform origin for LLM calls (can also be set via SERIOUSGAMING_API_HOST env var or .env file). |
|
|
1985
|
+
| `--lan` | | Listen on every network interface, so phones and tablets on the same network can connect (localhost only by default). |
|
|
1986
|
+
| `--teams [NUMBER]` | | Number of teams to simulate (each accessible at `/team/<n>);` omit to use the game's teams.min. |
|
|
1987
|
+
| `--participants [COUNT]` | | Participants to seed each team with, zero or more, or one per team as 3,0,2 (defaults to 1). |
|
|
1988
|
+
| `--scenario [ID]` | | Scenario identifier to activate (uses default scenario if omitted). |
|
|
1989
|
+
| `--fake-clock` | | Run on a clock that moves only when `sdk clock advance` moves it, to test automatic ticks without waiting. |
|
|
1990
|
+
| `--reinit-on-change` | | Restart the game at tick 0 whenever an edit applies only at initialisation (a setting, a manifest field such as teams, a capability removed or rescoped), rather than recording it as pending once play is under way. |
|
|
1991
|
+
| `--isolated` | | Run beside any dev server already running for this package, for tests and recordings: no lock file (CLI commands reach it through SERIOUSGAMING_DEV_URL), configuration from the package alone, and uploads in a temporary directory. |
|
|
1992
|
+
| `--brand <FILE>` | | A brand file to preview the game in, added to the brand picker and selected; repeat for more than one. |
|
|
1993
|
+
| `--public-url <ORIGIN>` | | The origin people reach the console at, when a proxy or gateway stands in front of the server; used for every link the server prints or hands out (can also be set via SERIOUSGAMING_DEV_PUBLIC_URL). |
|
|
1994
|
+
| `--public-asset-url <ORIGIN>` | | The origin browsers load game surfaces from behind that proxy, which must differ from the console's (defaults to the --public-url host on the asset port; can also be set via SERIOUSGAMING_DEV_PUBLIC_ASSET_URL). |
|
|
1995
|
+
| `--public-hmr-url <ORIGIN>` | | The origin a surface's hot-reload client connects to behind that proxy, as wss:// or ws:// (defaults to the public asset host on the Vite port; can also be set via SERIOUSGAMING_DEV_PUBLIC_HMR_URL). |
|
|
1993
1996
|
|
|
1994
1997
|
In more detail:
|
|
1995
1998
|
|
|
@@ -2003,10 +2006,11 @@ In more detail:
|
|
|
2003
2006
|
- `--reinit-on-change`: however far play has gone, rather than holding the edit as pending (see [What reloads](#what-reloads)). The console shows a short 'Settings changed, game restarted' notice each time. The hosted builder starts the dev server this way
|
|
2004
2007
|
- `--brand`: a brand file to preview the game in, added to the console's **Brand** menu and selected. Repeat it for more than one; the first is selected. See [Preview your game in another brand](./guides/theming-and-branding.md#preview-your-game-in-another-brand)
|
|
2005
2008
|
- `--isolated`: for a test run or a recording (see below)
|
|
2009
|
+
- `--public-url`, `--public-asset-url` and `--public-hmr-url`: the addresses people reach the server at when a proxy or gateway stands in front of it. Each defaults to its `SERIOUSGAMING_DEV_PUBLIC_*` environment variable. See [Embedding the dev server](./cli-and-dev-server.md#embedding-the-dev-server)
|
|
2006
2010
|
|
|
2007
2011
|
A package holds one session, so a second `sdk dev` for the same package is refused whatever port it asks for, and names the one already running. Stop that one with `sdk dev stop` to move it elsewhere, or start the second with `--isolated`.
|
|
2008
2012
|
|
|
2009
|
-
The server prints the console's address and the address game surfaces are served from. With `-j, --json`, the envelope it writes when it stops carries `url`, `assetUrl`, `port`, `assetPort` and `isolated
|
|
2013
|
+
The server prints the console's address and the address game surfaces are served from. With `-j, --json`, the envelope it writes when it stops carries `url`, `assetUrl`, `port`, `assetPort` and `isolated`, and `publicUrl` and `publicAssetUrl` when a public origin is set.
|
|
2010
2014
|
|
|
2011
2015
|
### Run a second server beside your own
|
|
2012
2016
|
|
|
@@ -2087,6 +2091,36 @@ Stop the dev server running for this package.
|
|
|
2087
2091
|
|
|
2088
2092
|
`dev status` and `dev stop` report through the [envelope](#json-output) with `-j, --json`, like every command.
|
|
2089
2093
|
|
|
2094
|
+
### Screenshot a surface
|
|
2095
|
+
|
|
2096
|
+
```text
|
|
2097
|
+
pnpm run sdk screenshot <path> [options]
|
|
2098
|
+
```
|
|
2099
|
+
|
|
2100
|
+
Capture a surface as a PNG, as a participant sees it.
|
|
2101
|
+
|
|
2102
|
+
| Option | Default | Description |
|
|
2103
|
+
| -------------------------- | --------------------- | ------------------------------------------------------------------------------------- |
|
|
2104
|
+
| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in. |
|
|
2105
|
+
| `--width <PIXELS>` | `1280` | Viewport width. |
|
|
2106
|
+
| `--height <PIXELS>` | `800` | Viewport height. |
|
|
2107
|
+
| `--scheme <SCHEME>` | | Colour scheme: light, dark or system. |
|
|
2108
|
+
| `--brand <ID>` | | Brand to show, from those the dev server offers. |
|
|
2109
|
+
| `--locale <CODE>` | | Session locale for the capture; a running server's is switched back after. |
|
|
2110
|
+
| `--full-page` | | Capture the surface's whole height, not just the viewport. |
|
|
2111
|
+
| `--out <FILE>` | | PNG to write (default: `.seriousgaming-sdk/screenshots/<path>-<width>x<height>.png).` |
|
|
2112
|
+
| `--timeout <SECONDS>` | `30` | How long to wait for the surface to render. |
|
|
2113
|
+
|
|
2114
|
+
```bash
|
|
2115
|
+
pnpm run sdk screenshot /team/1/player/1 --width 390 --height 844 --scheme dark --out plan.png --json
|
|
2116
|
+
```
|
|
2117
|
+
|
|
2118
|
+
The path is any surface's URL path, such as `/team/1/player/1` or `/` for the session surface; `?bare` is added for you. The capture waits for the surface to report its first paint, so it shows the screen as drawn rather than its loading state. With `--json` the data names the image (`path`), the `url` it opened, and the page's `consoleErrors`, `failedRequests` and `uncaughtExceptions`, those inside the surface's frame included.
|
|
2119
|
+
|
|
2120
|
+
It drives the game's own Playwright (`@playwright/test`, which every scaffolded game has), and fails with `BROWSER_MISSING` (exit 5) without it or its Chromium. A surface that does not connect, or does not report its first paint within `--timeout`, fails with `SURFACE_NOT_RENDERED` (exit 4), carrying the same three lists in `error.details`.
|
|
2121
|
+
|
|
2122
|
+
The locale is the session's, not a viewer's, so `--locale` switches the session for the capture, and switches a running dev server back afterwards. See [Screenshot a surface](./recipes/screenshot-a-surface.md).
|
|
2123
|
+
|
|
2090
2124
|
### Dev server features
|
|
2091
2125
|
|
|
2092
2126
|
- **Hot reloading**: edit logic, bundles, the manifest or UIs and see the change without a restart (see [What reloads](#what-reloads))
|
|
@@ -2510,11 +2544,16 @@ Prints the installed SDK version to stdout.
|
|
|
2510
2544
|
### Browse the documentation
|
|
2511
2545
|
|
|
2512
2546
|
```text
|
|
2513
|
-
pnpm run sdk docs view [file]
|
|
2547
|
+
pnpm run sdk docs view [file] [options]
|
|
2514
2548
|
```
|
|
2515
2549
|
|
|
2516
2550
|
View Serious Gaming SDK documentation.
|
|
2517
2551
|
|
|
2552
|
+
| Option | Default | Description |
|
|
2553
|
+
| --------------------- | ------- | ------------------------------------------------------------------------- |
|
|
2554
|
+
| `--outline` | | List the page's headings, with each section's length in characters. |
|
|
2555
|
+
| `--section <heading>` | | Print only the section under this heading, named by its slug or its text. |
|
|
2556
|
+
|
|
2518
2557
|
```text
|
|
2519
2558
|
pnpm run sdk docs export [dir]
|
|
2520
2559
|
```
|
|
@@ -2524,6 +2563,14 @@ Export SDK documentation to your project.
|
|
|
2524
2563
|
The docs ship inside the package at `node_modules/@seriousgaming/sdk-tools/dist/docs`, so they match the installed version and need no network. Search them with your editor or `grep`.
|
|
2525
2564
|
|
|
2526
2565
|
- `docs view` with no argument prints the tree of documents; with a path (for example `guides/engine.md`) it prints that document
|
|
2566
|
+
- `docs view page-index.md` lists every page with a one-sentence summary and its length: the place to find the page for a subject
|
|
2567
|
+
- `docs view <path> --outline` lists a page's headings, each with its level, its slug and its section's length in characters; `--section <heading>` prints only that section, named by its slug or its text, up to the next heading of the same or a higher level. Both work with `--json`, and an unknown section fails with `DOCS_SECTION_NOT_FOUND`, listing the slugs the page has in `details.available`
|
|
2568
|
+
|
|
2569
|
+
```bash
|
|
2570
|
+
pnpm run --silent sdk docs view guides/session.md --outline
|
|
2571
|
+
pnpm run --silent sdk docs view guides/session.md --section building-the-session-ui
|
|
2572
|
+
```
|
|
2573
|
+
|
|
2527
2574
|
- `docs export` copies every document to `dir`, or `.seriousgaming-sdk/docs` by default, so an editor or agent can search them locally
|
|
2528
2575
|
|
|
2529
2576
|
## Environment variables
|