@seriousgaming/sdk-tools 1.6.1 → 1.8.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/agent/guidance.md +1 -0
- package/dist/{cli-2NU2LPEE.js → cli-27M4PX7O.js} +17 -17
- package/dist/{cli-2BH7FX27.js → cli-2FXZZLCL.js} +1 -1
- package/dist/{cli-5ACDPCXI.js → cli-2KDV2DYC.js} +3 -3
- package/dist/{cli-OXAUOWCN.js → cli-2QM63J3I.js} +1 -1
- package/dist/{cli-HW53ICZC.js → cli-32NRB2IT.js} +15 -15
- package/dist/{cli-45OCBG53.js → cli-3HBYH4VF.js} +11 -11
- package/dist/{cli-4VFZHLDG.js → cli-3HPAKEJJ.js} +2 -2
- package/dist/{cli-R2MUZQE2.js → cli-3HZGJRQW.js} +11 -11
- package/dist/{cli-PGCIHPU7.js → cli-3OCKRPXI.js} +18 -18
- package/dist/{cli-64AB62PM.js → cli-3OVXQJEW.js} +2 -2
- package/dist/{cli-4UWFQNGF.js → cli-3VV2JLHX.js} +1 -1
- package/dist/{cli-XSLNH5PR.js → cli-42ZUP4X3.js} +141 -5
- package/dist/{cli-ZJFQ7EEA.js → cli-4B5OBHSY.js} +19 -19
- package/dist/{cli-7A6MKCUJ.js → cli-4EMNCU63.js} +27 -19
- package/dist/cli-5CG6BMCY.js +36 -0
- package/dist/{cli-XZCJIKIV.js → cli-5FRKWNVP.js} +19 -19
- package/dist/{cli-Y3DDNMPX.js → cli-5P66N5G6.js} +17 -17
- package/dist/{cli-6VNKQ3OX.js → cli-5SYPXJCB.js} +28 -16
- package/dist/{cli-G6CANSPL.js → cli-66AHBZRZ.js} +15 -15
- package/dist/{cli-BJMS3VX3.js → cli-6AGWTGTO.js} +106 -28
- package/dist/{cli-TTMBBEJC.js → cli-6BAZE75K.js} +18 -18
- package/dist/{cli-GFNDW2DL.js → cli-6FVHRL3H.js} +19 -19
- package/dist/{cli-QVASWX2A.js → cli-6GDPO5VU.js} +2 -2
- package/dist/{cli-7XLHO2FE.js → cli-6NBER36P.js} +1 -1
- package/dist/{cli-FQRVFGN6.js → cli-726NJARI.js} +0 -0
- package/dist/{cli-CD5CIJZI.js → cli-72DRYVTT.js} +13 -13
- package/dist/{cli-MMN4BPO4.js → cli-7CW2BBJG.js} +1 -1
- package/dist/{cli-XAT25PRU.js → cli-7GJGFILU.js} +15 -15
- package/dist/{cli-HFX3YPUL.js → cli-7NCVUM5U.js} +3 -3
- package/dist/cli-7S4G4EKK.js +110 -0
- package/dist/{cli-J4DKUUTK.js → cli-7V6GUIIS.js} +2 -2
- package/dist/{cli-N6H6T2E2.js → cli-AEAFLZGY.js} +12 -0
- package/dist/{cli-C47GJATR.js → cli-AGYCXRPR.js} +3 -3
- package/dist/{cli-XSVGKI3R.js → cli-BC4KKNLA.js} +1 -1
- package/dist/cli-BQ3FHENQ.js +16 -0
- package/dist/{cli-KGM6RRQW.js → cli-BXCCODYD.js} +20 -20
- package/dist/cli-C2XDL4LD.js +30 -0
- package/dist/{cli-MJUYJIEP.js → cli-C45A5VX6.js} +3 -3
- package/dist/{cli-DOXRQ3S5.js → cli-C7YZNPWX.js} +11 -11
- package/dist/{cli-HOE3WLFH.js → cli-CAX4CQTC.js} +13 -13
- package/dist/{cli-YOTGR3NB.js → cli-CVOLMK3Z.js} +1 -1
- package/dist/{cli-ILFDANBR.js → cli-D3CZRXVJ.js} +63 -17
- package/dist/{cli-4YB3ROVR.js → cli-DMKRP33X.js} +1 -1
- package/dist/{cli-Y3O5F4JN.js → cli-DPFN2LIZ.js} +15 -15
- package/dist/{cli-6UTPHWRQ.js → cli-DT756M3Z.js} +20 -20
- package/dist/{cli-TIDQ4WUE.js → cli-DXHPYN4N.js} +1 -1
- package/dist/{cli-6K3VQQUS.js → cli-E665NKUQ.js} +5 -5
- package/dist/{cli-O5ABH2WK.js → cli-EK7CGMGS.js} +17 -17
- package/dist/{cli-6QB2VFPY.js → cli-ESU3J563.js} +15 -15
- package/dist/{cli-VPRRICZA.js → cli-F47ELAXM.js} +47 -47
- package/dist/{cli-RLEGRWFM.js → cli-FH4WBZHA.js} +14 -14
- package/dist/{cli-3D3ZXWOV.js → cli-FHKRO6OU.js} +19 -19
- package/dist/{cli-JZCLIT3O.js → cli-FSEDPZR5.js} +19 -19
- package/dist/{cli-XOTNXEJA.js → cli-FV45UZQP.js} +19 -19
- package/dist/{cli-AV2FYC5G.js → cli-G7FX7ZIU.js} +12 -12
- package/dist/{cli-IP4RXGHM.js → cli-GFONBOJT.js} +129 -38
- package/dist/{cli-C5QOJJWX.js → cli-GHIMH6JU.js} +1 -1
- package/dist/{cli-IDVUHGKG.js → cli-HC7L5DXV.js} +15 -15
- package/dist/{cli-WU43JT4T.js → cli-HJPNNORV.js} +2 -2
- package/dist/{cli-QY5NZAR7.js → cli-HMEZHQBC.js} +17 -17
- package/dist/{cli-JZOZOEZM.js → cli-HQUVSAHY.js} +18 -18
- package/dist/{cli-MYJGMA6U.js → cli-IC5FOT2J.js} +1 -1
- package/dist/{cli-VL2P354N.js → cli-IVZ7AHUJ.js} +3 -3
- package/dist/{cli-B6YHEKIJ.js → cli-J2OTL6JH.js} +5 -5
- package/dist/{cli-Z56ZIVA6.js → cli-JA6UFTSX.js} +17 -17
- package/dist/{cli-MJV47HKI.js → cli-JOXCAGM7.js} +19 -19
- package/dist/{cli-ZBN5KAIB.js → cli-JQ6I5GGE.js} +3 -3
- package/dist/{cli-TDSQSCX4.js → cli-K6M6YB67.js} +1 -1
- package/dist/{cli-C6ZLPK2U.js → cli-KFVA7DT3.js} +3 -3
- package/dist/{cli-KOGRWFN7.js → cli-KH6FKM5A.js} +15 -15
- package/dist/{cli-5IAW3LIF.js → cli-KMT235FV.js} +2 -2
- package/dist/{cli-ZDUADFBY.js → cli-KU4PG7ZA.js} +15 -15
- package/dist/{cli-N45DREM4.js → cli-L4DEEAMK.js} +17 -17
- package/dist/{cli-MU5LB43S.js → cli-ME3JKMJL.js} +19 -19
- package/dist/{cli-C3CMJSNL.js → cli-MJ65PIYI.js} +15 -15
- package/dist/cli-MM2ROZWO.js +36 -0
- package/dist/{cli-RZITKPJX.js → cli-MN7X4UG2.js} +1 -1
- package/dist/{cli-4SIWLHQO.js → cli-MPU4FLA7.js} +4 -4
- package/dist/{cli-HCRTYQQS.js → cli-MPWTXNF6.js} +2 -2
- package/dist/{cli-EVI36HEM.js → cli-N5K2KHPR.js} +15 -15
- package/dist/{cli-RSW6EBBD.js → cli-NGOQWOQE.js} +15 -15
- package/dist/{cli-ZTWOE3ZT.js → cli-NU4SCD5D.js} +1 -1
- package/dist/{cli-BYCHKSSH.js → cli-O3IMNLN2.js} +282 -96
- package/dist/{cli-KGT5L7VZ.js → cli-OUFXSQOW.js} +7265 -4467
- package/dist/{cli-DFBTZEBX.js → cli-PEY6XZDE.js} +16 -16
- package/dist/{cli-QUSCIUOM.js → cli-PLW3TWJ7.js} +19 -19
- package/dist/{cli-JVI24FI6.js → cli-PO2ALWHP.js} +13 -13
- package/dist/{cli-3BRC32CP.js → cli-PPEB3ENS.js} +18 -18
- package/dist/{cli-ZDOTXEKL.js → cli-PZ7G544B.js} +3 -3
- package/dist/{cli-L7VYSXQK.js → cli-Q5BKFFDL.js} +4 -4
- package/dist/{cli-3ZKWV3PN.js → cli-QAI6T5FL.js} +15 -15
- package/dist/{cli-KSGB2ZLK.js → cli-QAVLRCQ5.js} +3 -3
- package/dist/{cli-VDBW23SS.js → cli-QDIH2G2P.js} +15 -15
- package/dist/cli-SN7D7HTX.js +36 -0
- package/dist/{cli-IEMKI7J7.js → cli-SOQJHK4Q.js} +6 -6
- package/dist/{cli-4PXNOJQX.js → cli-SPKPDXWD.js} +15 -15
- package/dist/{cli-MOPSZ3CS.js → cli-SWUAXVIJ.js} +15 -15
- package/dist/cli-TJNLXQJ5.js +36 -0
- package/dist/{cli-BUQI5UU4.js → cli-U2EWI6H5.js} +11 -11
- package/dist/{cli-TT36JCU5.js → cli-UADUC4JD.js} +2 -2
- package/dist/{cli-FWFRKQNE.js → cli-UR63LFVK.js} +2 -2
- package/dist/{cli-J4UBELKF.js → cli-UTHPCZYL.js} +2 -2
- package/dist/{cli-Q6ZBZYK2.js → cli-UYV3BDPA.js} +3 -3
- package/dist/{cli-LQOHATY2.js → cli-UZCQL6YP.js} +3 -3
- package/dist/{cli-HKORECAG.js → cli-V5K3CCYZ.js} +2 -2
- package/dist/cli-V7L3HEL4.js +36 -0
- package/dist/{cli-HSIHDN6K.js → cli-VBSF3R3L.js} +16 -16
- package/dist/{cli-NROTDF5Y.js → cli-VQ4OJ4KE.js} +18 -18
- package/dist/{cli-IUS2YCD3.js → cli-VTLFQHDO.js} +1 -1
- package/dist/{cli-JJSWBW4H.js → cli-W7XCTGQ7.js} +15 -15
- package/dist/{cli-UZZFNXRX.js → cli-W7Y7X3FX.js} +19 -19
- package/dist/cli-WWNTBK37.js +1973 -0
- package/dist/cli-XPJGW375.js +36 -0
- package/dist/{cli-SRHBXZCN.js → cli-Y33ULHYO.js} +1 -1
- package/dist/{cli-TTKICM5P.js → cli-YLYB4ITF.js} +13 -13
- package/dist/{cli-72XDEFU3.js → cli-ZFY6TGU7.js} +4 -4
- package/dist/{cli-6SGCYEEC.js → cli-ZSKP2IRP.js} +53 -38
- package/dist/cli.js +53 -51
- package/dist/client.js +17699 -16630
- package/dist/core/game-settings.d.ts +5 -3
- package/dist/core/save-scenario.d.ts +1 -0
- package/dist/core/session-roster.d.ts +10 -0
- package/dist/core/session-start-gate.d.ts +25 -0
- package/dist/core/session.d.ts +4 -0
- package/dist/dev/console/assets/index-CVNjiRUh.js +208 -0
- package/dist/dev/console/index.html +1 -1
- package/dist/dev/routes.d.ts +5 -2
- package/dist/dev/shell.d.ts +9 -1
- package/dist/dev/view/batch.d.ts +11 -1
- package/dist/dev/view/route.d.ts +18 -1
- package/dist/dev/view/view.d.ts +9 -0
- package/dist/docs/api/deck.md +1 -1
- package/dist/docs/api/index.md +2 -2
- package/dist/docs/api/sdk-commands.md +4 -0
- package/dist/docs/api/sdk-e2e.md +12 -6
- package/dist/docs/api/sdk-projection.md +1 -0
- package/dist/docs/api/sdk-tools-client.md +7 -1
- package/dist/docs/api/sdk-tools-playwright.md +1 -8
- package/dist/docs/api/sdk-ui-testing.md +1 -0
- package/dist/docs/api/sdk-ui.md +67 -63
- package/dist/docs/api/sdk.md +12 -1
- package/dist/docs/changelog.md +26 -0
- package/dist/docs/cli-and-dev-server.md +4 -0
- package/dist/docs/cli-error-codes.md +7 -1
- package/dist/docs/cli-reference.md +20 -2
- package/dist/docs/concepts/index.md +1 -0
- package/dist/docs/guides/engine.md +5 -0
- package/dist/docs/guides/file-handling.md +4 -1
- package/dist/docs/guides/llm-integration.md +3 -2
- package/dist/docs/guides/multi-team-games.md +2 -0
- package/dist/docs/guides/patterns.md +5 -0
- package/dist/docs/guides/presentation.md +11 -10
- package/dist/docs/guides/session-hooks.md +16 -0
- package/dist/docs/guides/session.md +1 -1
- package/dist/docs/guides/settings.md +6 -2
- package/dist/docs/guides/setup.md +23 -2
- package/dist/docs/guides/speech-generation.md +1 -0
- package/dist/docs/guides/testing.md +2 -0
- package/dist/docs/guides/tick-controller.md +2 -0
- package/dist/docs/guides/type-safety.md +2 -1
- package/dist/docs/guides/ui-files-and-llms.md +3 -1
- package/dist/docs/guides/upgrading.md +16 -0
- package/dist/docs/guides/validators.md +27 -4
- package/dist/docs/guides/waiting-room.md +2 -0
- package/dist/docs/page-index.md +12 -10
- package/dist/docs/recipes/call-endpoint-from-ui.md +1 -0
- package/dist/docs/recipes/create-scenario-editor.md +2 -1
- package/dist/docs/recipes/create-setup.md +2 -1
- package/dist/docs/recipes/declare-api-uses.md +1 -0
- package/dist/docs/recipes/describe-setup-with-endpoint.md +69 -0
- package/dist/docs/recipes/index.md +3 -1
- package/dist/docs/recipes/share-logic-between-engine-and-ui.md +2 -2
- package/dist/docs/recipes/test-user-interface.md +1 -1
- package/dist/docs/recipes/validate-scenarios.md +9 -3
- package/dist/docs/recipes/write-setup-notes.md +58 -0
- package/dist/docs/troubleshooting.md +2 -1
- package/dist/execution/executor.d.ts +12 -0
- package/dist/execution/scenario-gates.d.ts +40 -0
- package/dist/host/protocol.d.ts +10 -1
- package/dist/host.js +1083 -467
- package/dist/playwright.js +17760 -16691
- package/dist/runtime/manifest-version.d.ts +1 -1
- package/dist/runtime.js +4 -2
- package/dist/schema.json +10 -1
- package/dist/setup/setup-notes.d.ts +42 -0
- package/dist/templates/package/package.json.liquid +15 -15
- package/dist/templates/starter-game/package.json +13 -13
- package/dist/utils/error-codes.d.ts +13 -1
- package/dist/validation/package-validation.d.ts +1 -1
- package/package.json +22 -23
- package/dist/cli-2GZYGRVL.js +0 -36
- package/dist/cli-5SM367K7.js +0 -30
- package/dist/cli-DDJYUKQG.js +0 -36
- package/dist/cli-LK3V4RI5.js +0 -36
- package/dist/cli-N24OHSAN.js +0 -36
- package/dist/cli-OMWC75CC.js +0 -256
- package/dist/cli-RCIWBCXD.js +0 -36
- package/dist/cli-UMEBPAZQ.js +0 -16
- package/dist/cli-VQ6HVQW4.js +0 -4010
- package/dist/cli-WR3NOY74.js +0 -36
- package/dist/dev/console/assets/index-CuMOOH9m.js +0 -204
|
@@ -198,6 +198,7 @@ The engine receives `readAsset` in its callbacks. It accepts an `asset:`, `share
|
|
|
198
198
|
|
|
199
199
|
```typescript
|
|
200
200
|
import { decodeUtf8, getText, type RunFunction } from '@seriousgaming/sdk';
|
|
201
|
+
|
|
201
202
|
import type { Context, Settings } from './types';
|
|
202
203
|
|
|
203
204
|
export const Run: RunFunction<Context, Settings> = async ({ context, callbacks }) => {
|
|
@@ -266,6 +267,7 @@ Declare `"uses": ["extractText", "generateText"]` on the engine, and pass the ge
|
|
|
266
267
|
|
|
267
268
|
```typescript
|
|
268
269
|
import { getText, type RunFunction } from '@seriousgaming/sdk';
|
|
270
|
+
|
|
269
271
|
import type { Callbacks, Context, Settings } from './types';
|
|
270
272
|
|
|
271
273
|
export const Run: RunFunction<Context, Settings, Callbacks> = async ({
|
|
@@ -317,8 +319,9 @@ export const Handle: Handler = async ({ request, callbacks }) => {
|
|
|
317
319
|
The endpoint bundle declares `"uses": ["extractText"]`; the UI declares the endpoint in its `endpoints` array and calls it:
|
|
318
320
|
|
|
319
321
|
```tsx
|
|
320
|
-
import { useState } from 'react';
|
|
321
322
|
import { useUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
|
|
323
|
+
import { useState } from 'react';
|
|
324
|
+
|
|
322
325
|
import type { Callbacks } from '../types';
|
|
323
326
|
|
|
324
327
|
function DocumentProcessor() {
|
|
@@ -164,10 +164,10 @@ All engine functions are async and receive a `callbacks` parameter:
|
|
|
164
164
|
|
|
165
165
|
```typescript
|
|
166
166
|
import { RunFunction } from '@seriousgaming/sdk';
|
|
167
|
-
import type { Context, Settings } from './types';
|
|
168
|
-
|
|
169
167
|
import { getText } from '@seriousgaming/sdk';
|
|
170
168
|
|
|
169
|
+
import type { Context, Settings } from './types';
|
|
170
|
+
|
|
171
171
|
export const Run: RunFunction<Context, Settings> = async ({ context, settings, callbacks }) => {
|
|
172
172
|
// Simple text generation (quick tier by default)
|
|
173
173
|
const response = await callbacks.generateText('Your prompt here');
|
|
@@ -481,6 +481,7 @@ The endpoint bundle declares `"uses": ["generateText"]` and runs the LLM call se
|
|
|
481
481
|
```typescript
|
|
482
482
|
// endpoints/chat/logic/logic.ts
|
|
483
483
|
import { getText } from '@seriousgaming/sdk';
|
|
484
|
+
|
|
484
485
|
import type { Handler } from '../types';
|
|
485
486
|
|
|
486
487
|
export const Handle: Handler = async ({ request, callbacks }) => {
|
|
@@ -279,6 +279,7 @@ import {
|
|
|
279
279
|
InitAggregateFunction,
|
|
280
280
|
RunAggregateFunction,
|
|
281
281
|
} from '@seriousgaming/sdk';
|
|
282
|
+
|
|
282
283
|
import type { Context, Settings, SharedContext, TeamContext } from './types';
|
|
283
284
|
|
|
284
285
|
// Per-team init: set this team's own default values
|
|
@@ -413,6 +414,7 @@ Each entry in the `teams` array is `{ teamId, index, context }`, and the array i
|
|
|
413
414
|
|
|
414
415
|
```typescript
|
|
415
416
|
import { RunAggregateFunction } from '@seriousgaming/sdk';
|
|
417
|
+
|
|
416
418
|
import type { Settings, SharedContext, TeamContext } from './types';
|
|
417
419
|
|
|
418
420
|
// Per-team starting capital, indexed by the stable team index
|
|
@@ -64,6 +64,7 @@ pnpm run sdk new engine '{
|
|
|
64
64
|
|
|
65
65
|
```typescript
|
|
66
66
|
import { RunFunction } from '@seriousgaming/sdk';
|
|
67
|
+
|
|
67
68
|
import type { Context, Settings } from './types';
|
|
68
69
|
|
|
69
70
|
export const Run: RunFunction<Context, Settings> = async ({ context, settings }) => {
|
|
@@ -166,6 +167,7 @@ pnpm run sdk update engine '{
|
|
|
166
167
|
|
|
167
168
|
```typescript
|
|
168
169
|
import type { StepFunction } from '@seriousgaming/sdk';
|
|
170
|
+
|
|
169
171
|
import type { Context, Settings } from './types';
|
|
170
172
|
|
|
171
173
|
export const runInventory: StepFunction<Context, Settings> = async ({ context, settings }) => {
|
|
@@ -185,6 +187,7 @@ export const runInventory: StepFunction<Context, Settings> = async ({ context, s
|
|
|
185
187
|
|
|
186
188
|
```typescript
|
|
187
189
|
import type { StepFunction } from '@seriousgaming/sdk';
|
|
190
|
+
|
|
188
191
|
import type { Context, Settings } from './types';
|
|
189
192
|
|
|
190
193
|
export const runSales: StepFunction<Context, Settings> = async ({ context, settings }) => {
|
|
@@ -213,6 +216,7 @@ export const runSales: StepFunction<Context, Settings> = async ({ context, setti
|
|
|
213
216
|
|
|
214
217
|
```typescript
|
|
215
218
|
import { RunFunction } from '@seriousgaming/sdk';
|
|
219
|
+
|
|
216
220
|
import { runInventory } from './inventory';
|
|
217
221
|
import { runSales } from './sales';
|
|
218
222
|
import type { Context, Settings } from './types';
|
|
@@ -385,6 +389,7 @@ export const runCosts: StepFunction<Context, Settings> = async ({ context, setti
|
|
|
385
389
|
|
|
386
390
|
```typescript
|
|
387
391
|
import { RunFunction } from '@seriousgaming/sdk';
|
|
392
|
+
|
|
388
393
|
import { runCosts } from './costs';
|
|
389
394
|
import { runDemand } from './demand';
|
|
390
395
|
import { runProduction } from './production';
|
|
@@ -53,15 +53,15 @@ const { game, session, settings, theme, locale, getPastState, getAssetUrl } = us
|
|
|
53
53
|
>();
|
|
54
54
|
```
|
|
55
55
|
|
|
56
|
-
| Field | What it holds
|
|
57
|
-
| -------------- |
|
|
58
|
-
| `game` | `name` in the current locale, `maxTicks` (or `null` when the engine or tick controller decides), `mode`, and `scenarioName` (or `null`). Present with or without a session
|
|
59
|
-
| `session` | `null` with no session. Otherwise its `id`, `name`, `completedTicks` (the most rounds any team has completed, 0 before the first), `data` (the shared store and every team, narrowed to `reads`), `teams`, and how the room joins: `participants`, `joinLinks` and `joinPin` (see [Showing the room how to join](#showing-the-room-how-to-join)) |
|
|
60
|
-
| `settings` | The settings resources the presentation declares, resolved for the scenario, and for the session when there is one
|
|
61
|
-
| `theme` | The host's theme, to map onto the deck's colours
|
|
62
|
-
| `locale` | The locale to render in
|
|
63
|
-
| `getPastState` | Reads past rounds, as the session UI does, with `teams` defaulting to every team. Rejects when there is no session
|
|
64
|
-
| `getAssetUrl` | Turns an `asset:`, `shared:` or `blob:` reference into a URL
|
|
56
|
+
| Field | What it holds |
|
|
57
|
+
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
58
|
+
| `game` | `name` in the current locale, `maxTicks` (or `null` when the engine or tick controller decides), `mode`, and `scenarioName` (or `null`). Present with or without a session |
|
|
59
|
+
| `session` | `null` with no session. Otherwise its `id`, `name`, `completedTicks` (the most rounds any team has completed, 0 before the first), `data` (the shared store and every team, narrowed to `reads`), `teams`, and how the room joins: `participants`, `joinLinks`, `sessionJoinLink` and `joinPin` (see [Showing the room how to join](#showing-the-room-how-to-join)) |
|
|
60
|
+
| `settings` | The settings resources the presentation declares, resolved for the scenario, and for the session when there is one |
|
|
61
|
+
| `theme` | The host's theme, to map onto the deck's colours |
|
|
62
|
+
| `locale` | The locale to render in |
|
|
63
|
+
| `getPastState` | Reads past rounds, as the session UI does, with `teams` defaulting to every team. Rejects when there is no session |
|
|
64
|
+
| `getAssetUrl` | Turns an `asset:`, `shared:` or `blob:` reference into a URL |
|
|
65
65
|
|
|
66
66
|
A presentation sees every team: it is the facilitator's view of the room.
|
|
67
67
|
|
|
@@ -90,10 +90,11 @@ export function useResults(): Results {
|
|
|
90
90
|
The first slides are often on the projector while the room arrives, so a session carries what a join slide needs:
|
|
91
91
|
|
|
92
92
|
- **`joinLinks`**: one entry per team, in index order, each `{ teamId, joinUrl, fallbackJoinUrl? }`. Encode `joinUrl` in a QR code; offer `fallbackJoinUrl` only on request. There is no observe URL: watching a team is the facilitator's tool, not the room's
|
|
93
|
+
- **`sessionJoinLink`**: one link for the whole room, `{ joinUrl, fallbackJoinUrl? }`, or `null` when the host has none or the game turns it off. The host puts whoever follows it in a team, and no host promises which, so show it as one code for everyone and keep the team links for anyone who needs a particular team
|
|
93
94
|
- **`joinPin`**: the code to enter alongside the link, or `null` when joining needs none. Show it beside the link, never inside it
|
|
94
95
|
- **`participants`**: every team's participants, `connected` or not, for a count of who has arrived
|
|
95
96
|
|
|
96
|
-
All
|
|
97
|
+
All four are optional in the type. A host that predates them leaves them out, so render a placeholder there, as you would with no session.
|
|
97
98
|
|
|
98
99
|
### Varying by scenario
|
|
99
100
|
|
|
@@ -76,6 +76,21 @@ const teamLinks = useSessionUserInterfaceTeamLinks();
|
|
|
76
76
|
|
|
77
77
|
Encode `joinUrl` in a QR code: the host chose that form because a denser code is harder to scan across a room. Show `fallbackJoinUrl` on request rather than beside it, for the networks that block URL shorteners. `observeUrl` opens the team's game UI as an observer, with no participant identity and no presence.
|
|
78
78
|
|
|
79
|
+
## useSessionUserInterfaceSessionJoinLink
|
|
80
|
+
|
|
81
|
+
Get the session's one join link, for a single QR code the whole room scans:
|
|
82
|
+
|
|
83
|
+
```typescript
|
|
84
|
+
import { useSessionUserInterfaceSessionJoinLink } from '@seriousgaming/sdk/ui';
|
|
85
|
+
|
|
86
|
+
const sessionLink = useSessionUserInterfaceSessionJoinLink();
|
|
87
|
+
// SessionJoinLink | null: { joinUrl, fallbackJoinUrl? }
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Somebody who follows it is placed in a team by the host, rather than choosing one, and joins as an ordinary participant. That is what a room of many small teams needs: one code on the projector instead of one per team. Encode `joinUrl` and offer `fallbackJoinUrl` on request, as with the team links.
|
|
91
|
+
|
|
92
|
+
It is `null` until the host sends it, on a host with no session link, and for a game that turns it off, so fall back to the team links whenever it is. Never depend on which team somebody lands in: hosts choose differently, and none promises an order or a balance. If it matters, move people afterwards with `moveParticipant`, or turn the link off with `teams.sessionJoin` (see [The game settings](./settings.md#the-game-settings)).
|
|
93
|
+
|
|
79
94
|
## useSessionUserInterfaceHostOverlays
|
|
80
95
|
|
|
81
96
|
Find out which host overlays this host offers, before rendering a control for one:
|
|
@@ -201,5 +216,6 @@ Additional messages sent after initialisation:
|
|
|
201
216
|
| -------------------- | -------------------------------------------------------------------------------------------------------- |
|
|
202
217
|
| `setTeamList` | Updates the list of teams in the session (`TeamInfo[]`, each `{ teamId, index, name }`, sorted by index) |
|
|
203
218
|
| `setTeamLinks` | Updates each team's facilitator-only join and observe URLs |
|
|
219
|
+
| `setSessionJoinLink` | Updates the session's one join link, or `null` when there is none |
|
|
204
220
|
| `setParticipantList` | Updates the participant roster across all teams |
|
|
205
221
|
| `hookFailed` | Reports a hook chain that threw |
|
|
@@ -406,8 +406,8 @@ Read colours from the theme hook below rather than hard-coding them, so your ses
|
|
|
406
406
|
Edit `src/theme.ts` to use the session theme hook, and turn it into MUI theme options with `createSurfaceTheme`:
|
|
407
407
|
|
|
408
408
|
```typescript
|
|
409
|
-
import { createSurfaceTheme, useSessionUserInterfaceTheme } from '@seriousgaming/sdk/ui';
|
|
410
409
|
import { createTheme } from '@mui/material/styles';
|
|
410
|
+
import { createSurfaceTheme, useSessionUserInterfaceTheme } from '@seriousgaming/sdk/ui';
|
|
411
411
|
import { useMemo } from 'react';
|
|
412
412
|
|
|
413
413
|
export function useAppTheme() {
|
|
@@ -232,6 +232,7 @@ The engine, hooks, validators, the tick controller and endpoints receive `settin
|
|
|
232
232
|
|
|
233
233
|
```typescript
|
|
234
234
|
import type { RunFunction } from '@seriousgaming/sdk';
|
|
235
|
+
|
|
235
236
|
import type { Context, Settings } from './types';
|
|
236
237
|
|
|
237
238
|
export const Run: RunFunction<Context, Settings> = async ({ context, settings }) => {
|
|
@@ -253,6 +254,7 @@ A game UI, session UI and waiting room UI read `settings` from their data hook:
|
|
|
253
254
|
|
|
254
255
|
```tsx
|
|
255
256
|
import { useUserInterfaceData } from '@seriousgaming/sdk/ui';
|
|
257
|
+
|
|
256
258
|
import type { Context, Settings } from '../types';
|
|
257
259
|
|
|
258
260
|
function PricePanel() {
|
|
@@ -293,7 +295,7 @@ Keep a value in a capability only when it changes during play, or when it is com
|
|
|
293
295
|
|
|
294
296
|
## The game settings
|
|
295
297
|
|
|
296
|
-
Every game has one built-in settings resource, `game`, holding the game-level settings: how many ticks (rounds) it plays, how many teams a session may hold, how many participants a team is meant for, what the teams are called to begin with, and whether the waiting room opens with the session. It is a settings resource like any other, with two differences: the SDK owns its schema, and the game sets its values in `seriousgaming.sdk.json` rather than in `settings/game/`.
|
|
298
|
+
Every game has one built-in settings resource, `game`, holding the game-level settings: how many ticks (rounds) it plays, how many teams a session may hold, how many participants a team is meant for, what the teams are called to begin with, whether one link may join the whole session, and whether the waiting room opens with the session. It is a settings resource like any other, with two differences: the SDK owns its schema, and the game sets its values in `seriousgaming.sdk.json` rather than in `settings/game/`.
|
|
297
299
|
|
|
298
300
|
| Setting | The game's value, in `seriousgaming.sdk.json` | What it does |
|
|
299
301
|
| --------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------- |
|
|
@@ -301,6 +303,7 @@ Every game has one built-in settings resource, `game`, holding the game-level se
|
|
|
301
303
|
| `teams.min`, `teams.max` | `teams.min` and `teams.max`, or `null` for no bound | The fewest teams play can start with, and the most a session can hold |
|
|
302
304
|
| `teams.perTeam.minParticipants`, `.maxParticipants` | `teams.perTeam`, or `null` | Guidance on team size shown to the facilitator, never a limit on joining |
|
|
303
305
|
| `teams.defaultNames` | `teams.defaultNames`, or `[]` | The names teams start with, by team index. A facilitator or the team can rename |
|
|
306
|
+
| `teams.sessionJoin` | `teams.sessionJoin`, or `true` | Whether the host may offer one join link for the whole session |
|
|
304
307
|
| `waitingRoom.openOnStart` | `waitingRoom.openOnStart`, or `false` | Whether a new session starts with participants held in the waiting room |
|
|
305
308
|
|
|
306
309
|
`teams.mode` stays in the manifest and is not a setting: a game is independent or shared-state, and nothing can change that.
|
|
@@ -312,9 +315,10 @@ Override the game settings as you would any other, under `game`:
|
|
|
312
315
|
- **`sdk configure`** sets them on the dev server: `pnpm run sdk configure '{"game":{"maxTicks":6}}'`
|
|
313
316
|
- **Any resource can read them** by listing `game` in its `settings`, and its generated `types.ts` types them
|
|
314
317
|
|
|
315
|
-
|
|
318
|
+
Three rules are particular to these settings:
|
|
316
319
|
|
|
317
320
|
- **`waitingRoom.openOnStart` is set by the game or a scenario, never by setup.** It takes effect as the session is created, before setup runs, so a setup value would do nothing, and is refused
|
|
321
|
+
- **`teams.sessionJoin` is set by the game or a scenario, never by setup.** It is read as the session is created, because people can follow the session link before play starts, so a setup value is refused. Set it to `false` when your teams are not interchangeable, such as one role per team or teams set up by index: the host places whoever follows the session link in a team of its own choosing, so a game like that hands out team links instead (see [useSessionUserInterfaceSessionJoinLink](./session-hooks.md#usesessionuserinterfacesessionjoinlink))
|
|
318
322
|
- **Play cannot start outside the team bounds.** Setup can change `teams.min` and `teams.max` after the teams were created, so play is refused while the team count is outside them. Add or remove teams, or change the setting, and start again
|
|
319
323
|
|
|
320
324
|
A settings resource of your own may not be called `game`, and is refused with a message saying what to change.
|
|
@@ -62,8 +62,9 @@ setup/
|
|
|
62
62
|
Spreading `settings` into an update is safe: an unchanged value is never stored as a facilitator override, so a scenario chosen later still applies to it.
|
|
63
63
|
|
|
64
64
|
```tsx
|
|
65
|
-
import { useSettingsEditor } from '@seriousgaming/sdk/ui';
|
|
66
65
|
import { Stack, TextField } from '@mui/material';
|
|
66
|
+
import { useSettingsEditor } from '@seriousgaming/sdk/ui';
|
|
67
|
+
|
|
67
68
|
import type { Settings } from '../types';
|
|
68
69
|
|
|
69
70
|
function SetupForm() {
|
|
@@ -116,8 +117,8 @@ A write is also refused, as `denied` and with none of it applied, when it change
|
|
|
116
117
|
`useSettingsEditorCallbacks()` gives the screen `requestPlay`, which leaves the configuration step exactly as the host's Play control does:
|
|
117
118
|
|
|
118
119
|
```tsx
|
|
119
|
-
import { useSettingsEditorCallbacks } from '@seriousgaming/sdk/ui';
|
|
120
120
|
import { Button } from '@mui/material';
|
|
121
|
+
import { useSettingsEditorCallbacks } from '@seriousgaming/sdk/ui';
|
|
121
122
|
|
|
122
123
|
function StartButton() {
|
|
123
124
|
const { requestPlay } = useSettingsEditorCallbacks();
|
|
@@ -150,6 +151,24 @@ Setup is embedded in the host's page, not a page of its own:
|
|
|
150
151
|
|
|
151
152
|
The [session UI guide](./session.md#rendering-inside-the-host) covers the same ground in more detail.
|
|
152
153
|
|
|
154
|
+
## Notes for assistants
|
|
155
|
+
|
|
156
|
+
An AI assistant can set a session up for a facilitator, changing the settings your setup screen `configures`. From the schemas alone it cannot tell which few settings matter, or what 'make it a bit harder' means in your game. Tell it in setup notes: Markdown at `setup/notes/<locale>.md`, one file per locale.
|
|
157
|
+
|
|
158
|
+
```markdown
|
|
159
|
+
## What requests mean
|
|
160
|
+
|
|
161
|
+
- **'Harder'**: lower `engine.BaseDemand` to 7,000 and raise `engine.DemandPriceModifier` to 700
|
|
162
|
+
- **'Shorter'**: set `game.maxTicks` to 6
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
- **Name each setting as a setting path in a code span**, such as `engine.BaseDemand`: an assistant writes it back as it stands. The build checks every code span that starts with one of your settings identifiers, failing on one that names no setting (`SETTINGS_UNKNOWN`) and warning on one your setup screen does not configure (`SETUP_NOTES_UNCONFIGURED`)
|
|
166
|
+
- **Say what a schema cannot**: the two to five choices worth asking about, what common requests mean as settings and values, and what to leave alone. Where a request matches a scenario, say to pick that scenario
|
|
167
|
+
- **They are for assistants.** Your setup screen is what a facilitator sees, and a host need not show the notes to anyone. They grant nothing: an assistant is held to `configures` and to your game's [Scenario gate](./validators.md#when-it-runs) like anyone else
|
|
168
|
+
- **Locales fall back** from the assistant's locale to `en`, then your first supported locale
|
|
169
|
+
|
|
170
|
+
The build ships them as written. In the dev server, **Notes for assistants** on the configuration step shows them exactly as an assistant receives them. `examples/factory` has a set; see [Write setup notes for assistants](../recipes/write-setup-notes.md), and [Describe a setup with an endpoint](../recipes/describe-setup-with-endpoint.md) to let an assistant read a setup back in your game's words.
|
|
171
|
+
|
|
153
172
|
## Dev server behaviour
|
|
154
173
|
|
|
155
174
|
`pnpm run sdk dev` opens a game with a setup slot at its configuration step, on `/setup`. Fill in the form and press Play (or your own control). Once play starts, `/setup` shows that the step has closed; **Reconfigure** in the dev drawer returns the session to it and every team to tick 0. Overrides persist in `.seriousgaming-sdk/` between runs, and `pnpm run sdk configure` sets them from the command line.
|
|
@@ -173,6 +192,7 @@ Deleting the slot removes the configuration step: the game then starts at tick 0
|
|
|
173
192
|
|
|
174
193
|
```tsx
|
|
175
194
|
import { renderSettingsEditor } from '@seriousgaming/sdk/ui/testing';
|
|
195
|
+
|
|
176
196
|
import { defaultSettings } from '../defaults';
|
|
177
197
|
|
|
178
198
|
renderSettingsEditor(<SetupForm />, {
|
|
@@ -188,3 +208,4 @@ See [Test a user interface](../recipes/test-user-interface.md).
|
|
|
188
208
|
- [Settings](./settings.md): declaring, reading, and overriding settings
|
|
189
209
|
- [Scenarios](./scenarios.md)
|
|
190
210
|
- [Create a setup screen](../recipes/create-setup.md)
|
|
211
|
+
- [Write setup notes for assistants](../recipes/write-setup-notes.md)
|
|
@@ -123,6 +123,7 @@ For ElevenLabs, the defaults are `eleven_flash_v2_5` (quick), `eleven_turbo_v2_5
|
|
|
123
123
|
|
|
124
124
|
```typescript
|
|
125
125
|
import type { RunFunction } from '@seriousgaming/sdk';
|
|
126
|
+
|
|
126
127
|
import type { Context, Settings, Callbacks } from '../types';
|
|
127
128
|
|
|
128
129
|
export const Run: RunFunction<Context, Settings, Callbacks> = async ({
|
|
@@ -47,6 +47,7 @@ Every capability variable must declare a `default` for this to work. The build s
|
|
|
47
47
|
// engine/logic.test.ts
|
|
48
48
|
import { logicArgs } from '@seriousgaming/sdk/testing';
|
|
49
49
|
import { describe, it, expect } from 'vitest';
|
|
50
|
+
|
|
50
51
|
import { defaultSettings, defaultContext } from './defaults';
|
|
51
52
|
import { Run } from './logic';
|
|
52
53
|
import type { Context, Settings } from './types';
|
|
@@ -122,6 +123,7 @@ describe('Warehouse Init', () => {
|
|
|
122
123
|
|
|
123
124
|
```typescript
|
|
124
125
|
import { logicArgs } from '@seriousgaming/sdk/testing';
|
|
126
|
+
|
|
125
127
|
import { defaultSettings, defaultSharedContext, defaultTeamContext } from './defaults';
|
|
126
128
|
import { RunAggregate } from './logic';
|
|
127
129
|
|
|
@@ -78,6 +78,7 @@ The generated `tick_controller/logic.ts` exports a `GetTickController` function.
|
|
|
78
78
|
|
|
79
79
|
```typescript
|
|
80
80
|
import { GetTickControllerFunction, intervalTick } from '@seriousgaming/sdk';
|
|
81
|
+
|
|
81
82
|
import type { Context, Settings } from './types';
|
|
82
83
|
|
|
83
84
|
export const GetTickController: GetTickControllerFunction<Context, Settings> = async ({
|
|
@@ -444,6 +445,7 @@ The SDK provides helpers that compute the next occurrence of a daily or weekly t
|
|
|
444
445
|
|
|
445
446
|
```typescript
|
|
446
447
|
import { GetTickControllerFunction, nextDailyAt, scheduledTick } from '@seriousgaming/sdk';
|
|
448
|
+
|
|
447
449
|
import type { Context, Settings } from './types';
|
|
448
450
|
|
|
449
451
|
export const GetTickController: GetTickControllerFunction<Context, Settings> = async ({
|
|
@@ -45,9 +45,10 @@ export const Run: RunFunction<any, any> = async ({ context, settings, callbacks
|
|
|
45
45
|
### ✅ CORRECT: using generated types
|
|
46
46
|
|
|
47
47
|
```typescript
|
|
48
|
+
import { RunFunction } from '@seriousgaming/sdk';
|
|
49
|
+
|
|
48
50
|
// logic.ts
|
|
49
51
|
import type { Context, Settings } from './types';
|
|
50
|
-
import { RunFunction } from '@seriousgaming/sdk';
|
|
51
52
|
|
|
52
53
|
// ✅ CORRECT
|
|
53
54
|
export const Run: RunFunction<Context, Settings> = async ({ context, settings, callbacks }) => {
|
|
@@ -149,6 +149,7 @@ The endpoint bundle declares `"uses": ["generateText"]` and runs the LLM call:
|
|
|
149
149
|
```typescript
|
|
150
150
|
// endpoints/chat/logic/logic.ts
|
|
151
151
|
import { getText } from '@seriousgaming/sdk';
|
|
152
|
+
|
|
152
153
|
import type { Handler } from '../types';
|
|
153
154
|
|
|
154
155
|
export const Handle: Handler = async ({ request, callbacks }) => {
|
|
@@ -178,8 +179,9 @@ The UI bundle declares the endpoint in its `endpoints` array. A UI bundle has no
|
|
|
178
179
|
Access `callbacks.endpoints` with the `useUserInterfaceCallbacks` hook. Persist the conversation in a capability so it survives across ticks:
|
|
179
180
|
|
|
180
181
|
```tsx
|
|
181
|
-
import { useState } from 'react';
|
|
182
182
|
import { useUserInterfaceCallbacks, useUserInterfaceData } from '@seriousgaming/sdk/ui';
|
|
183
|
+
import { useState } from 'react';
|
|
184
|
+
|
|
183
185
|
import type { Context, Settings } from '../types';
|
|
184
186
|
import type { Callbacks } from '../types';
|
|
185
187
|
|
|
@@ -152,6 +152,7 @@ grep -rn "configuration" testing scripts
|
|
|
152
152
|
|
|
153
153
|
```typescript
|
|
154
154
|
import type { RunFunction } from '@seriousgaming/sdk';
|
|
155
|
+
|
|
155
156
|
import type { Context, Settings } from './types';
|
|
156
157
|
|
|
157
158
|
export const Run: RunFunction<Context, Settings> = async ({ context, settings }) => {
|
|
@@ -276,6 +277,7 @@ An engine that splits `Init` or `Run` into several functions typed as `RunFuncti
|
|
|
276
277
|
|
|
277
278
|
```typescript
|
|
278
279
|
import type { RunFunction, StepFunction } from '@seriousgaming/sdk';
|
|
280
|
+
|
|
279
281
|
import type { Context, Settings } from './types';
|
|
280
282
|
|
|
281
283
|
export const runSales: StepFunction<Context, Settings> = async ({ context }) => ({
|
|
@@ -295,6 +297,7 @@ An aggregate engine split into steps works the same way. There is no step type f
|
|
|
295
297
|
|
|
296
298
|
```typescript
|
|
297
299
|
import type { RunAggregateFunction } from '@seriousgaming/sdk';
|
|
300
|
+
|
|
298
301
|
import type { Settings, SharedContext, TeamContext } from './types';
|
|
299
302
|
|
|
300
303
|
type Board = { shared: SharedContext; teams: TeamContext[] };
|
|
@@ -550,6 +553,7 @@ Every logic call now receives `meta.now` (the operation's time in milliseconds)
|
|
|
550
553
|
|
|
551
554
|
```typescript
|
|
552
555
|
import { logicArgs } from '@seriousgaming/sdk/testing';
|
|
556
|
+
|
|
553
557
|
import { defaultSettings } from '../../engine/defaults';
|
|
554
558
|
|
|
555
559
|
const result = await Run(logicArgs.run({ context, settings: defaultSettings }));
|
|
@@ -684,6 +688,18 @@ renderUserInterface(<App />, { callbacks: { requestTick } });
|
|
|
684
688
|
|
|
685
689
|
These types are outside semantic versioning from 1.3, so the helpers are the way to keep up with later additions too. See [What a minor release may change](./testing.md#what-a-minor-release-may-change).
|
|
686
690
|
|
|
691
|
+
### 1.7: turn off the session join link where teams are not interchangeable
|
|
692
|
+
|
|
693
|
+
A host may now offer one join link for the whole session and put each person who follows it in a team of its choosing. A game that gives each team a role, or sets teams up by index, should not offer it. Set it off in `seriousgaming.sdk.json` and rebuild:
|
|
694
|
+
|
|
695
|
+
```json
|
|
696
|
+
{
|
|
697
|
+
"teams": { "mode": "independent", "sessionJoin": false }
|
|
698
|
+
}
|
|
699
|
+
```
|
|
700
|
+
|
|
701
|
+
A game whose teams are interchangeable needs nothing. A test that builds the `game` settings by hand, rather than spreading the generated `defaultSettings`, adds `sessionJoin` to `teams`.
|
|
702
|
+
|
|
687
703
|
### Optional: import the SDK's agent guidance in `CLAUDE.md`
|
|
688
704
|
|
|
689
705
|
A new package's `CLAUDE.md` no longer holds a copy of the SDK's guidance. Its first line imports the copy that ships with `@seriousgaming/sdk-tools`, so the guidance always matches the installed version, and the rest of the file is the package's own. An older package keeps the copy it was scaffolded with, which goes stale with every upgrade and, in a package that began as the starter game, describes the lemonade stand after a reskin.
|
|
@@ -110,7 +110,8 @@ Each validator is told who submitted the mutation, as `actor`:
|
|
|
110
110
|
|
|
111
111
|
```typescript
|
|
112
112
|
type ValidatorActor =
|
|
113
|
-
{ role: 'participant'; participant: Participant }
|
|
113
|
+
| { role: 'participant'; participant: Participant }
|
|
114
|
+
| { role: 'observer'; teamId: string };
|
|
114
115
|
```
|
|
115
116
|
|
|
116
117
|
It is a union rather than an optional participant, because these are two callers rather than an identity and the absence of one. `participant` is unreachable until you have narrowed on `role`, so a validator cannot read an identity it has not first decided it has.
|
|
@@ -288,8 +289,30 @@ const judge = (ui: Partial<Settings['ui']>) =>
|
|
|
288
289
|
### When it runs
|
|
289
290
|
|
|
290
291
|
- **`sdk build`** runs it on every scenario in `scenarios/`, and on the defaults alone when no scenario is the default, since a session can then run on no scenario. A problem fails the build (`SCENARIO_REFUSED`), pointing at the setting in the scenario's file
|
|
291
|
-
- **Saving a scenario** runs it, from the scenario editor, a form the platform generates, or an agent writing settings, and a problem refuses the save with every problem listed
|
|
292
|
-
- **
|
|
292
|
+
- **Saving a scenario** runs it, from the scenario editor, a form the platform generates, or an agent writing settings, and a problem refuses the save with every problem listed. A gate that runs out of time is run once more first, since a busy host can push a sound gate over its time limit
|
|
293
|
+
- **As a session starts**, when the game lists `session-validation` in `requires`. It judges the session's own settings, what setup changed over the scenario, and a session it finds an error with does not start: the facilitator, or an agent setting the session up, sees every problem and changes the setting. A session nobody changed, on a scenario the build checked, is not judged again. Without `session-validation`, a session is never refused on the gate
|
|
294
|
+
|
|
295
|
+
```json
|
|
296
|
+
"requires": ["scenario-validation", "session-validation"]
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
In the dev server, Play shows the refusal or the warnings, `pnpm run sdk play` prints the warnings, and `pnpm run sdk configure` runs the gate before it saves anything, so a refused change is never written and a running session is left as it was.
|
|
300
|
+
|
|
301
|
+
A gate that throws also stops a session starting, and is reported as a fault in the game rather than in its settings, since changing a setting will not clear it. One that runs out of time is run once more first, since a busy host can push a sound gate over its time limit, and refuses only if it overruns again. Nothing overrides it, so test your gate against the settings your setup screen can produce. The build notes each settings resource your setup UI changes that no `Scenario` gate declares in its `settings` (`SETTINGS_UNGATED`): nothing checks those changes before play.
|
|
302
|
+
|
|
303
|
+
### Errors and warnings
|
|
304
|
+
|
|
305
|
+
A problem is an error unless you say otherwise. Give it `level: 'warning'` for something unusual that may well be meant, such as a story week outside the rounds the game plays. A warning is reported wherever an error is, by the build (`SCENARIO_WARNING`), with a saved scenario and with a session start, and never refuses any of them:
|
|
306
|
+
|
|
307
|
+
```typescript
|
|
308
|
+
problems.push({
|
|
309
|
+
path: settingPath('engine', 'CostPerUnit'),
|
|
310
|
+
level: 'warning',
|
|
311
|
+
message: 'Making a unit costs nothing, so unsold stock never costs a team anything',
|
|
312
|
+
});
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
Keep errors for what breaks play, such as a document that never arrives. With `session-validation`, an error stops a facilitator starting their session, so a borderline case is better as a warning. `examples/factory`'s `scenariocheck` validator warns on a unit cost of £0.
|
|
293
316
|
|
|
294
317
|
### It judges values, not where they came from
|
|
295
318
|
|
|
@@ -305,7 +328,7 @@ The gate is the last word, and it runs on save. A [scenario editor](./scenario-e
|
|
|
305
328
|
|
|
306
329
|
The gate reads no game state and receives no `actor` or `meta`: there is no session or participant behind a scenario. Its only callbacks are the file reads above. It ignores the validator's `reads`, so a validator that only exports `Scenario` declares none.
|
|
307
330
|
|
|
308
|
-
|
|
331
|
+
Without `session-validation`, the gate runs when a scenario is saved, not each time one is used, so a scenario a facilitator saved before you added or tightened a rule has never met it. Bump `scenarioFormat` in `seriousgaming.sdk.json` when you do, and a runtime stops using those older scenarios. See [Scenario format: when to bump it](./scenarios.md#scenario-format-when-to-bump-it).
|
|
309
332
|
|
|
310
333
|
## Settings
|
|
311
334
|
|
|
@@ -81,6 +81,7 @@ Same as any game UI. Declare the capability in `reads`, regenerate, and read it
|
|
|
81
81
|
|
|
82
82
|
```typescript
|
|
83
83
|
import { useUserInterfaceData } from '@seriousgaming/sdk/ui';
|
|
84
|
+
|
|
84
85
|
import type { Context, Settings } from '../types';
|
|
85
86
|
|
|
86
87
|
function App() {
|
|
@@ -182,6 +183,7 @@ Opening the room pauses nothing. The decision belongs to the game, because only
|
|
|
182
183
|
|
|
183
184
|
```typescript
|
|
184
185
|
import type { GetTickControllerFunction } from '@seriousgaming/sdk';
|
|
186
|
+
|
|
185
187
|
import type { Context, Settings } from '../types';
|
|
186
188
|
|
|
187
189
|
export const GetTickController: GetTickControllerFunction<Context, Settings> = async ({
|
package/dist/docs/page-index.md
CHANGED
|
@@ -25,8 +25,8 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
|
|
|
25
25
|
- [`changelog-0.x.md`](changelog-0.x.md): Every release before 1.0, from 0.0.1 to 0.6.0, kept as history.
|
|
26
26
|
- [`changelog.md`](changelog.md): All notable changes to the Serious Gaming SDK are recorded here.
|
|
27
27
|
- [`cli-and-dev-server.md`](cli-and-dev-server.md), about 15k characters: The dev server runs your game on your own machine, with every screen in the browser, and the CLI plays and inspects the same session from the terminal.
|
|
28
|
-
- [`cli-error-codes.md`](cli-error-codes.md), about
|
|
29
|
-
- [`cli-reference.md`](cli-reference.md), about
|
|
28
|
+
- [`cli-error-codes.md`](cli-error-codes.md), about 32k characters: Every code a failed `seriousgaming-sdk` command can report.
|
|
29
|
+
- [`cli-reference.md`](cli-reference.md), about 163k characters: Every `seriousgaming-sdk` command and flag, in one place.
|
|
30
30
|
- [`cli-simulation-testing.md`](cli-simulation-testing.md), about 11k characters: Play a game from the terminal: configure it, start a session, make decisions, advance ticks, and read the state back as JSON.
|
|
31
31
|
- [`environment-variables.md`](environment-variables.md), about 10k characters: A single reference for every environment variable the dev server and CLI read.
|
|
32
32
|
- [`getting-started.md`](getting-started.md), about 11k characters: Scaffold the starter game, play it in the dev server, change one thing, and see the change.
|
|
@@ -56,15 +56,15 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
|
|
|
56
56
|
- [`guides/llm-integration.md`](guides/llm-integration.md), about 26k characters: Use generated text to give teams feedback, play characters, or write round reports that react to what they did.
|
|
57
57
|
- [`guides/multi-team-games.md`](guides/multi-team-games.md), about 35k characters: Let teams compete for one market, cooperate on a shared goal, or each play their own copy of the game.
|
|
58
58
|
- [`guides/patterns.md`](guides/patterns.md), about 12k characters: Three patterns for an engine's state and logic, each built up from the CLI commands that create its resources: a stock level that never goes negative, revenue computed in a second step, and a production loop split into one step per concern.
|
|
59
|
-
- [`guides/presentation.md`](guides/presentation.md), about
|
|
59
|
+
- [`guides/presentation.md`](guides/presentation.md), about 17k characters: Ship the facilitator's slide deck as part of the game, live with the session's results and exportable for anyone who wants to edit it.
|
|
60
60
|
- [`guides/production-constraints.md`](guides/production-constraints.md), about 10k characters: In production your UI bundle runs cross-origin, behind a strict content security policy and a short-lived auth cookie, and talks to the host only through a typed message channel.
|
|
61
61
|
- [`guides/scenario-editor.md`](guides/scenario-editor.md), about 10k characters: The `scenario_editor` slot holds the screen people use to build new scenarios for a released game, without rebuilding it.
|
|
62
62
|
- [`guides/scenarios.md`](guides/scenarios.md), about 31k characters: A scenario is a named set of settings overrides and static assets that makes a distinct flavour of a game: a different storyline, difficulty preset, or themed variant.
|
|
63
63
|
- [`guides/session-game-flow.md`](guides/session-game-flow.md), about 20k characters: How a session UI drives the session: ticks, the timer, host overlays, undo and reset, the waiting room, the language, the roster, and the participant list.
|
|
64
|
-
- [`guides/session-hooks.md`](guides/session-hooks.md), about
|
|
64
|
+
- [`guides/session-hooks.md`](guides/session-hooks.md), about 15k characters: Every hook a session UI reads its data and callbacks from, and the messages the host sends it.
|
|
65
65
|
- [`guides/session.md`](guides/session.md), about 23k characters: The session UI is the facilitator's view of the whole room: every team's position side by side, with the controls to run the session.
|
|
66
66
|
- [`guides/settings.md`](guides/settings.md), about 34k characters: Settings are a game's read-only parameters: a price, a difficulty, a round length, a menu, an answer key.
|
|
67
|
-
- [`guides/setup.md`](guides/setup.md), about
|
|
67
|
+
- [`guides/setup.md`](guides/setup.md), about 11k characters: The `setup` slot holds the small form a facilitator fills in when they create a session.
|
|
68
68
|
- [`guides/speech-generation.md`](guides/speech-generation.md), about 10k characters: Give characters and briefings a voice: generate speech from server-side logic and play it in any UI.
|
|
69
69
|
- [`guides/starter-game.md`](guides/starter-game.md), about 18k characters: `new package` hands you Lemonade Stand, a complete game rather than an empty shell.
|
|
70
70
|
- [`guides/testing.md`](guides/testing.md), about 34k characters: Test your engine's logic and your user interfaces, so a broken rule or a broken screen fails on your machine rather than in front of a room.
|
|
@@ -76,8 +76,8 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
|
|
|
76
76
|
- [`guides/ui-styling.md`](guides/ui-styling.md), about 11k characters: How a game UI handles language, theme, and screen size, and how to customise the Vite build that serves and bundles it.
|
|
77
77
|
- [`guides/ui-ticks.md`](guides/ui-ticks.md), about 15k characters: How a game UI ends a round and shows the time left: requesting a tick, awaiting a write or tick and handling a `MutationError`, and driving a countdown from the tick timer.
|
|
78
78
|
- [`guides/ui.md`](guides/ui.md), about 17k characters: The game UI is what each participant sees and plays: where they read the situation, make decisions, and see what those decisions caused.
|
|
79
|
-
- [`guides/upgrading.md`](guides/upgrading.md), about
|
|
80
|
-
- [`guides/validators.md`](guides/validators.md), about
|
|
79
|
+
- [`guides/upgrading.md`](guides/upgrading.md), about 68k characters: This guide takes a game package on 0.6 to 1.0, in 13 steps.
|
|
80
|
+
- [`guides/validators.md`](guides/validators.md), about 25k characters: A validator is a read-only gate on what a participant does: a context write before it is applied, and a request for the next tick before it runs.
|
|
81
81
|
- [`guides/waiting-room.md`](guides/waiting-room.md), about 14k characters: The waiting room is the holding screen participants see while a session is parked, and you can replace the host's stock panel with your own.
|
|
82
82
|
|
|
83
83
|
## Recipes
|
|
@@ -105,6 +105,7 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
|
|
|
105
105
|
- [`recipes/create-validator.md`](recipes/create-validator.md), about 4k characters: Reject a participant's write that breaks the game's rules, before the runtime applies it.
|
|
106
106
|
- [`recipes/create-waiting-room-ui.md`](recipes/create-waiting-room-ui.md), about 5k characters: Replace the host's stock holding screen with your own, so participants see your branding and your words while the facilitator has the waiting room open.
|
|
107
107
|
- [`recipes/declare-api-uses.md`](recipes/declare-api-uses.md), about 4k characters: A logic-bearing resource (engine, hook, tick controller, endpoint) must declare the runtime callbacks it intends to call.
|
|
108
|
+
- [`recipes/describe-setup-with-endpoint.md`](recipes/describe-setup-with-endpoint.md), about 3k characters: Let an assistant, or your own setup screen, ask your game to describe a session's settings in the game's own words before it starts.
|
|
108
109
|
- [`recipes/design-state-for-concurrent-writes.md`](recipes/design-state-for-concurrent-writes.md), about 6k characters: Shape capabilities and `setData` calls so that several participants writing at once never overwrite each other.
|
|
109
110
|
- [`recipes/distribute-package.md`](recipes/distribute-package.md), about 3k characters: Wrap a built `dist/` directory into a single zip archive that a production runtime can ingest as an upload.
|
|
110
111
|
- [`recipes/e2e-testing.md`](recipes/e2e-testing.md), about 6k characters: Test your game's screens in a real browser against an isolated dev server.
|
|
@@ -129,7 +130,8 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
|
|
|
129
130
|
- [`recipes/upload-and-display-files.md`](recipes/upload-and-display-files.md), about 6k characters: Let a participant attach a file (a PDF, CSV, or image) in the game UI, show it back, and optionally summarise it in the engine.
|
|
130
131
|
- [`recipes/use-request-play.md`](recipes/use-request-play.md), about 2k characters: Leave the configuration step and start the game from within your setup screen, so operators can move to play from your own control as well as from the host's Play button.
|
|
131
132
|
- [`recipes/use-request-tick.md`](recipes/use-request-tick.md), about 3k characters: Trigger the next game tick from within your user interface, so participants submit their decisions via your own button.
|
|
132
|
-
- [`recipes/validate-scenarios.md`](recipes/validate-scenarios.md), about
|
|
133
|
+
- [`recipes/validate-scenarios.md`](recipes/validate-scenarios.md), about 5k characters: Refuse a scenario whose settings break your game's rules, at build and when one is saved, and optionally a session whose setup breaks them.
|
|
134
|
+
- [`recipes/write-setup-notes.md`](recipes/write-setup-notes.md), about 3k characters: Tell an AI assistant setting a session up which of your game's settings matter, and what a request such as 'make it a bit harder' means in your game.
|
|
133
135
|
|
|
134
136
|
## API reference
|
|
135
137
|
|
|
@@ -142,5 +144,5 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
|
|
|
142
144
|
- [`api/sdk-tools-client.md`](api/sdk-tools-client.md), about 14k characters: Programmatic API for testing a game in-process.
|
|
143
145
|
- [`api/sdk-tools-playwright.md`](api/sdk-tools-playwright.md), about 3k characters: Playwright for a game's browser tests: a dev server for each worker.
|
|
144
146
|
- [`api/sdk-ui-testing.md`](api/sdk-ui-testing.md), about 8k characters: Every export of `@seriousgaming/sdk/ui/testing`, with the declaration it is published with.
|
|
145
|
-
- [`api/sdk-ui.md`](api/sdk-ui.md), about
|
|
146
|
-
- [`api/sdk.md`](api/sdk.md), about
|
|
147
|
+
- [`api/sdk-ui.md`](api/sdk-ui.md), about 36k characters: Every export of `@seriousgaming/sdk/ui`, with the declaration it is published with.
|
|
148
|
+
- [`api/sdk.md`](api/sdk.md), about 59k characters: Every export of `@seriousgaming/sdk`, with the declaration it is published with.
|
|
@@ -27,6 +27,7 @@ Call a server-side endpoint from any of your game's screens and handle its respo
|
|
|
27
27
|
|
|
28
28
|
```tsx
|
|
29
29
|
import { useUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
|
|
30
|
+
|
|
30
31
|
import type { Callbacks } from '../types';
|
|
31
32
|
|
|
32
33
|
function ReportButton({ reportText }: { reportText: string }) {
|
|
@@ -44,8 +44,9 @@ This creates `scenario_editor/` with `scenario_editor.sdk.json`, `index.html`, `
|
|
|
44
44
|
Open `scenario_editor/src/App.tsx`. It uses the same hooks as setup:
|
|
45
45
|
|
|
46
46
|
```tsx
|
|
47
|
-
import { useSettingsEditor } from '@seriousgaming/sdk/ui';
|
|
48
47
|
import { Stack, TextField } from '@mui/material';
|
|
48
|
+
import { useSettingsEditor } from '@seriousgaming/sdk/ui';
|
|
49
|
+
|
|
49
50
|
import type { Settings } from '../types';
|
|
50
51
|
|
|
51
52
|
function App() {
|
|
@@ -48,8 +48,9 @@ setup/
|
|
|
48
48
|
Open `setup/src/App.tsx`. Read and write the settings with `useSettingsEditor`, typed by the generated `Settings`:
|
|
49
49
|
|
|
50
50
|
```tsx
|
|
51
|
-
import { useSettingsEditor, useSettingsEditorCallbacks } from '@seriousgaming/sdk/ui';
|
|
52
51
|
import { Button, Stack, TextField } from '@mui/material';
|
|
52
|
+
import { useSettingsEditor, useSettingsEditorCallbacks } from '@seriousgaming/sdk/ui';
|
|
53
|
+
|
|
53
54
|
import type { Settings } from '../types';
|
|
54
55
|
|
|
55
56
|
function App() {
|
|
@@ -30,6 +30,7 @@ A logic-bearing resource (engine, hook, tick controller, endpoint) must declare
|
|
|
30
30
|
|
|
31
31
|
```typescript
|
|
32
32
|
import { getText, type RunFunction } from '@seriousgaming/sdk';
|
|
33
|
+
|
|
33
34
|
import type { Context, Settings, Callbacks } from './types';
|
|
34
35
|
|
|
35
36
|
export const Run: RunFunction<Context, Settings, Callbacks> = async ({
|