@seriousgaming/sdk-tools 1.7.0 → 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-ZTZ5H55T.js → cli-27M4PX7O.js} +17 -17
- package/dist/{cli-2BH7FX27.js → cli-2FXZZLCL.js} +1 -1
- package/dist/{cli-HHPMAV4F.js → cli-2KDV2DYC.js} +3 -3
- package/dist/{cli-57V4ARER.js → cli-2QM63J3I.js} +1 -1
- package/dist/{cli-TFMNNVJ7.js → cli-32NRB2IT.js} +15 -15
- package/dist/{cli-JPAXKLVT.js → cli-3HBYH4VF.js} +11 -11
- package/dist/{cli-JR5AZLLK.js → cli-3HPAKEJJ.js} +2 -2
- package/dist/{cli-3PIJLSRQ.js → cli-3HZGJRQW.js} +11 -11
- package/dist/{cli-BOXXMDSX.js → cli-3OCKRPXI.js} +18 -18
- package/dist/{cli-4CHKF4DQ.js → cli-3OVXQJEW.js} +2 -2
- package/dist/{cli-4UWFQNGF.js → cli-3VV2JLHX.js} +1 -1
- package/dist/{cli-EJVAQCMQ.js → cli-42ZUP4X3.js} +114 -5
- package/dist/{cli-CV4JGVJR.js → cli-4B5OBHSY.js} +19 -19
- package/dist/{cli-2DQJACAH.js → cli-4EMNCU63.js} +17 -17
- package/dist/cli-5CG6BMCY.js +36 -0
- package/dist/{cli-VYR326C6.js → cli-5FRKWNVP.js} +19 -19
- package/dist/{cli-TDYKRXUA.js → cli-5P66N5G6.js} +17 -17
- package/dist/{cli-ZRPWZOCW.js → cli-5SYPXJCB.js} +20 -16
- package/dist/{cli-TJ3PLRHF.js → cli-66AHBZRZ.js} +15 -15
- package/dist/{cli-M7WEAIRF.js → cli-6AGWTGTO.js} +106 -28
- package/dist/{cli-WG36UJRK.js → cli-6BAZE75K.js} +18 -18
- package/dist/{cli-VPON5HGB.js → cli-6FVHRL3H.js} +19 -19
- package/dist/{cli-QVASWX2A.js → cli-6GDPO5VU.js} +2 -2
- package/dist/{cli-TPNQLYPC.js → cli-6NBER36P.js} +1 -1
- package/dist/{cli-LQ4VSM5R.js → cli-726NJARI.js} +0 -0
- package/dist/{cli-GHLILDH7.js → cli-72DRYVTT.js} +13 -13
- package/dist/{cli-MMN4BPO4.js → cli-7CW2BBJG.js} +1 -1
- package/dist/{cli-FP32D3T6.js → cli-7GJGFILU.js} +15 -15
- package/dist/{cli-HYEU3QS6.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-CXCL7VRK.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-64AA7367.js → cli-C7YZNPWX.js} +11 -11
- package/dist/{cli-ZKG3OPZ6.js → cli-CAX4CQTC.js} +13 -13
- package/dist/{cli-YOTGR3NB.js → cli-CVOLMK3Z.js} +1 -1
- package/dist/{cli-PKQNOGBO.js → cli-D3CZRXVJ.js} +63 -17
- package/dist/{cli-4YB3ROVR.js → cli-DMKRP33X.js} +1 -1
- package/dist/{cli-FZ7QAZZP.js → cli-DPFN2LIZ.js} +15 -15
- package/dist/{cli-7TOLC62D.js → cli-DT756M3Z.js} +20 -20
- package/dist/{cli-TIDQ4WUE.js → cli-DXHPYN4N.js} +1 -1
- package/dist/{cli-OANH3BTQ.js → cli-E665NKUQ.js} +5 -5
- package/dist/{cli-DEBCP7UH.js → cli-EK7CGMGS.js} +17 -17
- package/dist/{cli-PIO7NWMH.js → cli-ESU3J563.js} +15 -15
- package/dist/{cli-6HB6HTC6.js → cli-F47ELAXM.js} +47 -47
- package/dist/{cli-JIZTQVL2.js → cli-FH4WBZHA.js} +14 -14
- package/dist/{cli-JRMHSMYT.js → cli-FHKRO6OU.js} +19 -19
- package/dist/{cli-ESA6YNPF.js → cli-FSEDPZR5.js} +19 -19
- package/dist/{cli-G5DQGZ2E.js → cli-FV45UZQP.js} +19 -19
- package/dist/{cli-XR2XSWQN.js → cli-G7FX7ZIU.js} +12 -12
- package/dist/{cli-X7E3637I.js → cli-GFONBOJT.js} +50 -26
- package/dist/{cli-C5QOJJWX.js → cli-GHIMH6JU.js} +1 -1
- package/dist/{cli-T4HWGMY4.js → cli-HC7L5DXV.js} +15 -15
- package/dist/{cli-WU43JT4T.js → cli-HJPNNORV.js} +2 -2
- package/dist/{cli-SOMIB4B4.js → cli-HMEZHQBC.js} +17 -17
- package/dist/{cli-TFZ53OA2.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-NEOLMC2P.js → cli-JA6UFTSX.js} +17 -17
- package/dist/{cli-Z5HWENER.js → cli-JOXCAGM7.js} +19 -19
- package/dist/{cli-NOQBWJQN.js → cli-JQ6I5GGE.js} +3 -3
- package/dist/{cli-TDSQSCX4.js → cli-K6M6YB67.js} +1 -1
- package/dist/{cli-MYJGGLC5.js → cli-KFVA7DT3.js} +3 -3
- package/dist/{cli-DHOWZCXT.js → cli-KH6FKM5A.js} +15 -15
- package/dist/{cli-4VZIJYKU.js → cli-KMT235FV.js} +2 -2
- package/dist/{cli-6ZSMW4HR.js → cli-KU4PG7ZA.js} +15 -15
- package/dist/{cli-ATI6OLJU.js → cli-L4DEEAMK.js} +17 -17
- package/dist/{cli-EDCAH2TC.js → cli-ME3JKMJL.js} +19 -19
- package/dist/{cli-R7RG2VMW.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-LE5ICDAF.js → cli-MPU4FLA7.js} +4 -4
- package/dist/{cli-HCRTYQQS.js → cli-MPWTXNF6.js} +2 -2
- package/dist/{cli-NPPY557S.js → cli-N5K2KHPR.js} +15 -15
- package/dist/{cli-PVA52RC2.js → cli-NGOQWOQE.js} +15 -15
- package/dist/{cli-ZTWOE3ZT.js → cli-NU4SCD5D.js} +1 -1
- package/dist/{cli-UTM4QU67.js → cli-O3IMNLN2.js} +282 -96
- package/dist/{cli-MM3A4SPH.js → cli-OUFXSQOW.js} +7265 -4467
- package/dist/{cli-UBQCSUDH.js → cli-PEY6XZDE.js} +16 -16
- package/dist/{cli-HM7CD4VU.js → cli-PLW3TWJ7.js} +19 -19
- package/dist/{cli-LRQDF3ZO.js → cli-PO2ALWHP.js} +13 -13
- package/dist/{cli-IPP5FDCH.js → cli-PPEB3ENS.js} +18 -18
- package/dist/{cli-C3OERMIR.js → cli-PZ7G544B.js} +3 -3
- package/dist/{cli-GPAN6XK2.js → cli-Q5BKFFDL.js} +4 -4
- package/dist/{cli-MULKSLA4.js → cli-QAI6T5FL.js} +15 -15
- package/dist/{cli-JGFJWZFU.js → cli-QAVLRCQ5.js} +3 -3
- package/dist/{cli-OQG3Y4RU.js → cli-QDIH2G2P.js} +15 -15
- package/dist/cli-SN7D7HTX.js +36 -0
- package/dist/{cli-SWZY7L7K.js → cli-SOQJHK4Q.js} +6 -6
- package/dist/{cli-7RYIEKMB.js → cli-SPKPDXWD.js} +15 -15
- package/dist/{cli-WAZD75KE.js → cli-SWUAXVIJ.js} +15 -15
- package/dist/cli-TJNLXQJ5.js +36 -0
- package/dist/{cli-SX3ULO5P.js → cli-U2EWI6H5.js} +11 -11
- package/dist/{cli-FXY3DKPW.js → cli-UADUC4JD.js} +2 -2
- package/dist/{cli-FWFRKQNE.js → cli-UR63LFVK.js} +2 -2
- package/dist/{cli-YSPZZQCP.js → cli-UTHPCZYL.js} +2 -2
- package/dist/{cli-XTANOFQR.js → cli-UYV3BDPA.js} +3 -3
- package/dist/{cli-H3J3ICCQ.js → cli-UZCQL6YP.js} +3 -3
- package/dist/{cli-LQERHJFE.js → cli-V5K3CCYZ.js} +2 -2
- package/dist/cli-V7L3HEL4.js +36 -0
- package/dist/{cli-GEQUJF4L.js → cli-VBSF3R3L.js} +16 -16
- package/dist/{cli-FXWWYBYU.js → cli-VQ4OJ4KE.js} +18 -18
- package/dist/{cli-IUS2YCD3.js → cli-VTLFQHDO.js} +1 -1
- package/dist/{cli-SOFCTQAL.js → cli-W7XCTGQ7.js} +15 -15
- package/dist/{cli-GTWEGYSU.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-ZQ2Y3U7F.js → cli-YLYB4ITF.js} +13 -13
- package/dist/{cli-4XCQUM3E.js → cli-ZFY6TGU7.js} +4 -4
- package/dist/{cli-JRIIAZ33.js → cli-ZSKP2IRP.js} +53 -38
- package/dist/cli.js +52 -52
- package/dist/client.js +17518 -16558
- package/dist/core/save-scenario.d.ts +1 -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-CnXlPeLX.js → index-CVNjiRUh.js} +31 -27
- package/dist/dev/console/index.html +1 -1
- package/dist/docs/api/deck.md +1 -1
- package/dist/docs/api/index.md +1 -1
- package/dist/docs/api/sdk-e2e.md +7 -6
- package/dist/docs/api/sdk-projection.md +1 -0
- package/dist/docs/api/sdk-tools-client.md +3 -1
- package/dist/docs/api/sdk-tools-playwright.md +1 -8
- package/dist/docs/api/sdk-ui.md +40 -64
- package/dist/docs/api/sdk.md +10 -1
- package/dist/docs/changelog.md +15 -0
- package/dist/docs/cli-error-codes.md +7 -1
- package/dist/docs/cli-reference.md +3 -0
- 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/session.md +1 -1
- package/dist/docs/guides/settings.md +2 -0
- 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 +4 -0
- package/dist/docs/guides/validators.md +27 -4
- package/dist/docs/guides/waiting-room.md +2 -0
- package/dist/docs/page-index.md +8 -6
- 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.js +1082 -467
- package/dist/playwright.js +17529 -16569
- package/dist/runtime/manifest-version.d.ts +1 -1
- package/dist/runtime.js +4 -2
- 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-57C72YKJ.js +0 -36
- package/dist/cli-5G7TZHD3.js +0 -36
- package/dist/cli-7MBLH4M3.js +0 -36
- package/dist/cli-C6G65H6S.js +0 -256
- package/dist/cli-L5IG7MY2.js +0 -36
- package/dist/cli-SPGUVL6Z.js +0 -36
- package/dist/cli-UY4VDI7W.js +0 -30
- package/dist/cli-WM6SQJ6Q.js +0 -16
- package/dist/cli-ZBTFLZUL.js +0 -36
- package/dist/cli-ZF7IFB54.js +0 -4026
|
@@ -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';
|
|
@@ -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() {
|
|
@@ -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 }));
|
|
@@ -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.
|
|
@@ -64,7 +64,7 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
|
|
|
64
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.
|
|
@@ -77,7 +77,7 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
|
|
|
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
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
|
|
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
|
|
|
@@ -143,4 +145,4 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
|
|
|
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
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.
|
|
146
|
-
- [`api/sdk.md`](api/sdk.md), about
|
|
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 ({
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Describe a setup with an endpoint
|
|
2
|
+
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
**Keywords:** describe setup, summary, confirmation, assistant, agent, external endpoint, setup screen, session-scoped endpoint, settings summary
|
|
6
|
+
|
|
7
|
+
## What you'll build
|
|
8
|
+
|
|
9
|
+
A session-scoped endpoint, `describe_setup`, that reads the settings a session would start on and answers with a sentence a facilitator recognises, such as 'six rounds, a tough market, and factories close after three losing rounds'. An assistant can read it out before asking the facilitator to confirm.
|
|
10
|
+
|
|
11
|
+
## Prerequisites
|
|
12
|
+
|
|
13
|
+
- A [setup screen](create-setup.md)
|
|
14
|
+
- `seriousgaming.sdk.json` in your working directory
|
|
15
|
+
|
|
16
|
+
## Steps
|
|
17
|
+
|
|
18
|
+
1. Create the endpoint, session-scoped and `external` so an assistant can find it, declaring the settings it describes and no `reads`:
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
pnpm run sdk new endpoint '{
|
|
22
|
+
"definition": {
|
|
23
|
+
"identifier": "describe_setup",
|
|
24
|
+
"scope": "session",
|
|
25
|
+
"visibility": "external",
|
|
26
|
+
"description": "Describes the settings this session would start on, in a sentence a facilitator recognises. Call it after changing settings, before asking the facilitator to confirm.",
|
|
27
|
+
"settings": ["engine", "game"],
|
|
28
|
+
"requestSchema": { "type": "object", "properties": {}, "additionalProperties": false },
|
|
29
|
+
"responseSchema": {
|
|
30
|
+
"type": "object",
|
|
31
|
+
"properties": { "summary": { "type": "string" } },
|
|
32
|
+
"required": ["summary"],
|
|
33
|
+
"additionalProperties": false
|
|
34
|
+
}
|
|
35
|
+
},
|
|
36
|
+
"logic": { "directory": "logic", "entrypoint": "logic.ts" },
|
|
37
|
+
"rootDirectory": "."
|
|
38
|
+
}'
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
2. Write the handler in `endpoints/describe_setup/logic/logic.ts`. During setup, `settings` already carries the session's changes:
|
|
42
|
+
|
|
43
|
+
```typescript
|
|
44
|
+
import type { Handler } from '../types';
|
|
45
|
+
|
|
46
|
+
export const Handle: Handler = async ({ settings }) => {
|
|
47
|
+
const rounds = settings.game.maxTicks;
|
|
48
|
+
const length = rounds === null ? 'No round limit' : `${rounds} rounds`;
|
|
49
|
+
const market = settings.engine.BaseDemand < 8000 ? 'a tough market' : 'a forgiving market';
|
|
50
|
+
return { summary: `${length} in ${market}` };
|
|
51
|
+
};
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
3. Optionally, list it in your setup screen's `endpoints` and show the summary beside your Play button
|
|
55
|
+
|
|
56
|
+
## Verify
|
|
57
|
+
|
|
58
|
+
- `pnpm run sdk build --validate-only` passes
|
|
59
|
+
- With `pnpm run sdk dev` at the configuration step, `pnpm run sdk endpoint call describe_setup --request '{}'` answers with the summary, and changes when you change a setting
|
|
60
|
+
|
|
61
|
+
## Troubleshooting
|
|
62
|
+
|
|
63
|
+
- _The endpoint is refused during setup_: it declares `reads` or `writes`. A session in setup has no game state yet, so an endpoint called then declares neither
|
|
64
|
+
- _An assistant cannot find it_: give it `"visibility": "external"` and a `description` saying when to call it
|
|
65
|
+
|
|
66
|
+
## Related
|
|
67
|
+
|
|
68
|
+
- [Endpoints guide: calling from outside the game](../guides/endpoints.md#calling-from-outside-the-game)
|
|
69
|
+
- [Write setup notes for assistants](write-setup-notes.md)
|
|
@@ -34,6 +34,8 @@ New to the SDK? Start with [Getting started](../getting-started.md), which plays
|
|
|
34
34
|
- [Create a session UI](create-session-ui.md): a facilitator screen that shows every team and controls the session
|
|
35
35
|
- [Create a waiting room UI](create-waiting-room-ui.md): replace the host's built-in holding screen with your own
|
|
36
36
|
- [Create a setup screen](create-setup.md): a short form at session creation that sets this session's settings
|
|
37
|
+
- [Write setup notes for assistants](write-setup-notes.md): tell an AI assistant which settings matter and what requests such as 'harder' mean
|
|
38
|
+
- [Describe a setup with an endpoint](describe-setup-with-endpoint.md): let an assistant read back a session's settings in the game's own words
|
|
37
39
|
- [Create a scenario editor](create-scenario-editor.md): a screen for building new scenarios for a released game
|
|
38
40
|
- [Adapt a UI for observers](adapt-ui-for-observers.md): tell a facilitator observing a team from a participant with `useUserInterfaceViewerRole`
|
|
39
41
|
- [Remember a viewer's choice](remember-a-viewers-choice.md): keep a tab, a collapsed panel or a sort order across a reload with `useViewerStorage`, keyed by session, surface and viewer
|
|
@@ -63,7 +65,7 @@ The full reference is the [Multi-team games](../guides/multi-team-games.md) guid
|
|
|
63
65
|
## Validation
|
|
64
66
|
|
|
65
67
|
- [Create a validator](create-validator.md): reject UI mutations that break the game's rules
|
|
66
|
-
- [Validate a game's scenarios](validate-scenarios.md): refuse a scenario whose settings break the game's rules, at build and
|
|
68
|
+
- [Validate a game's scenarios](validate-scenarios.md): refuse a scenario whose settings break the game's rules, at build, on save and optionally as a session starts
|
|
67
69
|
|
|
68
70
|
## Runtime callbacks
|
|
69
71
|
|
|
@@ -85,10 +85,10 @@ Writing the formula twice works right up until someone changes one copy. Then th
|
|
|
85
85
|
4. Import the same file from your UI, and use it only to project. Never to decide:
|
|
86
86
|
|
|
87
87
|
```tsx
|
|
88
|
-
// ui/src/App.tsx
|
|
89
|
-
import { projectShare } from '../../shared/market';
|
|
90
88
|
import { useUserInterfaceCrossTeamData, useUserInterfaceOwnTeam } from '@seriousgaming/sdk/ui';
|
|
91
89
|
|
|
90
|
+
// ui/src/App.tsx
|
|
91
|
+
import { projectShare } from '../../shared/market';
|
|
92
92
|
import type { CrossTeamContext } from '../types';
|
|
93
93
|
|
|
94
94
|
const ownTeam = useUserInterfaceOwnTeam();
|
|
@@ -15,8 +15,8 @@ Write and run component tests for a user interface with Vitest, React Testing Li
|
|
|
15
15
|
2. Render through the helper for the surface, giving it only what the test cares about. Every other context value has a complete default, so never build the providers by hand:
|
|
16
16
|
|
|
17
17
|
```tsx
|
|
18
|
-
import { fireEvent, screen } from '@testing-library/react';
|
|
19
18
|
import { renderUserInterface } from '@seriousgaming/sdk/ui/testing';
|
|
19
|
+
import { fireEvent, screen } from '@testing-library/react';
|
|
20
20
|
import { describe, expect, it, vi } from 'vitest';
|
|
21
21
|
|
|
22
22
|
import { defaultContext, defaultSettings } from '../defaults';
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# Validate a game's scenarios
|
|
2
2
|
|
|
3
|
-
Refuse a scenario whose settings break your game's rules, at build and when one is saved,
|
|
3
|
+
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.
|
|
4
4
|
|
|
5
|
-
**Keywords:** validate scenario, scenario rules, settings conflict, required scenario value, empty default, Scenario gate, scenario-validation, scenario-files, missing file, custom scenario check
|
|
5
|
+
**Keywords:** validate scenario, scenario rules, settings conflict, required scenario value, empty default, Scenario gate, scenario-validation, scenario-files, session-validation, warning, refuse a session start, missing file, custom scenario check
|
|
6
6
|
|
|
7
7
|
## Prerequisites
|
|
8
8
|
|
|
@@ -74,6 +74,10 @@ Refuse a scenario whose settings break your game's rules, at build and when one
|
|
|
74
74
|
|
|
75
75
|
7. Optionally, check the files the scenario names: add `"scenario-files"` to `requires`, and the gate receives `callbacks.describeAsset` and `callbacks.readAsset`, resolved against the scenario being judged. See [Checking the files a scenario names](../guides/validators.md#checking-the-files-a-scenario-names)
|
|
76
76
|
|
|
77
|
+
8. Optionally, judge a session's own settings as it starts: add `"session-validation"` to `requires`, and a session whose setup breaks a rule does not start. See [When it runs](../guides/validators.md#when-it-runs)
|
|
78
|
+
|
|
79
|
+
9. Optionally, mark a problem that is unusual but may be meant with `level: 'warning'`: it is reported, and never refuses a build, a save or a start
|
|
80
|
+
|
|
77
81
|
## Verify
|
|
78
82
|
|
|
79
83
|
- `pnpm run sdk build --validate-only` passes
|
|
@@ -81,7 +85,9 @@ Refuse a scenario whose settings break your game's rules, at build and when one
|
|
|
81
85
|
|
|
82
86
|
## Troubleshooting
|
|
83
87
|
|
|
84
|
-
- _`FEATURE_UNDECLARED` at `/requires`_: add `"scenario-validation"` to `requires`
|
|
88
|
+
- _`FEATURE_UNDECLARED` at `/requires`_: add `"scenario-validation"` to `requires`, beside `"session-validation"` if you list that
|
|
89
|
+
- _`SETTINGS_UNGATED`_: your setup UI changes settings no `Scenario` gate declares, so nothing checks them before play. Add them to the gate's validator `settings` if a change there can break play
|
|
90
|
+
- _'The session cannot start'_ when pressing Play: with `session-validation`, the gate found an error in what setup changed. Change the named setting; a message saying the check failed means the gate threw, which only a fix to the game clears
|
|
85
91
|
- _`SCENARIO_REFUSED` for 'The defaults'_: no scenario is the default, so a session can run on the defaults alone, and they break a rule. Mark a scenario `"default": true`, or change the defaults
|
|
86
92
|
- _A placeholder that is also a real choice_: the gate sees values, not where they came from, so it cannot tell a scenario that chose `0` from one that forgot. Use an obviously empty default (`""`, `[]` or `{}`)
|
|
87
93
|
- _'needs the "scenario-files" feature'_: the gate called `readAsset` or `describeAsset`, which it is handed only when `requires` lists `"scenario-files"`
|