@seriousgaming/sdk-tools 1.7.0 → 1.9.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-SOFCTQAL.js → cli-2BF7KBBJ.js} +15 -15
- package/dist/cli-2CSI2UU2.js +110 -0
- package/dist/{cli-2BH7FX27.js → cli-2FXZZLCL.js} +1 -1
- package/dist/{cli-H3J3ICCQ.js → cli-2I6UN6C3.js} +3 -3
- package/dist/{cli-MYJGGLC5.js → cli-2JEICVMA.js} +3 -3
- package/dist/{cli-7RYIEKMB.js → cli-2PMLR6WG.js} +15 -15
- package/dist/{cli-JRIIAZ33.js → cli-2UOUIVHW.js} +53 -38
- package/dist/{cli-OQG3Y4RU.js → cli-2VV5IPSY.js} +15 -15
- package/dist/{cli-ZRPWZOCW.js → cli-35K37SYY.js} +20 -16
- package/dist/cli-3I6AI4AA.js +36 -0
- package/dist/{cli-YSPZZQCP.js → cli-3RMP4HKZ.js} +2 -2
- package/dist/{cli-4UWFQNGF.js → cli-3VV2JLHX.js} +1 -1
- package/dist/cli-3YGNWZC6.js +30 -0
- package/dist/{cli-TPNQLYPC.js → cli-4L7S27XO.js} +1 -1
- package/dist/cli-4X3X4HB2.js +16 -0
- package/dist/{cli-TJ3PLRHF.js → cli-5BPQ73OM.js} +15 -15
- package/dist/{cli-UTM4QU67.js → cli-5PTCQTS6.js} +282 -96
- package/dist/{cli-ZTZ5H55T.js → cli-6COAU7JR.js} +17 -17
- package/dist/{cli-QVASWX2A.js → cli-6GDPO5VU.js} +2 -2
- package/dist/{cli-TFMNNVJ7.js → cli-6KL5B7EC.js} +15 -15
- package/dist/{cli-NOQBWJQN.js → cli-6Y4XIVQS.js} +3 -3
- package/dist/cli-6ZBQELF2.js +36 -0
- package/dist/{cli-MMN4BPO4.js → cli-7CW2BBJG.js} +1 -1
- package/dist/{cli-LQ4VSM5R.js → cli-7N7WFRWA.js} +0 -0
- package/dist/{cli-JR5AZLLK.js → cli-7OCEVQQN.js} +2 -2
- package/dist/{cli-Z5HWENER.js → cli-7RLZIWFP.js} +19 -19
- package/dist/{cli-J4DKUUTK.js → cli-7V6GUIIS.js} +2 -2
- package/dist/{cli-6ZSMW4HR.js → cli-A3P3PO6Z.js} +15 -15
- package/dist/{cli-4VZIJYKU.js → cli-A7PITFRR.js} +2 -2
- package/dist/{cli-4XCQUM3E.js → cli-AA5GMEUL.js} +4 -4
- package/dist/{cli-N6H6T2E2.js → cli-AEAFLZGY.js} +12 -0
- package/dist/{cli-C47GJATR.js → cli-AGYCXRPR.js} +3 -3
- package/dist/{cli-T4HWGMY4.js → cli-AJ5CABGJ.js} +15 -15
- package/dist/{cli-FZ7QAZZP.js → cli-B5LZEFLU.js} +15 -15
- package/dist/{cli-XSVGKI3R.js → cli-BC4KKNLA.js} +1 -1
- package/dist/{cli-EJVAQCMQ.js → cli-BF6L37O3.js} +114 -5
- package/dist/{cli-ZQ2Y3U7F.js → cli-BNN36WZJ.js} +13 -13
- package/dist/{cli-FXY3DKPW.js → cli-BT47H36C.js} +2 -2
- package/dist/{cli-XTANOFQR.js → cli-BV7MX7JE.js} +3 -3
- package/dist/{cli-PVA52RC2.js → cli-BYXNPBVG.js} +15 -15
- package/dist/{cli-MJUYJIEP.js → cli-C45A5VX6.js} +3 -3
- package/dist/{cli-HM7CD4VU.js → cli-CKV44U7P.js} +19 -19
- package/dist/{cli-LQERHJFE.js → cli-CL3KF5KS.js} +2 -2
- package/dist/{cli-SX3ULO5P.js → cli-CPX4YA3P.js} +11 -11
- package/dist/{cli-CV4JGVJR.js → cli-CQUSM3SF.js} +19 -19
- package/dist/cli-CUZUIYCQ.js +36 -0
- package/dist/{cli-YOTGR3NB.js → cli-CVOLMK3Z.js} +1 -1
- package/dist/{cli-TFZ53OA2.js → cli-D6AC3ZCX.js} +18 -18
- package/dist/{cli-PIO7NWMH.js → cli-DJCQ5XFR.js} +15 -15
- package/dist/{cli-4YB3ROVR.js → cli-DMKRP33X.js} +1 -1
- package/dist/cli-DNCJURUU.js +36 -0
- package/dist/{cli-TIDQ4WUE.js → cli-DXHPYN4N.js} +1 -1
- package/dist/{cli-FP32D3T6.js → cli-E77R7ZYB.js} +15 -15
- package/dist/{cli-PKQNOGBO.js → cli-EDZF5Q2E.js} +63 -17
- package/dist/{cli-IPP5FDCH.js → cli-G54355N5.js} +18 -18
- package/dist/{cli-SWZY7L7K.js → cli-G7JTIP5G.js} +6 -6
- package/dist/{cli-C5QOJJWX.js → cli-GHIMH6JU.js} +1 -1
- package/dist/{cli-LE5ICDAF.js → cli-GHQIATHP.js} +4 -4
- package/dist/{cli-ESA6YNPF.js → cli-GZE4V7RC.js} +19 -19
- package/dist/{cli-4CHKF4DQ.js → cli-H7T6E7OA.js} +2 -2
- package/dist/{cli-TDYKRXUA.js → cli-HCMVZXWK.js} +17 -17
- package/dist/{cli-WU43JT4T.js → cli-HJPNNORV.js} +2 -2
- package/dist/{cli-MYJGMA6U.js → cli-IC5FOT2J.js} +1 -1
- package/dist/{cli-VYR326C6.js → cli-ICLCA6VD.js} +19 -19
- package/dist/{cli-CXCL7VRK.js → cli-IJPRZSJ5.js} +20 -20
- package/dist/{cli-VL2P354N.js → cli-IVZ7AHUJ.js} +3 -3
- package/dist/{cli-B6YHEKIJ.js → cli-J2OTL6JH.js} +5 -5
- package/dist/{cli-SOMIB4B4.js → cli-J75EBRAJ.js} +17 -17
- package/dist/{cli-WAZD75KE.js → cli-JEMWAIAA.js} +15 -15
- package/dist/{cli-TDSQSCX4.js → cli-K6M6YB67.js} +1 -1
- package/dist/{cli-WG36UJRK.js → cli-KD2RQS35.js} +18 -18
- package/dist/{cli-GTWEGYSU.js → cli-KGJHEDR2.js} +19 -19
- package/dist/{cli-EDCAH2TC.js → cli-KINJAQTJ.js} +19 -19
- package/dist/cli-KJV3GGBA.js +1973 -0
- package/dist/{cli-X7E3637I.js → cli-KO26S2CL.js} +50 -26
- package/dist/{cli-MULKSLA4.js → cli-L5ZKQNMI.js} +15 -15
- package/dist/{cli-ATI6OLJU.js → cli-LFUKHLHI.js} +17 -17
- package/dist/{cli-GHLILDH7.js → cli-LZFUSEJT.js} +13 -13
- package/dist/{cli-RZITKPJX.js → cli-MN7X4UG2.js} +1 -1
- package/dist/{cli-HCRTYQQS.js → cli-MPWTXNF6.js} +2 -2
- package/dist/{cli-HHPMAV4F.js → cli-MSSJLABW.js} +3 -3
- package/dist/{cli-DHOWZCXT.js → cli-MTAGL3QE.js} +15 -15
- package/dist/{cli-JIZTQVL2.js → cli-MX7GFQ6N.js} +14 -14
- package/dist/{cli-7TOLC62D.js → cli-MYBDWJP7.js} +20 -20
- package/dist/{cli-VPON5HGB.js → cli-MZM4MW7C.js} +19 -19
- package/dist/{cli-UBQCSUDH.js → cli-NTI22MRE.js} +16 -16
- package/dist/{cli-ZTWOE3ZT.js → cli-NU4SCD5D.js} +1 -1
- package/dist/{cli-DEBCP7UH.js → cli-OK6XWVIN.js} +17 -17
- package/dist/{cli-6HB6HTC6.js → cli-OOTGO3KW.js} +47 -47
- package/dist/{cli-2DQJACAH.js → cli-OX3254NS.js} +17 -17
- package/dist/{cli-GEQUJF4L.js → cli-PJO4BKSV.js} +16 -16
- package/dist/{cli-R7RG2VMW.js → cli-QIHVXDMW.js} +15 -15
- package/dist/{cli-57V4ARER.js → cli-QK2OD24J.js} +1 -1
- package/dist/{cli-OANH3BTQ.js → cli-QRAYIXNE.js} +5 -5
- package/dist/{cli-GPAN6XK2.js → cli-QWO3XJR3.js} +4 -4
- package/dist/{cli-JRMHSMYT.js → cli-R6YAZP6E.js} +19 -19
- package/dist/{cli-FXWWYBYU.js → cli-RHYQYXE2.js} +18 -18
- package/dist/{cli-C3OERMIR.js → cli-RL5EBZL7.js} +3 -3
- package/dist/{cli-XR2XSWQN.js → cli-S3YIYAXC.js} +12 -12
- package/dist/{cli-NPPY557S.js → cli-S7PLSPGE.js} +15 -15
- package/dist/{cli-NEOLMC2P.js → cli-SBKTGFY4.js} +17 -17
- package/dist/{cli-BOXXMDSX.js → cli-TLRTLTGK.js} +18 -18
- package/dist/cli-UKC7KXWU.js +36 -0
- package/dist/{cli-FWFRKQNE.js → cli-UR63LFVK.js} +2 -2
- package/dist/{cli-ZKG3OPZ6.js → cli-USBJQAYI.js} +13 -13
- package/dist/{cli-M7WEAIRF.js → cli-VRGVHSXH.js} +106 -28
- package/dist/{cli-IUS2YCD3.js → cli-VTLFQHDO.js} +1 -1
- package/dist/{cli-JGFJWZFU.js → cli-W4BHSBAX.js} +3 -3
- package/dist/cli-WA2PDQUB.js +36 -0
- package/dist/{cli-HYEU3QS6.js → cli-WJO75KP7.js} +3 -3
- package/dist/{cli-3PIJLSRQ.js → cli-XA4IL7IM.js} +11 -11
- package/dist/{cli-LRQDF3ZO.js → cli-XRVH5WV6.js} +13 -13
- package/dist/{cli-SRHBXZCN.js → cli-Y33ULHYO.js} +1 -1
- package/dist/{cli-G5DQGZ2E.js → cli-YD4SBAHQ.js} +19 -19
- package/dist/{cli-64AA7367.js → cli-YI3WZF3C.js} +11 -11
- package/dist/{cli-JPAXKLVT.js → cli-ZHFHOWJI.js} +11 -11
- package/dist/{cli-MM3A4SPH.js → cli-ZZSPFLTK.js} +7265 -4467
- 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 +25 -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 +67 -6
- 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 +10 -7
- 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 +19 -10
- 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/give-setup-a-menu.md +90 -0
- package/dist/docs/recipes/index.md +4 -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 +57 -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
|
@@ -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)
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# Give setup a menu
|
|
2
|
+
|
|
3
|
+
Move the choices your setup screen offers into a settings resource of their own, so a facilitator, or an AI assistant setting a session up for one, can change exactly those and nothing else.
|
|
4
|
+
|
|
5
|
+
**Keywords:** setup menu, quick config, setup screen, configures, AI assistant, agent setup, difficulty, session setup, restrict setup, settings resource
|
|
6
|
+
|
|
7
|
+
## What you'll build
|
|
8
|
+
|
|
9
|
+
A settings resource at `settings/setup/` holding only your setup's choices, a setup screen that configures it instead of `engine`, and an engine that works out what each choice means. Today, a setup that configures `engine` lets an assistant change every engine setting, even the ones your screen never shows. See [Give setup a menu of its own](../guides/setup.md#give-setup-a-menu-of-its-own) for the reasoning.
|
|
10
|
+
|
|
11
|
+
## Prerequisites
|
|
12
|
+
|
|
13
|
+
- A [setup screen](create-setup.md) that configures one of your game's other settings resources, such as `engine`
|
|
14
|
+
- `seriousgaming.sdk.json` in your working directory
|
|
15
|
+
|
|
16
|
+
## Steps
|
|
17
|
+
|
|
18
|
+
1. List what your setup screen offers. For each control, decide the choice a facilitator makes rather than the value it writes: 'easier, standard or harder' rather than 'game level from 1 to 10'
|
|
19
|
+
|
|
20
|
+
2. Create the menu. Make each choice an `enum`, a `boolean`, or an array of an `enum`, with a `title`, a `description` and a `default`:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
pnpm run sdk new settings '{
|
|
24
|
+
"definition": {
|
|
25
|
+
"identifier": "setup",
|
|
26
|
+
"settingsSchema": {
|
|
27
|
+
"type": "object",
|
|
28
|
+
"properties": {
|
|
29
|
+
"Market": {
|
|
30
|
+
"title": "Market",
|
|
31
|
+
"description": "How forgiving the market is, compared with the scenario. standard plays the scenario as written",
|
|
32
|
+
"type": "string",
|
|
33
|
+
"enum": ["gentler", "standard", "tougher"],
|
|
34
|
+
"default": "standard"
|
|
35
|
+
}
|
|
36
|
+
},
|
|
37
|
+
"additionalProperties": false
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
}'
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
3. Point setup at the menu. Keep `game` if your screen sets the number of rounds:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
pnpm run sdk update setup --patch '[{ "op": "replace", "path": "/definition/configures", "value": ["game", "setup"] }]'
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
4. Let the engine read the menu. Add `setup` to its `settings`, and to the `settings` of any endpoint or validator whose answer the choice changes:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
pnpm run sdk update engine --patch '[{ "op": "add", "path": "/definition/settings/-", "value": "setup" }]'
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
5. Work out what each choice means in the engine, relative to the scenario so the two never clash:
|
|
56
|
+
|
|
57
|
+
```typescript
|
|
58
|
+
const engine =
|
|
59
|
+
settings.setup.Market === 'tougher'
|
|
60
|
+
? { ...settings.engine, BaseDemand: Math.round(settings.engine.BaseDemand * 0.7) }
|
|
61
|
+
: settings.engine;
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
6. Rewrite the setup screen's controls to write the menu with `updateSettings({ setup: { ... } })`, and remove any control for a setting the menu does not hold
|
|
65
|
+
|
|
66
|
+
7. Where what the menu offers depends on the scenario, such as an aid only some scenarios allow, keep that list in your other settings, where only a scenario can set it. Say where it is in the menu setting's `description`, and refuse a choice the scenario does not allow in a [Scenario gate](validate-scenarios.md) that declares `setup` in its `settings`. List `session-validation` in `requires` so the gate runs as each session starts
|
|
67
|
+
|
|
68
|
+
8. Rewrite your [setup notes](write-setup-notes.md), if you have them, to name the menu's settings and say which requests need a scenario instead
|
|
69
|
+
|
|
70
|
+
9. Add `setup` to the scenario editor's `configures` if authors should choose a scenario's defaults for the menu
|
|
71
|
+
|
|
72
|
+
## Verify
|
|
73
|
+
|
|
74
|
+
- `pnpm run generate`, then `pnpm run typecheck`: every hand-built `Settings` in your tests now needs a `setup` entry, such as `setup: defaultSettings.setup`
|
|
75
|
+
- `pnpm run sdk build --validate-only` passes with no `SETUP_NOTES_UNCONFIGURED` warning
|
|
76
|
+
- Write `{ "setup": { "Market": "tougher" } }` to `settings.json`, run `pnpm run sdk configure -f settings.json`, then `pnpm run sdk tick`: the engine acts on the choice
|
|
77
|
+
- `pnpm run sdk configure` still accepts an `engine` value, since the command line is your own authoring tool. On a host, an assistant setting a session up is refused one
|
|
78
|
+
|
|
79
|
+
## Troubleshooting
|
|
80
|
+
|
|
81
|
+
- _`SETTINGS_UNGATED` on `setup`_: no `Scenario` gate reads the menu. Fine when every choice is safe on every scenario; otherwise add `setup` to the gate's `settings` and check it there
|
|
82
|
+
- _A scenario plays differently after the move_: the menu's default must mean 'as the scenario sets it'. Make the default choice change nothing
|
|
83
|
+
- _The setup screen shows no choice selected_: an old session override still names an `engine` setting. Reconfigure the session, or delete `.seriousgaming-sdk/configuration.json`
|
|
84
|
+
|
|
85
|
+
## Related
|
|
86
|
+
|
|
87
|
+
- [Setup guide: give setup a menu of its own](../guides/setup.md#give-setup-a-menu-of-its-own)
|
|
88
|
+
- [Create a setup screen](create-setup.md)
|
|
89
|
+
- [Write setup notes for assistants](write-setup-notes.md)
|
|
90
|
+
- [Validate a game's scenarios](validate-scenarios.md)
|
|
@@ -34,6 +34,9 @@ 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
|
+
- [Give setup a menu](give-setup-a-menu.md): keep what setup can change to the choices it offers, so an assistant changes nothing else
|
|
38
|
+
- [Write setup notes for assistants](write-setup-notes.md): tell an AI assistant which settings matter and what requests such as 'harder' mean
|
|
39
|
+
- [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
40
|
- [Create a scenario editor](create-scenario-editor.md): a screen for building new scenarios for a released game
|
|
38
41
|
- [Adapt a UI for observers](adapt-ui-for-observers.md): tell a facilitator observing a team from a participant with `useUserInterfaceViewerRole`
|
|
39
42
|
- [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 +66,7 @@ The full reference is the [Multi-team games](../guides/multi-team-games.md) guid
|
|
|
63
66
|
## Validation
|
|
64
67
|
|
|
65
68
|
- [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
|
|
69
|
+
- [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
70
|
|
|
68
71
|
## Runtime callbacks
|
|
69
72
|
|
|
@@ -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"`
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
# Write setup notes for assistants
|
|
2
|
+
|
|
3
|
+
Tell an AI assistant setting a session up which of your setup's choices matter, and what a request such as 'make it a bit harder' means in your game.
|
|
4
|
+
|
|
5
|
+
**Keywords:** setup notes, assistant, agent, AI setup, session setup, setup menu, make it harder, shorter session, setting paths, setup/notes, MCP
|
|
6
|
+
|
|
7
|
+
## What you'll build
|
|
8
|
+
|
|
9
|
+
A Markdown file at `setup/notes/en.md` that an assistant reads before setting a session up for a facilitator. A settings schema describes each choice on its own; the notes say which choices mean what a facilitator asks for, and which requests need a scenario instead. They are for assistants: your setup screen is what a facilitator sees, and a host need not show the notes to anyone.
|
|
10
|
+
|
|
11
|
+
## Prerequisites
|
|
12
|
+
|
|
13
|
+
- A [setup screen](create-setup.md) with a [menu of its own](give-setup-a-menu.md), since the notes describe the choices it `configures` and nothing else
|
|
14
|
+
- `seriousgaming.sdk.json` in your working directory
|
|
15
|
+
|
|
16
|
+
## Steps
|
|
17
|
+
|
|
18
|
+
1. Create `setup/notes/en.md`. Name every setting as a setting path in a code span, as `setup.Market`, so an assistant can write it back as it stands. Name only settings your setup screen configures, with values their schemas allow:
|
|
19
|
+
|
|
20
|
+
```markdown
|
|
21
|
+
# Setting up a Factory session
|
|
22
|
+
|
|
23
|
+
Most sessions need no changes: start on the scenario the facilitator picked.
|
|
24
|
+
|
|
25
|
+
## The choices
|
|
26
|
+
|
|
27
|
+
- **Length.** `game.maxTicks` is the number of rounds, 10 by default, between 4 and 12
|
|
28
|
+
- **Market.** `setup.Market` is `gentler`, `standard` (the scenario as written) or `tougher`
|
|
29
|
+
|
|
30
|
+
## What requests mean
|
|
31
|
+
|
|
32
|
+
- **'Harder'**: set `setup.Market` to `tougher`
|
|
33
|
+
- **'Shorter'**: set `game.maxTicks` to 6. The bonus is paid in round 10, so say a shorter session pays none
|
|
34
|
+
- **Anything else**, such as cheaper materials: setup cannot do it. Suggest a scenario that does
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
2. Keep it short: the choices worth asking a facilitator about, what common requests mean as choices, and which requests need a scenario. Where a request matches one of your scenarios, say to pick that scenario instead. Where what the menu offers depends on the scenario, name the setting that says what it offers: an assistant may be able to read it, though not change it
|
|
38
|
+
|
|
39
|
+
3. Add a file per locale you support, such as `setup/notes/it.md`. An assistant gets the notes in its locale, or `en`, or your first supported locale
|
|
40
|
+
|
|
41
|
+
## Verify
|
|
42
|
+
|
|
43
|
+
- `pnpm run sdk build --validate-only` passes, and `dist/setup/notes/en.md` is there after `pnpm run sdk build`
|
|
44
|
+
- `pnpm run sdk dev`: on the configuration step, **Notes for assistants** shows the file exactly as an assistant receives it
|
|
45
|
+
|
|
46
|
+
## Troubleshooting
|
|
47
|
+
|
|
48
|
+
- _`SETTINGS_UNKNOWN` in `setup/notes/en.md`_: a code span names a setting your package does not declare, often a typo. Any code span starting with one of your settings identifiers is read as a setting path
|
|
49
|
+
- _`SETUP_NOTES_UNCONFIGURED`_: the notes name a setting your setup screen does not `configures`, so a host refuses that change. Leave the setting out and say which scenario does the job, or, if facilitators should choose it, add it to your [menu](give-setup-a-menu.md). Adding a whole settings resource such as `engine` to `configures` hands every setting in it to the assistant
|
|
50
|
+
- _A code span that is not a setting_, such as `requires`: fine. Only spans starting with a settings identifier are checked
|
|
51
|
+
|
|
52
|
+
## Related
|
|
53
|
+
|
|
54
|
+
- [Setup guide: notes for assistants](../guides/setup.md#notes-for-assistants)
|
|
55
|
+
- [Give setup a menu](give-setup-a-menu.md)
|
|
56
|
+
- [Describe a setup with an endpoint](describe-setup-with-endpoint.md): let an assistant read back what a setup means
|
|
57
|
+
- [Validate a game's scenarios](validate-scenarios.md): refuse a session whose setup breaks your rules
|
|
@@ -723,8 +723,9 @@ Restart the dev server. The SDK merges this config automatically for both `sdk d
|
|
|
723
723
|
3. Check the type imports:
|
|
724
724
|
|
|
725
725
|
```typescript
|
|
726
|
-
import type { Context, Settings } from '../types';
|
|
727
726
|
import { useUserInterfaceData } from '@seriousgaming/sdk/ui';
|
|
727
|
+
|
|
728
|
+
import type { Context, Settings } from '../types';
|
|
728
729
|
```
|
|
729
730
|
|
|
730
731
|
4. Call the hook inside `UserInterfaceWrapper`:
|
|
@@ -297,6 +297,18 @@ export declare class GameExecutor {
|
|
|
297
297
|
* Get the active scenario (if any)
|
|
298
298
|
*/
|
|
299
299
|
getActiveScenario(): SDKScenario | null;
|
|
300
|
+
/**
|
|
301
|
+
* What `initialize(true, …, scenarioId)` would start a session on, read
|
|
302
|
+
* without changing anything: the package on disk, the scenario it would
|
|
303
|
+
* activate and the session-override layer it would load. So a start can be
|
|
304
|
+
* judged (§15.8) before the running session is torn down, and a refusal
|
|
305
|
+
* leaves it as it was.
|
|
306
|
+
*/
|
|
307
|
+
previewStart(scenarioId?: string | null): Promise<{
|
|
308
|
+
config: ResolvedPackageManifest;
|
|
309
|
+
scenario: SDKScenario | null;
|
|
310
|
+
overrides: SessionSettingsOverrides;
|
|
311
|
+
}>;
|
|
300
312
|
/** The scenario `initialize` would activate for this id, without activating it. */
|
|
301
313
|
findScenario(scenarioId?: string | null): SDKScenario | null;
|
|
302
314
|
/**
|
|
@@ -5,6 +5,8 @@
|
|
|
5
5
|
* Unlike the other two gates it needs no session. It judges settings, not a
|
|
6
6
|
* board, so the build can run it on a package's own scenarios and the dev
|
|
7
7
|
* server on a scenario about to be saved, with only the package and a loader.
|
|
8
|
+
* In a package that lists `session-validation` it also judges a session's own
|
|
9
|
+
* settings as the session starts.
|
|
8
10
|
*/
|
|
9
11
|
import { type ResolvedPackageManifest, type ScenarioProblem } from '@seriousgaming/sdk';
|
|
10
12
|
import { LogicLoader } from './logic-loader';
|
|
@@ -13,6 +15,8 @@ import type { SessionSettingsOverrides } from './types';
|
|
|
13
15
|
export declare const SCENARIO_VALIDATION = "scenario-validation";
|
|
14
16
|
/** The `requires` feature name a package whose `Scenario` gate reads files lists (§15.8). */
|
|
15
17
|
export declare const SCENARIO_FILES = "scenario-files";
|
|
18
|
+
/** The `requires` feature name a package whose `Scenario` gate also judges a starting session lists (§15.8). */
|
|
19
|
+
export declare const SESSION_VALIDATION = "session-validation";
|
|
16
20
|
/**
|
|
17
21
|
* Where the files of the scenario being judged resolve (§15.8): as that
|
|
18
22
|
* scenario resolves them, so a gate finds exactly the files a session started
|
|
@@ -32,7 +36,38 @@ export interface ScenarioFileRoots {
|
|
|
32
36
|
/** A problem one validator found with a scenario. */
|
|
33
37
|
export interface ScenarioGateProblem extends ScenarioProblem {
|
|
34
38
|
validatorIdentifier: string;
|
|
39
|
+
/**
|
|
40
|
+
* Set when the gate itself failed (it threw, overran, or returned
|
|
41
|
+
* something other than an array) rather than finding a problem. A failure
|
|
42
|
+
* blocks like an error, but only a fix to the game clears it, so it is
|
|
43
|
+
* reported apart from the problems a setting change would fix (§15.6).
|
|
44
|
+
*/
|
|
45
|
+
failed?: true;
|
|
46
|
+
/**
|
|
47
|
+
* Set beside `failed` when the gate ran out of time rather than threw.
|
|
48
|
+
* The bound is real time, so a busy host can push a sound gate over it,
|
|
49
|
+
* and a runtime may run it again before refusing a start (§15.8).
|
|
50
|
+
*/
|
|
51
|
+
overran?: true;
|
|
35
52
|
}
|
|
53
|
+
/** Whether a problem refuses: a failed gate, or one that is not a warning. */
|
|
54
|
+
export declare function isBlocking(problem: ScenarioGateProblem): boolean;
|
|
55
|
+
/** How many more times a gate that only overran is run, before a start or a save is refused. */
|
|
56
|
+
export declare const OVERRUN_RETRIES = 1;
|
|
57
|
+
/** Whether the only thing refusing is a gate that ran out of time. */
|
|
58
|
+
export declare function onlyOverran(problems: ScenarioGateProblem[]): boolean;
|
|
59
|
+
/**
|
|
60
|
+
* Run `judge` again while all it refuses on is a gate that ran out of time
|
|
61
|
+
* (§15.8). The bound is real time, so a busy host can push a sound gate over
|
|
62
|
+
* it; a throw gives the same answer every time, so it is never run again. The
|
|
63
|
+
* build does not retry: nothing else competes for its time.
|
|
64
|
+
*/
|
|
65
|
+
export declare function withOverrunRetry(judge: () => Promise<ScenarioGateProblem[]>): Promise<ScenarioGateProblem[]>;
|
|
66
|
+
/** The problems that refuse, and the warnings that never do. */
|
|
67
|
+
export declare function partitionProblems(problems: ScenarioGateProblem[]): {
|
|
68
|
+
blocking: ScenarioGateProblem[];
|
|
69
|
+
warnings: ScenarioGateProblem[];
|
|
70
|
+
};
|
|
36
71
|
/** Whether any validator in the package gates scenarios. */
|
|
37
72
|
export declare function hasScenarioGate(config: Pick<ResolvedPackageManifest, 'validators'>): boolean;
|
|
38
73
|
/**
|
|
@@ -49,6 +84,11 @@ export declare function runScenarioGates(options: {
|
|
|
49
84
|
boundMs?: number;
|
|
50
85
|
/** Where the scenario's files resolve. None at all when absent: the defaults alone. */
|
|
51
86
|
files?: ScenarioFileRoots;
|
|
87
|
+
/**
|
|
88
|
+
* A starting session's own overrides, applied over the scenario
|
|
89
|
+
* (`session-validation`). Absent for a scenario judged alone.
|
|
90
|
+
*/
|
|
91
|
+
sessionOverrides?: SessionSettingsOverrides | null;
|
|
52
92
|
}): Promise<ScenarioGateProblem[]>;
|
|
53
93
|
/** One line per problem, naming the validator and the setting. */
|
|
54
94
|
export declare function describeScenarioProblems(problems: ScenarioGateProblem[]): string[];
|