@seriousgaming/sdk-tools 1.0.0-alpha.3 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -5
- package/dist/cli.js +30 -12
- package/dist/client/index.d.ts +2 -2
- package/dist/client/test-session.d.ts +12 -15
- package/dist/client.js +20 -11
- package/dist/docs/api/index.md +1 -1
- package/dist/docs/api/sdk-tools-client.md +40 -32
- package/dist/docs/api/sdk-ui-testing.md +4 -4
- package/dist/docs/api/sdk-ui.md +80 -20
- package/dist/docs/api/sdk.md +37 -21
- package/dist/docs/changelog.md +119 -74
- package/dist/docs/cli-and-dev-server.md +16 -15
- package/dist/docs/concepts/index.md +1 -1
- package/dist/docs/concepts/terminology.md +6 -6
- package/dist/docs/getting-started.md +4 -2
- package/dist/docs/guides/engine-testing.md +1 -1
- package/dist/docs/guides/engine.md +13 -0
- package/dist/docs/guides/file-handling.md +4 -4
- package/dist/docs/guides/internationalization.md +15 -1
- package/dist/docs/guides/llm-integration.md +2 -0
- package/dist/docs/guides/patterns.md +33 -5
- package/dist/docs/guides/presentation.md +9 -9
- package/dist/docs/guides/session.md +22 -19
- package/dist/docs/guides/testing.md +1 -1
- package/dist/docs/guides/tick-controller.md +5 -3
- package/dist/docs/guides/ui.md +5 -1
- package/dist/docs/guides/upgrading.md +40 -5
- package/dist/docs/recipes/create-endpoint.md +1 -1
- package/dist/docs/recipes/start-from-an-empty-package.md +6 -7
- package/dist/docs/recipes/use-request-tick.md +1 -1
- package/dist/docs/troubleshooting.md +6 -4
- package/dist/schema.json +6 -6
- package/dist/templates/endpoint/logic.test.ts.liquid +35 -48
- package/dist/templates/engine/logic-aggregate.test.ts.liquid +34 -53
- package/dist/templates/engine/logic.test.ts.liquid +22 -34
- package/dist/templates/hook/logic.test.ts.liquid +28 -32
- package/dist/templates/package/CLAUDE.md.template +1 -1
- package/dist/templates/package/README.md.liquid +3 -3
- package/dist/templates/package/claude/rules/workflow-create-capability.md +1 -1
- package/dist/templates/package/claude/rules/workflow-create-endpoint.md +1 -1
- package/dist/templates/presentation/src/App.tsx.liquid +1 -1
- package/dist/templates/session/src/main.tsx.liquid +3 -3
- package/dist/templates/settings-editor/src/main.tsx.liquid +3 -3
- package/dist/templates/starter-game/engine/logic.test.ts +37 -47
- package/dist/templates/starter-game/engine/test-helpers.ts +13 -65
- package/dist/templates/starter-game/hooks/assignproducts/logic/logic.test.ts +24 -30
- package/dist/templates/starter-game/session/src/main.tsx +3 -3
- package/dist/templates/starter-game/ui/src/main.tsx +3 -3
- package/dist/templates/starter-game/validators/capacity/logic/logic.test.ts +12 -35
- package/dist/templates/starter-game/waiting_room/src/main.tsx +3 -3
- package/dist/templates/ui/src/App.test.tsx.liquid +2 -2
- package/dist/templates/ui/src/App.tsx.liquid +22 -11
- package/dist/templates/ui/src/i18n.ts.liquid +3 -0
- package/dist/templates/ui/src/main.tsx.liquid +3 -3
- package/dist/templates/validator/logic.test.ts.liquid +21 -30
- package/dist/templates/waiting-room/src/App.test.tsx.liquid +2 -2
- package/dist/templates/waiting-room/src/main.tsx.liquid +3 -3
- package/package.json +3 -3
|
@@ -300,10 +300,10 @@ See [Take a file in an endpoint](../recipes/take-a-file-in-an-endpoint.md).
|
|
|
300
300
|
|
|
301
301
|
Every blob is stored with a retention that controls its lifetime:
|
|
302
302
|
|
|
303
|
-
| Retention | Lifetime
|
|
304
|
-
| ------------ |
|
|
305
|
-
| `"game"` | Cleared on a session reset or a re-initialise
|
|
306
|
-
| `"settings"` | Survives a session reset
|
|
303
|
+
| Retention | Lifetime | When to use |
|
|
304
|
+
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
|
|
305
|
+
| `"game"` | Cleared on a session reset or a re-initialise | Participant-uploaded content for a specific game session |
|
|
306
|
+
| `"settings"` | Survives a session reset and the automatic re-initialise after a package edit; cleared on a manual re-initialise, a reconfigure or a scenario change | Documents set up before the game starts (e.g. a scenario brief uploaded from a setup screen or scenario editor) |
|
|
307
307
|
|
|
308
308
|
Retention is a deletion-lifecycle bucket only: it is not an access or visibility control. It is set at upload time, and who sets it depends on the surface:
|
|
309
309
|
|
|
@@ -22,6 +22,18 @@ pnpm run sdk update package --patch '[
|
|
|
22
22
|
|
|
23
23
|
The `supportedLocales` array defines which languages the game supports. The `locales` object holds the game's name in each of them, and the name in the first supported locale is the package's name.
|
|
24
24
|
|
|
25
|
+
### Locale codes
|
|
26
|
+
|
|
27
|
+
A locale code is a short BCP 47 language tag: a language, then optionally a script, then optionally a region, separated by hyphens.
|
|
28
|
+
|
|
29
|
+
| Part | Form | Examples |
|
|
30
|
+
| -------- | ------------------------------------ | ----------------- |
|
|
31
|
+
| Language | Two or three lowercase letters | `en`, `zh`, `fil` |
|
|
32
|
+
| Script | Four letters, first capitalised | `Hant`, `Latn` |
|
|
33
|
+
| Region | Two capital letters, or three digits | `GB`, `TW`, `419` |
|
|
34
|
+
|
|
35
|
+
So `en`, `en-GB`, `es-419`, `zh-Hant`, `zh-Hant-TW` and `fil` are all valid. The case matters: `en-gb`, `zh-hant` and `en_GB` are refused when the package is built, as is anything with more parts (a variant or a private-use tag).
|
|
36
|
+
|
|
25
37
|
Use `--patch` rather than a JSON definition here. A definition passed as an argument or with `--file` replaces the whole manifest, so anything it leaves out (`maxTicks`, `teams`, `waitingRoom` and the rest) is dropped. An RFC 6902 patch changes only the paths it names.
|
|
26
38
|
|
|
27
39
|
## User interface localisation
|
|
@@ -121,6 +133,8 @@ In the dev server, change the session language with the locale select in the con
|
|
|
121
133
|
|
|
122
134
|
The choice holds for the rest of the session. No additional code is needed: just use `t()` in your components.
|
|
123
135
|
|
|
136
|
+
A scaffolded `main.tsx` hands i18next the whole locale code, which falls back through it on its own: `zh-Hant-TW` looks for `zh-Hant-TW` translations, then `zh-Hant`, then `zh`, then the fallback language. Translations keyed by language alone (`fr`) therefore still serve `fr-CA`, and a script you key separately (`zh-Hant` beside `zh-Hans`) is found too.
|
|
137
|
+
|
|
124
138
|
## Localising scenario content
|
|
125
139
|
|
|
126
140
|
The i18next setup above localises UI chrome: the buttons, labels, and other text that ships inside the user interface. Scenario-authored content is different. This is the prose a scenario carries but a UI renders: inbox documents, narrative emails, briefings, and transcripts. It needs its own approach.
|
|
@@ -141,7 +155,7 @@ assets/
|
|
|
141
155
|
it/documents.json
|
|
142
156
|
```
|
|
143
157
|
|
|
144
|
-
Read it with `useAsset`, which tries the surface's locale first
|
|
158
|
+
Read it with `useAsset`, which tries the surface's locale first, then the locale with its last part dropped, down to its language (so `fr-CA` finds `fr/`, and `zh-Hant-TW` tries `zh-Hant/` before `zh/`), and falls back to the file as given:
|
|
145
159
|
|
|
146
160
|
```typescript
|
|
147
161
|
import { useAsset } from '@seriousgaming/sdk/ui';
|
|
@@ -153,6 +153,8 @@ interface LLMResponse {
|
|
|
153
153
|
|
|
154
154
|
The blocks let one response carry text and one or more tool-use intents. The stop reason distinguishes normal completion (`'endTurn'`), tool use (`'toolUse'`), truncation (`'maxTokens'`), and refusal (`'refusal'`). When the provider reports token counts, `usage` carries the input and output token totals for the call.
|
|
155
155
|
|
|
156
|
+
Both sets are closed, so a `switch` over them can be exhaustive. A runtime never returns a stop reason your game was not built to know: one a later release adds reaches only a game that declares the feature that adds it in `requires`, and any other game is told `'endTurn'`. A new kind of content block reaches only a call that asks for it with an option on `generateText`, and is dropped from every other response.
|
|
157
|
+
|
|
156
158
|
For the common case where you just want the assistant's text, use `getText`:
|
|
157
159
|
|
|
158
160
|
```typescript
|
|
@@ -279,17 +279,46 @@ pnpm run sdk new capability '{
|
|
|
279
279
|
"variablesSchema": {
|
|
280
280
|
"type": "object",
|
|
281
281
|
"properties": {
|
|
282
|
-
"ProductionCost": { "type": "number", "default": 5 },
|
|
283
282
|
"TotalCosts": { "type": "number", "default": 0 }
|
|
284
283
|
},
|
|
285
|
-
"required": ["
|
|
284
|
+
"required": ["TotalCosts"],
|
|
286
285
|
"additionalProperties": false
|
|
287
286
|
}
|
|
288
287
|
}
|
|
289
288
|
}'
|
|
290
289
|
```
|
|
291
290
|
|
|
292
|
-
|
|
291
|
+
**Settings:**
|
|
292
|
+
|
|
293
|
+
The steps read their parameters from a settings resource rather than from context, because they are fixed when play starts and no step writes them:
|
|
294
|
+
|
|
295
|
+
```bash
|
|
296
|
+
pnpm run sdk new settings '{
|
|
297
|
+
"definition": {
|
|
298
|
+
"identifier": "engine",
|
|
299
|
+
"settingsSchema": {
|
|
300
|
+
"type": "object",
|
|
301
|
+
"properties": {
|
|
302
|
+
"BaseDemand": { "type": "number", "default": 100 },
|
|
303
|
+
"DemandVariance": { "type": "number", "default": 20 },
|
|
304
|
+
"ProductionCost": { "type": "number", "default": 5 }
|
|
305
|
+
},
|
|
306
|
+
"additionalProperties": false
|
|
307
|
+
}
|
|
308
|
+
}
|
|
309
|
+
}'
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
The engine lists it in `settings` beside the capabilities it writes:
|
|
313
|
+
|
|
314
|
+
```bash
|
|
315
|
+
pnpm run sdk update engine --patch '[
|
|
316
|
+
{ "op": "replace", "path": "/definition/writes", "value": ["demand", "production", "costs"] },
|
|
317
|
+
{ "op": "add", "path": "/definition/settings", "value": ["engine"] }
|
|
318
|
+
]'
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
The steps below read `BaseDemand`, `DemandVariance`, and `ProductionCost` as `settings.engine.*`.
|
|
293
322
|
|
|
294
323
|
**Demand step** (`engine/demand.ts`)**:**
|
|
295
324
|
|
|
@@ -316,7 +345,7 @@ export const runDemand: StepFunction<Context, Settings> = async ({ context, sett
|
|
|
316
345
|
**Production step** (`engine/production.ts`)**:**
|
|
317
346
|
|
|
318
347
|
```typescript
|
|
319
|
-
export const runProduction: StepFunction<Context, Settings> = async ({ context
|
|
348
|
+
export const runProduction: StepFunction<Context, Settings> = async ({ context }) => {
|
|
320
349
|
const { CurrentDemand } = context.demand;
|
|
321
350
|
const { ProductionRate, TotalProduced } = context.production;
|
|
322
351
|
|
|
@@ -350,7 +379,6 @@ export const runCosts: StepFunction<Context, Settings> = async ({ context, setti
|
|
|
350
379
|
...context,
|
|
351
380
|
costs: {
|
|
352
381
|
...context.costs,
|
|
353
|
-
ProductionCost: settings.engine.ProductionCost,
|
|
354
382
|
TotalCosts: TotalCosts + costThisTick,
|
|
355
383
|
},
|
|
356
384
|
};
|
|
@@ -57,15 +57,15 @@ const { game, session, settings, theme, locale, getPastState, getAssetUrl } = us
|
|
|
57
57
|
>();
|
|
58
58
|
```
|
|
59
59
|
|
|
60
|
-
| Field | What it holds
|
|
61
|
-
| -------------- |
|
|
62
|
-
| `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
|
|
63
|
-
| `session` | `null` with no session. Otherwise its `id`, `name`, `
|
|
64
|
-
| `settings` | The settings resources the presentation declares, resolved for the scenario, and for the session when there is one
|
|
65
|
-
| `theme` | The host's theme, to map onto the deck's colours
|
|
66
|
-
| `locale` | The locale to render in
|
|
67
|
-
| `getPastState` | Reads past rounds, as the session UI does, with `teams` defaulting to every team. Rejects when there is no session
|
|
68
|
-
| `getAssetUrl` | Turns an `asset:`, `shared:` or `blob:` reference into a URL
|
|
60
|
+
| Field | What it holds |
|
|
61
|
+
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
62
|
+
| `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 |
|
|
63
|
+
| `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 `teams` |
|
|
64
|
+
| `settings` | The settings resources the presentation declares, resolved for the scenario, and for the session when there is one |
|
|
65
|
+
| `theme` | The host's theme, to map onto the deck's colours |
|
|
66
|
+
| `locale` | The locale to render in |
|
|
67
|
+
| `getPastState` | Reads past rounds, as the session UI does, with `teams` defaulting to every team. Rejects when there is no session |
|
|
68
|
+
| `getAssetUrl` | Turns an `asset:`, `shared:` or `blob:` reference into a URL |
|
|
69
69
|
|
|
70
70
|
A presentation sees every team: it is the facilitator's view of the room.
|
|
71
71
|
|
|
@@ -908,25 +908,28 @@ const { requestTick, pauseTimer, resumeTimer, undoTick, resetGame } =
|
|
|
908
908
|
useSessionUserInterfaceCallbacks();
|
|
909
909
|
```
|
|
910
910
|
|
|
911
|
-
| Callback
|
|
912
|
-
|
|
|
913
|
-
| `requestTick`
|
|
914
|
-
| `pauseTimer`
|
|
915
|
-
| `resumeTimer`
|
|
916
|
-
| `undoTick`
|
|
917
|
-
| `resetGame`
|
|
918
|
-
| `
|
|
919
|
-
| `
|
|
920
|
-
| `
|
|
921
|
-
| `
|
|
922
|
-
| `
|
|
923
|
-
| `
|
|
924
|
-
| `
|
|
925
|
-
| `
|
|
926
|
-
| `
|
|
927
|
-
| `
|
|
928
|
-
| `
|
|
929
|
-
| `
|
|
911
|
+
| Callback | Signature | Description |
|
|
912
|
+
| -------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
913
|
+
| `requestTick` | `(teamId?: string) => Promise<void>` | Advance the game by one tick; omit `teamId` to advance all teams |
|
|
914
|
+
| `pauseTimer` | `(teamId?: string) => Promise<void>` | Pause automatic ticking; omit `teamId` to pause all teams |
|
|
915
|
+
| `resumeTimer` | `(teamId?: string) => Promise<void>` | Resume automatic ticking; omit `teamId` to resume all teams |
|
|
916
|
+
| `undoTick` | `(teamId?: string) => Promise<void>` | Un-run the last tick, keeping the tick's decisions; omit `teamId` to undo all teams. Naming one is independent mode only |
|
|
917
|
+
| `resetGame` | `(teamId?: string) => Promise<void>` | Re-initialise the game from scratch; omit `teamId` to reset all teams |
|
|
918
|
+
| `getPastState` | `(query) => Promise<PastStateEntry[]>` | Read committed past rounds; `teams` defaults to every team, or name one team by id |
|
|
919
|
+
| `extendTick` | `(byMs, teamId?) => Promise<void>` | Move the currently scheduled tick's deadline by `byMs` milliseconds; negative pulls it in |
|
|
920
|
+
| `openHostOverlay` | `(overlay, target?) => Promise<void>` | Ask the host to open the guide or a print sheet |
|
|
921
|
+
| `uploadBlob` | `(file: File) => Promise<string>` | Upload a file, returns a `blob:<id>` reference |
|
|
922
|
+
| `getAssetUrl` | `(reference: string) => string` | Resolve an `asset:`, `shared:`, or `blob:` reference to a URL |
|
|
923
|
+
| `readAsset` | `(reference: string) => Promise<{ data, mimeType, name }>` | Read bytes for an `asset:`, `shared:`, or `blob:` reference |
|
|
924
|
+
| `endpoints` | `Record<string, (request) => Promise<Response>>` | Call a declared endpoint by identifier |
|
|
925
|
+
| `setWaitingRoom` | `(open: boolean) => Promise<void>` | Open or close the session's waiting room; no `teamId` |
|
|
926
|
+
| `resetWalkthrough` | `() => Promise<void>` | Throw the walkthrough away and restart it at tick 0; rejects while the session has no walkthrough |
|
|
927
|
+
| `createTeam` | `(name?: string) => Promise<void>` | Add a team; the host assigns the index |
|
|
928
|
+
| `renameTeam` | `(teamId, name) => Promise<void>` | Rename a team |
|
|
929
|
+
| `renameParticipant` | `(participantId, name) => Promise<void>` | Rename a participant; the host resolves their team |
|
|
930
|
+
| `moveParticipant` | `(participantId, teamId) => Promise<void>` | Reassign a participant to another team |
|
|
931
|
+
| `deleteTeam` | `(teamId) => Promise<void>` | Delete an empty team; independent mode only, and never the last team |
|
|
932
|
+
| `setThemePreference` | `(preference: ThemePreference) => void` | Set the host's theme preference |
|
|
930
933
|
|
|
931
934
|
The promise-returning callbacks resolve and reject as described in [Controlling game flow](#controlling-game-flow). The wrapper supplies every callback, so none needs an optional-chaining guard.
|
|
932
935
|
|
|
@@ -268,7 +268,7 @@ Default values when you omit an option:
|
|
|
268
268
|
| `settings` | `{}` |
|
|
269
269
|
| `completedTicks` | `0` |
|
|
270
270
|
| `setData` | no-op |
|
|
271
|
-
| `theme` | `
|
|
271
|
+
| `theme` | `createMockUserInterfaceTheme()` (light mode, MUI palette) |
|
|
272
272
|
| `locale` | `{ locale: 'en' }` |
|
|
273
273
|
| `participant` | `{ id: '1', name: 'Participant 1', index: 0, connected: true, teamId: 'team-1' }` |
|
|
274
274
|
| `participants` | `[]` (`createMockParticipants(n)` builds a roster) |
|
|
@@ -308,8 +308,10 @@ export const GetTickController: GetTickControllerFunction<Context, Settings> = a
|
|
|
308
308
|
context,
|
|
309
309
|
settings,
|
|
310
310
|
}) => {
|
|
311
|
-
|
|
312
|
-
|
|
311
|
+
return {
|
|
312
|
+
enabled: false,
|
|
313
|
+
complete: context.financials.Profit >= settings.tick_controller.ProfitTarget,
|
|
314
|
+
};
|
|
313
315
|
};
|
|
314
316
|
```
|
|
315
317
|
|
|
@@ -359,7 +361,7 @@ export const GetTickController: GetTickControllerFunction<Context, Settings> = a
|
|
|
359
361
|
}) => {
|
|
360
362
|
// The game ends when every team hits the target
|
|
361
363
|
const allDone = teams.every(
|
|
362
|
-
(t) =>
|
|
364
|
+
(t) => t.context.financials.Profit >= settings.tick_controller.ProfitTarget
|
|
363
365
|
);
|
|
364
366
|
return { enabled: false, complete: allDone };
|
|
365
367
|
};
|
package/dist/docs/guides/ui.md
CHANGED
|
@@ -302,6 +302,8 @@ useEffect(() => {
|
|
|
302
302
|
- `tick-failed`: the tick could not run (tick limit reached, game complete, or the executor threw)
|
|
303
303
|
- `error`: anything else unexpected
|
|
304
304
|
|
|
305
|
+
The list is closed, so a `switch` over `outcome.kind` can be exhaustive. A kind a later release adds reaches only a game that declares the feature that adds it in `requires`; any other game is told `error`.
|
|
306
|
+
|
|
305
307
|
Reach for `useMutationReporter` rather than branching by hand. It awaits the write, tracks whether one is in flight, and hands you the failure to render:
|
|
306
308
|
|
|
307
309
|
```tsx
|
|
@@ -444,6 +446,8 @@ function Decisions() {
|
|
|
444
446
|
|
|
445
447
|
Most UIs need no changes: an observer sees the live game UI exactly as a participant does, and can still drive it. Any change an observer makes goes to the game's validators, as a participant's would, with `actor.role` set to `'observer'` so a validator can treat it differently (see [Validators](./validators.md)). Reach for `useUserInterfaceViewerRole()` only when you want to adapt: hide a participant-only control (anything keyed by participant id has no id to write under), reveal state you keep hidden during play, or present a deliberately read-only debrief view.
|
|
446
448
|
|
|
449
|
+
The two roles are the only ones your UI is ever told. A kind of viewer a later release adds reaches only a game that declares the feature that adds it in `requires`, and every other game is shown to that viewer as to an observer, so code that treats anything but `'participant'` as observing is always right.
|
|
450
|
+
|
|
447
451
|
One read does need attention. To find out **which team** your UI is rendering, use `useUserInterfaceOwnTeam()`, not `useUserInterfaceParticipant()?.teamId`:
|
|
448
452
|
|
|
449
453
|
```typescript
|
|
@@ -927,7 +931,7 @@ function Briefing() {
|
|
|
927
931
|
}
|
|
928
932
|
```
|
|
929
933
|
|
|
930
|
-
It prefers a copy in the surface's locale, held in a directory named for the locale just before the file name, and falls back to the reference as given. In `fr-CA`, `shared:briefing/briefing.md` tries `shared:briefing/fr-CA/briefing.md`, then `shared:briefing/fr/briefing.md`, then `shared:briefing/briefing.md
|
|
934
|
+
It prefers a copy in the surface's locale, held in a directory named for the locale just before the file name, and falls back to the reference as given. In `fr-CA`, `shared:briefing/briefing.md` tries `shared:briefing/fr-CA/briefing.md`, then `shared:briefing/fr/briefing.md`, then `shared:briefing/briefing.md` (a locale with a script, such as `zh-Hant-TW`, tries `zh-Hant` before `zh`):
|
|
931
935
|
|
|
932
936
|
```
|
|
933
937
|
shared-assets/
|
|
@@ -4,7 +4,7 @@ This guide takes a game package on 0.6 to 1.0, in 13 steps. Each step names what
|
|
|
4
4
|
|
|
5
5
|
The steps are grouped by topic, not in the quickest order. Until the package loads, every CLI command reports what later steps have not fixed yet, so most games go fastest like this:
|
|
6
6
|
|
|
7
|
-
1. Make every edit that gets the package loading, in one pass: step 1, the bundle files and directories in step 2 (2a, 2b, 2c, 2e and 2g), step 3's moves, 7a and step
|
|
7
|
+
1. Make every edit that gets the package loading, in one pass: step 1, the bundle files and directories in step 2 (2a, 2b, 2c, 2e and 2g), step 3's moves, 7a, 7e, step 8, and step 9's bullets on `uses`, demo mode and Node built-ins (`LOGIC_NODE_BUILTIN`). Each of these is a build refusal, and any one of them stops the package loading
|
|
8
8
|
2. Run `pnpm run sdk generate`
|
|
9
9
|
3. Let `pnpm run typecheck` drive the rest: 2d and steps 4, 5, 6 and 10. One or two runs list everything
|
|
10
10
|
4. Search by hand for the changes no tool sees (below), then verify with step 13
|
|
@@ -27,6 +27,9 @@ Most steps are mechanical and the compiler finds what they break. **These change
|
|
|
27
27
|
- A surface retrying a `conflict` on its own ([step 9](#step-9-meet-what-the-build-and-runtime-now-enforce))
|
|
28
28
|
- A test calling an endpoint with `uiIdentifier: ''`, which is now refused ([step 10a](#10a-move-off-gamerunner))
|
|
29
29
|
- Code that reads scenario files itself and still looks for `configuration` ([step 2c](#2c-rename-scenario-configuration-to-settings))
|
|
30
|
+
- A scenario's `teams.defaultNames` replacing the game's list whole, rather than falling back to the game's names past its end ([step 2g](#2g-rename-ticks-to-maxticks-and-move-a-scenarios-game-fields-into-settingsgame))
|
|
31
|
+
- `complete` now being `true` once a team has played its last round, not only when something ended the game early ([step 6d](#6d-completion-record-times-blob-retention-and-the-manifest-types))
|
|
32
|
+
- An endpoint checking `caller.userInterfaceIdentifier === 'cli'`, which never matches now that the field is absent for the CLI ([step 7b](#7b-handle-the-new-arguments))
|
|
30
33
|
|
|
31
34
|
The [changelog](../changelog.md) carries the detail behind every step.
|
|
32
35
|
|
|
@@ -40,7 +43,7 @@ The three public packages move to the `@seriousgaming` scope on the public npm r
|
|
|
40
43
|
| `@businesssimulations/seriousgaming-sdk` | `@seriousgaming/sdk` |
|
|
41
44
|
| `@businesssimulations/seriousgaming-deck` | `@seriousgaming/deck` |
|
|
42
45
|
|
|
43
|
-
1. In `package.json`, rename the dependencies and set each to the 1.0 version. Keep the SDK, the tools and the deck at one version. `@seriousgaming/sdk-tools` declares `@seriousgaming/sdk` as a peer dependency
|
|
46
|
+
1. In `package.json`, rename the dependencies and set each to the 1.0 version. Keep the SDK, the tools and the deck at one version. `@seriousgaming/sdk-tools` declares `@seriousgaming/sdk` as a peer dependency with a compatible `^` range on its own version (`^1.0.0` for 1.0.0)
|
|
44
47
|
2. Replace the names everywhere else, in the order of the table so the SDK's name does not rewrite the start of the tools' name: every import (logic, surfaces, tests), `resolve.dedupe` in `vite.config.ts` and `vitest.config.ts`, `oxlintrc.json`, `testing/e2e/global-setup.ts` if you have one, `CLAUDE.md`, `.claude/rules/` and `README.md`. Then run your formatter: the new names sort differently, so every `package.json` and sorted import block changes
|
|
45
48
|
3. Remove the `@businesssimulations:registry=https://npm.pkg.github.com` line, and the token beside it, from `.npmrc` and from CI, unless something else you install still comes from there
|
|
46
49
|
4. In `pnpm-workspace.yaml`, delete the `sharp` and `protobufjs` overrides. They held back dependencies of `@xenova/transformers`, which left with `docs ask` (step 11), so nothing installs either package any more. Delete anything else you added for it too, such as `minimumReleaseAgeExclude` or `allowBuilds` entries for `@xenova/transformers` or `onnxruntime-node`
|
|
@@ -217,7 +220,8 @@ Three things behave differently once you have:
|
|
|
217
220
|
- **A scenario's `teams.defaultNames` replaces the game's list whole.** It used to fall back to the game's name for a team past the end of the scenario's list. List every name the scenario needs
|
|
218
221
|
- **A presentation reads `game.maxTicks`**, where it read `game.ticks`
|
|
219
222
|
- **A settings resource called `game` is refused** (`SETTINGS_RESERVED`), since the name is the built-in one's. Rename yours, along with every `settings` and `configures` entry that names it
|
|
220
|
-
|
|
223
|
+
|
|
224
|
+
**Lock `teams.max` in a single-team game.** `teams.max: 1` alone no longer makes a game single-team, because a scenario or setup could raise it. An independent game whose engine writes a shared capability fails the build until it adds `"gameSettingsConstraints": { "teams": { "max": { "readOnly": true } } }` beside `teams.max: 1` (see [Narrow or lock the game settings](./settings.md#narrow-or-lock-the-game-settings)).
|
|
221
225
|
|
|
222
226
|
A setup UI or scenario editor can now set the number of rounds: list `game` in its `configures`, and write `updateSettings({ game: { ...settings.game, maxTicks: 6 } })`. A setup cannot set `waitingRoom.openOnStart`, which takes effect before setup runs. See [The game settings](./settings.md#the-game-settings).
|
|
223
227
|
|
|
@@ -430,7 +434,6 @@ One `TimerState` type replaces `SurfaceTimer`, `UserInterfaceTimer` and the proj
|
|
|
430
434
|
| `scheduledTick(at, { isComplete })` | `scheduledTick(at, { complete })` |
|
|
431
435
|
| `intervalTick(seconds)` | `intervalTick(intervalMs)` (**milliseconds**) |
|
|
432
436
|
| `extendTick(seconds, teamId?)` on a session UI | `extendTick(byMs, teamId?)` (**milliseconds**) |
|
|
433
|
-
| `MIN_EFFECTIVE_TICK_INTERVAL_SECONDS`, `MAX_…` | `MIN_EFFECTIVE_TICK_INTERVAL_MS`, `MAX_…` |
|
|
434
437
|
|
|
435
438
|
The unit changes compile unchanged, so search for each by hand:
|
|
436
439
|
|
|
@@ -462,7 +465,13 @@ grep -rnE "intervalTick\(|extendTick\(|interval:|timerEnabled|isPaused" tick_con
|
|
|
462
465
|
A `writeBlob` call still passing `'config'` is refused, naming the new value. A test fixture that builds past-state entries by hand needs the new names too:
|
|
463
466
|
|
|
464
467
|
```bash
|
|
465
|
-
grep -rnE "isComplete|timestamp|retention: 'config'|SDKConfiguration|LogicConfiguration" engine endpoints hooks ui session testing
|
|
468
|
+
grep -rnE "isComplete|timestamp|retention: 'config'|SDKConfiguration|LogicConfiguration|needsConfiguration" engine endpoints hooks ui session testing
|
|
469
|
+
```
|
|
470
|
+
|
|
471
|
+
**`complete` now counts the tick limit, and the compiler cannot see it.** On an endpoint's `session` and its team statuses, and in the state `sdk view` prints, a team is `complete` once it can tick no more: its engine or tick controller ended the game, or it has played `maxTicks`. The session is `complete` once every team is. Under 0.6 a game that ended by its limit read `complete: false` after its last round, so code that took `complete` to mean 'ended early', such as a 'target reached' banner, now shows it after every final round. Undoing that round clears it again. A `getPastState` entry's `complete` still reports only an engine or tick controller ending the game:
|
|
472
|
+
|
|
473
|
+
```bash
|
|
474
|
+
grep -rnw "complete" endpoints session ui presentation testing
|
|
466
475
|
```
|
|
467
476
|
|
|
468
477
|
## Step 7: update endpoints
|
|
@@ -560,6 +569,29 @@ Two builders need more than their names suggest:
|
|
|
560
569
|
|
|
561
570
|
### 10d. Update UI component tests
|
|
562
571
|
|
|
572
|
+
Four names in `@seriousgaming/sdk/ui` and `@seriousgaming/sdk/ui/testing` are renamed to pair with their hook or theme type, with no alias for the old ones, so code using them fails to compile until it is renamed:
|
|
573
|
+
|
|
574
|
+
| Before | After |
|
|
575
|
+
| ------------------------------------- | ------------------------------------------ |
|
|
576
|
+
| `createMockTheme` | `createMockUserInterfaceTheme` |
|
|
577
|
+
| `createMockSessionTheme` | `createMockSessionUserInterfaceTheme` |
|
|
578
|
+
| `CrossTeamDataContext` | `UserInterfaceCrossTeamDataContext` |
|
|
579
|
+
| `UserInterfaceValidationContext` | `UserInterfaceValidationRejectionsContext` |
|
|
580
|
+
| `UserInterfaceValidationContextValue` | `UserInterfaceValidationRejectionsValue` |
|
|
581
|
+
|
|
582
|
+
The renames are name-only, so one command makes them across a package. Run it from the package root, in a clean working tree so you can review the result with `git diff`:
|
|
583
|
+
|
|
584
|
+
```bash
|
|
585
|
+
git grep -lzE 'createMockTheme|createMockSessionTheme|CrossTeamDataContext|UserInterfaceValidationContext' -- '*.ts' '*.tsx' \
|
|
586
|
+
| xargs -0 perl -pi -e '
|
|
587
|
+
s/\bcreateMockTheme\b/createMockUserInterfaceTheme/g;
|
|
588
|
+
s/\bcreateMockSessionTheme\b/createMockSessionUserInterfaceTheme/g;
|
|
589
|
+
s/\bCrossTeamDataContext\b/UserInterfaceCrossTeamDataContext/g;
|
|
590
|
+
s/\bUserInterfaceValidationContextValue\b/UserInterfaceValidationRejectionsValue/g;
|
|
591
|
+
s/\bUserInterfaceValidationContext\b/UserInterfaceValidationRejectionsContext/g;
|
|
592
|
+
'
|
|
593
|
+
```
|
|
594
|
+
|
|
563
595
|
The helpers in `@seriousgaming/sdk/ui/testing` build each piece; see [Testing](./testing.md):
|
|
564
596
|
|
|
565
597
|
- **`createMockTeamState` and `createMockSharedState`** build a team's and the shared store's state for a session UI test. Pass the generated types, `createMockTeamState<TeamContext>({ context })` and `createMockSharedState<SharedContext>({ context })`, and a shared capability left on a team fixture fails to compile. Render with `renderSessionUserInterface<SessionData>(...)` so the whole fixture is checked. Typing a fixture this way tends to turn up stale test data: fields the game renamed long ago, and tests that were passing while checking nothing. Treat each failure as a find, not a regression, and fix the test
|
|
@@ -594,6 +626,9 @@ Optional, but each item fixes a trap. A package created by `sdk new package` at
|
|
|
594
626
|
- **The agent's pre-approved commands match its guidance.** Replace `.claude/settings.json`: it allows only read and check commands, never `dev`, `publish` or `pnpm add`
|
|
595
627
|
- **Unit tests stop building a DOM they do not use.** Replace `vitest.config.ts`: it runs `*.test.ts` in plain Node and `*.test.tsx` in jsdom on the `vmThreads` pool. Rename any `.ts` test that renders, `renderHook` included, to `.tsx`
|
|
596
628
|
- **Lint fails on a warning.** Set the `lint` script to `oxlint --max-warnings=0`
|
|
629
|
+
- **Lint refuses `any` and non-null assertions (`!`)** outside tests, `testing/` and each UI's `src/main.tsx`. Merge `oxlintrc.json.template` into `oxlintrc.json`, then fix or justify what it reports
|
|
630
|
+
- **Playwright's output stays out of git.** Merge `gitignore.template` into `.gitignore`: it ignores `test-results/` and `playwright-report/`
|
|
631
|
+
- **A stray `test.only` fails CI.** `playwright.config.ts.liquid` sets `forbidOnly` when `CI` is set, so one focused test no longer skips every other test. Merge it into `playwright.config.ts` if you did not replace that file above
|
|
597
632
|
- **The wrappers set `lang` and `dir`.** Delete the lines in each `main.tsx` that set them on the document
|
|
598
633
|
- **A shorter `CLAUDE.md` and refreshed rules.** Merge in the new `CLAUDE.md.template` and `claude/rules/` if you have not customised them heavily, as `workflow-update-sdk-version.md` describes
|
|
599
634
|
- **Refreshed dependencies.** Merge the versions in `package.json.liquid`, and after the Playwright bump run `pnpm exec playwright install chromium`
|
|
@@ -56,7 +56,7 @@
|
|
|
56
56
|
};
|
|
57
57
|
```
|
|
58
58
|
|
|
59
|
-
The
|
|
59
|
+
The handler takes `{ request, context, callbacks, caller, settings, meta, participants, session }` and returns `Promise<Response>`. A team-scoped handler also takes `team` (`{ teamId, index, name }`), the team the call runs for. A session-scoped handler has no `team`; it takes `teams`, every team's values, when it declares a capability that is not shared. An endpoint that declares no `writes` cannot change state: return only what fits the declared `responseSchema`.
|
|
60
60
|
|
|
61
61
|
To change state, declare the capabilities you may write and return the change alongside the response. `scope`, `writes`, and `visibility` can go straight into the `definition` you pass to `new endpoint`, which then scaffolds a handler of the writing shape:
|
|
62
62
|
|
|
@@ -128,7 +128,7 @@ This writes `ui/`, the game UI each participant sees. Edit `ui/src/App.tsx` to s
|
|
|
128
128
|
### 6. Set how long the game runs
|
|
129
129
|
|
|
130
130
|
```bash
|
|
131
|
-
pnpm run sdk update package --patch '[{"op":"add","path":"/
|
|
131
|
+
pnpm run sdk update package --patch '[{"op":"add","path":"/maxTicks","value":5}]'
|
|
132
132
|
```
|
|
133
133
|
|
|
134
134
|
`seriousgaming.sdk.json` now ends the game after five ticks.
|
|
@@ -151,12 +151,11 @@ pnpm test:run
|
|
|
151
151
|
|
|
152
152
|
## Troubleshooting
|
|
153
153
|
|
|
154
|
-
| Problem | Solution
|
|
155
|
-
| ----------------------------------------------- |
|
|
156
|
-
| `new engine` refuses because one already exists | The package was not made with `--empty`. Change the existing engine with `update engine` instead
|
|
157
|
-
| `context.bakery` is a type error | The engine does not declare `bakery` in `reads` or `writes`. Add it with `update engine`, which regenerates `types.ts`
|
|
158
|
-
|
|
|
159
|
-
| The tick changes nothing | Check `Run` returns the new capability object rather than the context it received |
|
|
154
|
+
| Problem | Solution |
|
|
155
|
+
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
156
|
+
| `new engine` refuses because one already exists | The package was not made with `--empty`. Change the existing engine with `update engine` instead |
|
|
157
|
+
| `context.bakery` is a type error | The engine does not declare `bakery` in `reads` or `writes`. Add it with `update engine`, which regenerates `types.ts` |
|
|
158
|
+
| The tick changes nothing | Check `Run` returns the new capability object rather than the context it received |
|
|
160
159
|
|
|
161
160
|
## Related
|
|
162
161
|
|
|
@@ -68,7 +68,7 @@ The hook must be called inside a component rendered within `UserInterfaceWrapper
|
|
|
68
68
|
|
|
69
69
|
**UI shows a brief flicker after calling `setData` then `requestTick`**
|
|
70
70
|
|
|
71
|
-
When you call `setData({ ... }); callbacks.requestTick();`, the `setData` change is visible immediately but the tick is asynchronous. Between the two, UIs show the raw `setData` values without any engine-computed results. This resolves once the tick completes (typically a few milliseconds). See [Combining setData with requestTick](../guides/ui.md#combining-setdata-with-requesttick) for strategies to handle the intermediate state.
|
|
71
|
+
When you call `await setData({ ... }); await callbacks.requestTick();`, the `setData` change is visible immediately but the tick is asynchronous. Between the two, UIs show the raw `setData` values without any engine-computed results. This resolves once the tick completes (typically a few milliseconds). See [Combining setData with requestTick](../guides/ui.md#combining-setdata-with-requesttick) for strategies to handle the intermediate state.
|
|
72
72
|
|
|
73
73
|
## Related
|
|
74
74
|
|
|
@@ -166,7 +166,7 @@ pnpm run sdk dev
|
|
|
166
166
|
**Fix:**
|
|
167
167
|
|
|
168
168
|
1. This is the expected end of the game. Use undo or reset to keep playing, or raise `maxTicks` in `seriousgaming.sdk.json` if the game should run longer
|
|
169
|
-
2. Your UI does not need to gate its advance control on `
|
|
169
|
+
2. Your UI does not need to gate its advance control on `completedTicks < maxTicks` for correctness, because the runtime enforces the limit. Disabling the control remains good UX
|
|
170
170
|
|
|
171
171
|
### A tick is refused with 'Team is already complete'
|
|
172
172
|
|
|
@@ -488,11 +488,11 @@ Demo mode has been removed, so `demo` is read by nothing. To show a game to a ro
|
|
|
488
488
|
|
|
489
489
|
**Fix:** re-key the override by the settings resource that declares the property, or create one with that name. A value in `.seriousgaming-sdk/configuration.json` can be corrected in place, or the file deleted to start again from the defaults. See [Overriding settings](./guides/settings.md#overriding-settings).
|
|
490
490
|
|
|
491
|
-
### An aggregate engine fails the build with '
|
|
491
|
+
### An aggregate engine fails the build with 'does not export "Run"'
|
|
492
492
|
|
|
493
|
-
**Symptom:** an engine you intended as aggregate fails `pnpm run sdk build` with
|
|
493
|
+
**Symptom:** an engine you intended as aggregate fails `pnpm run sdk build` with `LOGIC_EXPORT_MISSING`: _'Engine "engine": Logic file ".../engine/logic.ts" does not export "Run". A per-team engine must export `Run`; `Init` is optional.'_
|
|
494
494
|
|
|
495
|
-
**Cause:** its logic exports neither `InitAggregate` nor `RunAggregate`, so the build reads it as a per-team engine and applies the per-team export contract
|
|
495
|
+
**Cause:** its logic exports neither `InitAggregate` nor `RunAggregate`, so the build reads it as a per-team engine and applies the per-team export contract, which needs only `Run`. Merging several files into one engine makes this easy to do: the aggregate functions end up in a file nothing re-exports.
|
|
496
496
|
|
|
497
497
|
**Fix:**
|
|
498
498
|
|
|
@@ -510,6 +510,8 @@ Demo mode has been removed, so `demo` is read by nothing. To show a game to a ro
|
|
|
510
510
|
|
|
511
511
|
3. `sdk new engine --aggregate` scaffolds all three exports for a fresh engine
|
|
512
512
|
|
|
513
|
+
Exporting only one of the pair fails the same way, naming the other: _'does not export "RunAggregate". This engine is aggregate because its logic exports the other of "InitAggregate" / "RunAggregate"...'_. Export both.
|
|
514
|
+
|
|
513
515
|
### The build rejects a teamless surface calling a team-scoped endpoint
|
|
514
516
|
|
|
515
517
|
**Symptom:** `pnpm run sdk build` fails with _'calls endpoint X, which is team-scoped, but this surface has no team of its own'_ on a session UI, setup screen, or scenario editor.
|
package/dist/schema.json
CHANGED
|
@@ -460,7 +460,7 @@
|
|
|
460
460
|
"type": "object",
|
|
461
461
|
"description": "Localized scenario fields with one entry per supported locale",
|
|
462
462
|
"patternProperties": {
|
|
463
|
-
"^[a-z]{2}(-[A-Z]{2})?$": {
|
|
463
|
+
"^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": {
|
|
464
464
|
"type": "object",
|
|
465
465
|
"description": "Localized fields for this locale",
|
|
466
466
|
"properties": {
|
|
@@ -514,7 +514,7 @@
|
|
|
514
514
|
"type": "object",
|
|
515
515
|
"description": "Localized facilitator guide fields with one entry per supported locale. Each declared locale must have a matching content/<locale>/ directory.",
|
|
516
516
|
"patternProperties": {
|
|
517
|
-
"^[a-z]{2}(-[A-Z]{2})?$": {
|
|
517
|
+
"^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": {
|
|
518
518
|
"type": "object",
|
|
519
519
|
"description": "Localized fields for this locale",
|
|
520
520
|
"properties": {
|
|
@@ -563,7 +563,7 @@
|
|
|
563
563
|
"description": "List of locales supported by this game (e.g., ['en', 'es', 'fr'])",
|
|
564
564
|
"items": {
|
|
565
565
|
"type": "string",
|
|
566
|
-
"pattern": "^[a-z]{2}(-[A-Z]{2})?$"
|
|
566
|
+
"pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$"
|
|
567
567
|
},
|
|
568
568
|
"minItems": 1,
|
|
569
569
|
"uniqueItems": true
|
|
@@ -572,7 +572,7 @@
|
|
|
572
572
|
"type": "object",
|
|
573
573
|
"description": "Localized game fields with one entry per supported locale",
|
|
574
574
|
"patternProperties": {
|
|
575
|
-
"^[a-z]{2}(-[A-Z]{2})?$": {
|
|
575
|
+
"^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": {
|
|
576
576
|
"type": "object",
|
|
577
577
|
"description": "Localized fields for this locale",
|
|
578
578
|
"properties": {
|
|
@@ -639,7 +639,7 @@
|
|
|
639
639
|
"type": "object",
|
|
640
640
|
"description": "Localised default name for one team, with one entry per supported locale",
|
|
641
641
|
"patternProperties": {
|
|
642
|
-
"^[a-z]{2}(-[A-Z]{2})?$": {
|
|
642
|
+
"^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": {
|
|
643
643
|
"type": "object",
|
|
644
644
|
"description": "Localised fields for this locale",
|
|
645
645
|
"properties": {
|
|
@@ -768,7 +768,7 @@
|
|
|
768
768
|
"type": "object",
|
|
769
769
|
"description": "Localised default name for one team, with one entry per supported locale",
|
|
770
770
|
"patternProperties": {
|
|
771
|
-
"^[a-z]{2}(-[A-Z]{2})?$": {
|
|
771
|
+
"^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": {
|
|
772
772
|
"type": "object",
|
|
773
773
|
"description": "Localised fields for this locale",
|
|
774
774
|
"properties": {
|