@seriousgaming/sdk-tools 1.8.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/{cli-W7XCTGQ7.js → cli-2BF7KBBJ.js} +10 -10
- package/dist/{cli-7S4G4EKK.js → cli-2CSI2UU2.js} +1 -1
- package/dist/{cli-UZCQL6YP.js → cli-2I6UN6C3.js} +2 -2
- package/dist/{cli-KFVA7DT3.js → cli-2JEICVMA.js} +2 -2
- package/dist/{cli-SPKPDXWD.js → cli-2PMLR6WG.js} +10 -10
- package/dist/{cli-ZSKP2IRP.js → cli-2UOUIVHW.js} +8 -8
- package/dist/{cli-QDIH2G2P.js → cli-2VV5IPSY.js} +10 -10
- package/dist/{cli-5SYPXJCB.js → cli-35K37SYY.js} +7 -7
- package/dist/{cli-XPJGW375.js → cli-3I6AI4AA.js} +14 -14
- package/dist/{cli-UTHPCZYL.js → cli-3RMP4HKZ.js} +2 -2
- package/dist/{cli-C2XDL4LD.js → cli-3YGNWZC6.js} +8 -8
- package/dist/{cli-6NBER36P.js → cli-4L7S27XO.js} +1 -1
- package/dist/{cli-BQ3FHENQ.js → cli-4X3X4HB2.js} +5 -5
- package/dist/{cli-66AHBZRZ.js → cli-5BPQ73OM.js} +10 -10
- package/dist/{cli-O3IMNLN2.js → cli-5PTCQTS6.js} +1 -1
- package/dist/{cli-27M4PX7O.js → cli-6COAU7JR.js} +12 -12
- package/dist/{cli-32NRB2IT.js → cli-6KL5B7EC.js} +10 -10
- package/dist/{cli-JQ6I5GGE.js → cli-6Y4XIVQS.js} +1 -1
- package/dist/{cli-MM2ROZWO.js → cli-6ZBQELF2.js} +14 -14
- package/dist/{cli-726NJARI.js → cli-7N7WFRWA.js} +0 -0
- package/dist/{cli-3HPAKEJJ.js → cli-7OCEVQQN.js} +1 -1
- package/dist/{cli-JOXCAGM7.js → cli-7RLZIWFP.js} +13 -13
- package/dist/{cli-KU4PG7ZA.js → cli-A3P3PO6Z.js} +10 -10
- package/dist/{cli-KMT235FV.js → cli-A7PITFRR.js} +1 -1
- package/dist/{cli-ZFY6TGU7.js → cli-AA5GMEUL.js} +2 -2
- package/dist/{cli-HC7L5DXV.js → cli-AJ5CABGJ.js} +7 -7
- package/dist/{cli-DPFN2LIZ.js → cli-B5LZEFLU.js} +11 -11
- package/dist/{cli-42ZUP4X3.js → cli-BF6L37O3.js} +3 -3
- package/dist/{cli-YLYB4ITF.js → cli-BNN36WZJ.js} +7 -7
- package/dist/{cli-UADUC4JD.js → cli-BT47H36C.js} +2 -2
- package/dist/{cli-UYV3BDPA.js → cli-BV7MX7JE.js} +2 -2
- package/dist/{cli-NGOQWOQE.js → cli-BYXNPBVG.js} +11 -11
- package/dist/{cli-PLW3TWJ7.js → cli-CKV44U7P.js} +13 -13
- package/dist/{cli-V5K3CCYZ.js → cli-CL3KF5KS.js} +2 -2
- package/dist/{cli-U2EWI6H5.js → cli-CPX4YA3P.js} +8 -8
- package/dist/{cli-4B5OBHSY.js → cli-CQUSM3SF.js} +13 -13
- package/dist/{cli-TJNLXQJ5.js → cli-CUZUIYCQ.js} +14 -14
- package/dist/{cli-HQUVSAHY.js → cli-D6AC3ZCX.js} +12 -12
- package/dist/{cli-ESU3J563.js → cli-DJCQ5XFR.js} +10 -10
- package/dist/{cli-5CG6BMCY.js → cli-DNCJURUU.js} +14 -14
- package/dist/{cli-7GJGFILU.js → cli-E77R7ZYB.js} +10 -10
- package/dist/{cli-D3CZRXVJ.js → cli-EDZF5Q2E.js} +7 -7
- package/dist/{cli-PPEB3ENS.js → cli-G54355N5.js} +12 -12
- package/dist/{cli-SOQJHK4Q.js → cli-G7JTIP5G.js} +3 -3
- package/dist/{cli-MPU4FLA7.js → cli-GHQIATHP.js} +2 -2
- package/dist/{cli-FSEDPZR5.js → cli-GZE4V7RC.js} +13 -13
- package/dist/{cli-3OVXQJEW.js → cli-H7T6E7OA.js} +1 -1
- package/dist/{cli-5P66N5G6.js → cli-HCMVZXWK.js} +12 -12
- package/dist/{cli-5FRKWNVP.js → cli-ICLCA6VD.js} +13 -13
- package/dist/{cli-BXCCODYD.js → cli-IJPRZSJ5.js} +13 -13
- package/dist/{cli-HMEZHQBC.js → cli-J75EBRAJ.js} +12 -12
- package/dist/{cli-SWUAXVIJ.js → cli-JEMWAIAA.js} +10 -10
- package/dist/{cli-6BAZE75K.js → cli-KD2RQS35.js} +12 -12
- package/dist/{cli-W7Y7X3FX.js → cli-KGJHEDR2.js} +12 -12
- package/dist/{cli-ME3JKMJL.js → cli-KINJAQTJ.js} +13 -13
- package/dist/{cli-WWNTBK37.js → cli-KJV3GGBA.js} +1 -1
- package/dist/{cli-GFONBOJT.js → cli-KO26S2CL.js} +5 -5
- package/dist/{cli-QAI6T5FL.js → cli-L5ZKQNMI.js} +10 -10
- package/dist/{cli-L4DEEAMK.js → cli-LFUKHLHI.js} +12 -12
- package/dist/{cli-72DRYVTT.js → cli-LZFUSEJT.js} +9 -9
- package/dist/{cli-2KDV2DYC.js → cli-MSSJLABW.js} +1 -1
- package/dist/{cli-KH6FKM5A.js → cli-MTAGL3QE.js} +10 -10
- package/dist/{cli-FH4WBZHA.js → cli-MX7GFQ6N.js} +8 -8
- package/dist/{cli-DT756M3Z.js → cli-MYBDWJP7.js} +14 -14
- package/dist/{cli-6FVHRL3H.js → cli-MZM4MW7C.js} +12 -12
- package/dist/{cli-PEY6XZDE.js → cli-NTI22MRE.js} +11 -11
- package/dist/{cli-EK7CGMGS.js → cli-OK6XWVIN.js} +10 -10
- package/dist/{cli-F47ELAXM.js → cli-OOTGO3KW.js} +47 -47
- package/dist/{cli-4EMNCU63.js → cli-OX3254NS.js} +10 -10
- package/dist/{cli-VBSF3R3L.js → cli-PJO4BKSV.js} +11 -11
- package/dist/{cli-MJ65PIYI.js → cli-QIHVXDMW.js} +10 -10
- package/dist/{cli-2QM63J3I.js → cli-QK2OD24J.js} +1 -1
- package/dist/{cli-E665NKUQ.js → cli-QRAYIXNE.js} +1 -1
- package/dist/{cli-Q5BKFFDL.js → cli-QWO3XJR3.js} +3 -3
- package/dist/{cli-FHKRO6OU.js → cli-R6YAZP6E.js} +13 -13
- package/dist/{cli-VQ4OJ4KE.js → cli-RHYQYXE2.js} +11 -11
- package/dist/{cli-PZ7G544B.js → cli-RL5EBZL7.js} +1 -1
- package/dist/{cli-G7FX7ZIU.js → cli-S3YIYAXC.js} +7 -7
- package/dist/{cli-N5K2KHPR.js → cli-S7PLSPGE.js} +10 -10
- package/dist/{cli-JA6UFTSX.js → cli-SBKTGFY4.js} +12 -12
- package/dist/{cli-3OCKRPXI.js → cli-TLRTLTGK.js} +11 -11
- package/dist/{cli-SN7D7HTX.js → cli-UKC7KXWU.js} +14 -14
- package/dist/{cli-CAX4CQTC.js → cli-USBJQAYI.js} +9 -9
- package/dist/{cli-6AGWTGTO.js → cli-VRGVHSXH.js} +5 -5
- package/dist/{cli-QAVLRCQ5.js → cli-W4BHSBAX.js} +1 -1
- package/dist/{cli-V7L3HEL4.js → cli-WA2PDQUB.js} +14 -14
- package/dist/{cli-7NCVUM5U.js → cli-WJO75KP7.js} +1 -1
- package/dist/{cli-3HZGJRQW.js → cli-XA4IL7IM.js} +5 -5
- package/dist/{cli-PO2ALWHP.js → cli-XRVH5WV6.js} +7 -7
- package/dist/{cli-FV45UZQP.js → cli-YD4SBAHQ.js} +13 -13
- package/dist/{cli-C7YZNPWX.js → cli-YI3WZF3C.js} +8 -8
- package/dist/{cli-3HBYH4VF.js → cli-ZHFHOWJI.js} +8 -8
- package/dist/{cli-OUFXSQOW.js → cli-ZZSPFLTK.js} +1 -1
- package/dist/cli.js +35 -35
- package/dist/docs/changelog.md +10 -0
- package/dist/docs/guides/setup.md +48 -8
- package/dist/docs/page-index.md +4 -3
- package/dist/docs/recipes/create-setup.md +18 -10
- package/dist/docs/recipes/give-setup-a-menu.md +90 -0
- package/dist/docs/recipes/index.md +1 -0
- package/dist/docs/recipes/write-setup-notes.md +13 -14
- package/dist/runtime/manifest-version.d.ts +1 -1
- package/dist/runtime.js +1 -1
- package/package.json +3 -3
package/dist/docs/page-index.md
CHANGED
|
@@ -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 15k 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.
|
|
@@ -99,7 +99,7 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
|
|
|
99
99
|
- [`recipes/create-scenario.md`](recipes/create-scenario.md), about 3k characters: Bundle a game flavour with settings overrides and static assets.
|
|
100
100
|
- [`recipes/create-session-ui.md`](recipes/create-session-ui.md), about 5k characters: Build the facilitator's screen: every team's state side by side, with controls to change values and run the session.
|
|
101
101
|
- [`recipes/create-settings.md`](recipes/create-settings.md), about 4k characters: Give a game a read-only parameter, such as a price, a difficulty, or an answer key, that its logic and screens read and that scenarios and facilitators can change before play starts.
|
|
102
|
-
- [`recipes/create-setup.md`](recipes/create-setup.md), about
|
|
102
|
+
- [`recipes/create-setup.md`](recipes/create-setup.md), about 4k characters: Give facilitators a short form at session creation that sets a few of your game's settings for that session only.
|
|
103
103
|
- [`recipes/create-tick-controller.md`](recipes/create-tick-controller.md), about 3k characters: Make ticks fire automatically, on an interval or a schedule your game's logic decides.
|
|
104
104
|
- [`recipes/create-user-interface.md`](recipes/create-user-interface.md), about 4k characters: Build the game UI: the screen each participant sees, showing the game's state and taking their decisions.
|
|
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.
|
|
@@ -111,6 +111,7 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
|
|
|
111
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.
|
|
112
112
|
- [`recipes/end-game-on-condition.md`](recipes/end-game-on-condition.md), about 5k characters: Stop a game automatically when a goal is reached, rather than after a fixed number of ticks.
|
|
113
113
|
- [`recipes/fix-duplicate-packages.md`](recipes/fix-duplicate-packages.md), about 4k characters: Resolve 'Invalid hook call' and similar errors caused by multiple copies of the same package being loaded by the dev server.
|
|
114
|
+
- [`recipes/give-setup-a-menu.md`](recipes/give-setup-a-menu.md), about 5k characters: 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.
|
|
114
115
|
- [`recipes/make-a-guide-follow-the-scenario.md`](recipes/make-a-guide-follow-the-scenario.md), about 5k characters: Show the session's settings in the facilitator guide, and show content only to the scenarios that need it.
|
|
115
116
|
- [`recipes/make-an-endpoint-external.md`](recipes/make-an-endpoint-external.md), about 5k characters: Publish one of your endpoints to callers outside the game, such as a facilitator's AI agent or a platform API, so it can be invoked by asking or by another system rather than by clicking.
|
|
116
117
|
- [`recipes/negotiate-across-teams.md`](recipes/negotiate-across-teams.md), about 8k characters: Build a game where two teams propose, agree, and settle an exchange with each other, using a team-readable ledger and authoritative settlement at tick time.
|
|
@@ -131,7 +132,7 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
|
|
|
131
132
|
- [`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.
|
|
132
133
|
- [`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.
|
|
133
134
|
- [`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
|
|
135
|
+
- [`recipes/write-setup-notes.md`](recipes/write-setup-notes.md), about 4k characters: 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.
|
|
135
136
|
|
|
136
137
|
## API reference
|
|
137
138
|
|
|
@@ -6,11 +6,11 @@ Give facilitators a short form at session creation that sets a few of your game'
|
|
|
6
6
|
|
|
7
7
|
## What you'll build
|
|
8
8
|
|
|
9
|
-
A setup screen at `setup/` that
|
|
9
|
+
A setup screen at `setup/` that offers a menu of choices, held in a settings resource of its own, and starts play from its own button. A game with a `setup` slot opens at the configuration step: nothing runs until the facilitator presses Play. See the [setup guide](../guides/setup.md) for the full behaviour.
|
|
10
10
|
|
|
11
11
|
## Prerequisites
|
|
12
12
|
|
|
13
|
-
- A
|
|
13
|
+
- A menu for the screen to edit: a settings resource at `settings/setup/` holding only the choices setup offers, here a `Market` enum of `gentler`, `standard` and `tougher`. See [Give setup a menu](give-setup-a-menu.md) for why, and [Create a settings resource](create-settings.md)
|
|
14
14
|
- `seriousgaming.sdk.json` in your working directory
|
|
15
15
|
|
|
16
16
|
## Steps
|
|
@@ -20,7 +20,7 @@ A setup screen at `setup/` that edits the `engine` settings and starts play from
|
|
|
20
20
|
```bash
|
|
21
21
|
pnpm run sdk new setup '{
|
|
22
22
|
"definition": {
|
|
23
|
-
"configures": ["
|
|
23
|
+
"configures": ["setup"]
|
|
24
24
|
},
|
|
25
25
|
"rootDirectory": ".",
|
|
26
26
|
"ui": { "entrypoint": "index.html" }
|
|
@@ -48,7 +48,7 @@ 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 { Button, Stack, TextField } from '@mui/material';
|
|
51
|
+
import { Button, MenuItem, Stack, TextField } from '@mui/material';
|
|
52
52
|
import { useSettingsEditor, useSettingsEditorCallbacks } from '@seriousgaming/sdk/ui';
|
|
53
53
|
|
|
54
54
|
import type { Settings } from '../types';
|
|
@@ -60,15 +60,22 @@ function App() {
|
|
|
60
60
|
return (
|
|
61
61
|
<Stack spacing={2}>
|
|
62
62
|
<TextField
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
value={settings.
|
|
63
|
+
select
|
|
64
|
+
label="Market"
|
|
65
|
+
value={settings.setup.Market}
|
|
66
66
|
onChange={(e) =>
|
|
67
67
|
void updateSettings({
|
|
68
|
-
|
|
68
|
+
setup: {
|
|
69
|
+
...settings.setup,
|
|
70
|
+
Market: e.target.value as Settings['setup']['Market'],
|
|
71
|
+
},
|
|
69
72
|
})
|
|
70
73
|
}
|
|
71
|
-
|
|
74
|
+
>
|
|
75
|
+
<MenuItem value="gentler">Gentler</MenuItem>
|
|
76
|
+
<MenuItem value="standard">As the scenario sets it</MenuItem>
|
|
77
|
+
<MenuItem value="tougher">Tougher</MenuItem>
|
|
78
|
+
</TextField>
|
|
72
79
|
<Button variant="contained" onClick={() => requestPlay()}>
|
|
73
80
|
Start game
|
|
74
81
|
</Button>
|
|
@@ -93,7 +100,7 @@ The dev server opens on `/setup`.
|
|
|
93
100
|
|
|
94
101
|
- [ ] The form shows each setting's resolved value
|
|
95
102
|
- [ ] Changing a value and pressing Start (or the host's Play) starts the session with that value
|
|
96
|
-
- [ ] `pnpm run sdk view` after play shows the engine acting on the
|
|
103
|
+
- [ ] `pnpm run sdk view` after play shows the engine acting on the choice, once the engine declares `setup` in its `settings` and reads it
|
|
97
104
|
|
|
98
105
|
## Troubleshooting
|
|
99
106
|
|
|
@@ -115,3 +122,4 @@ The configuration step exists only when the package has a `setup/setup.sdk.json`
|
|
|
115
122
|
- [Create a scenario editor](create-scenario-editor.md)
|
|
116
123
|
- [Use requestPlay in a setup screen](use-request-play.md)
|
|
117
124
|
- [Create a settings resource](create-settings.md)
|
|
125
|
+
- [Give setup a menu](give-setup-a-menu.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,7 @@ 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
|
|
37
38
|
- [Write setup notes for assistants](write-setup-notes.md): tell an AI assistant which settings matter and what requests such as 'harder' mean
|
|
38
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
|
|
39
40
|
- [Create a scenario editor](create-scenario-editor.md): a screen for building new scenarios for a released game
|
|
@@ -1,42 +1,40 @@
|
|
|
1
1
|
# Write setup notes for assistants
|
|
2
2
|
|
|
3
|
-
Tell an AI assistant setting a session up which of your
|
|
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
4
|
|
|
5
|
-
**Keywords:** setup notes, assistant, agent, AI setup, session setup, make it harder, shorter session, setting paths, setup/notes, MCP
|
|
5
|
+
**Keywords:** setup notes, assistant, agent, AI setup, session setup, setup menu, make it harder, shorter session, setting paths, setup/notes, MCP
|
|
6
6
|
|
|
7
7
|
## What you'll build
|
|
8
8
|
|
|
9
|
-
A Markdown file at `setup/notes/en.md` that an assistant reads before
|
|
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
10
|
|
|
11
11
|
## Prerequisites
|
|
12
12
|
|
|
13
|
-
- A [setup screen](create-setup.md), since the notes
|
|
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
14
|
- `seriousgaming.sdk.json` in your working directory
|
|
15
15
|
|
|
16
16
|
## Steps
|
|
17
17
|
|
|
18
|
-
1. Create `setup/notes/en.md`. Name every setting as a setting path in a code span, as `
|
|
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
19
|
|
|
20
20
|
```markdown
|
|
21
21
|
# Setting up a Factory session
|
|
22
22
|
|
|
23
23
|
Most sessions need no changes: start on the scenario the facilitator picked.
|
|
24
24
|
|
|
25
|
-
##
|
|
25
|
+
## The choices
|
|
26
26
|
|
|
27
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`
|
|
28
29
|
|
|
29
30
|
## What requests mean
|
|
30
31
|
|
|
31
|
-
- **'Harder'**:
|
|
32
|
-
- **'Shorter'**: set `game.maxTicks` to 6
|
|
33
|
-
|
|
34
|
-
## Leave alone
|
|
35
|
-
|
|
36
|
-
- `engine.CostPerUnit` at £0 makes unsold stock free, which only suits a practice round
|
|
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
|
|
37
35
|
```
|
|
38
36
|
|
|
39
|
-
2. Keep it short: the
|
|
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
|
|
40
38
|
|
|
41
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
|
|
42
40
|
|
|
@@ -48,11 +46,12 @@ A Markdown file at `setup/notes/en.md` that an assistant reads before changing a
|
|
|
48
46
|
## Troubleshooting
|
|
49
47
|
|
|
50
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
|
|
51
|
-
- _`SETUP_NOTES_UNCONFIGURED`_: the notes name a setting your setup screen does not `configures`, so a host refuses that change.
|
|
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
|
|
52
50
|
- _A code span that is not a setting_, such as `requires`: fine. Only spans starting with a settings identifier are checked
|
|
53
51
|
|
|
54
52
|
## Related
|
|
55
53
|
|
|
56
54
|
- [Setup guide: notes for assistants](../guides/setup.md#notes-for-assistants)
|
|
55
|
+
- [Give setup a menu](give-setup-a-menu.md)
|
|
57
56
|
- [Describe a setup with an endpoint](describe-setup-with-endpoint.md): let an assistant read back what a setup means
|
|
58
57
|
- [Validate a game's scenarios](validate-scenarios.md): refuse a session whose setup breaks your rules
|
|
@@ -26,7 +26,7 @@ export declare const MANIFEST_VERSION = 3;
|
|
|
26
26
|
* section is stamped, it is the revision at the top of the appendix.
|
|
27
27
|
* `spec-revision.test.ts` holds the two together.
|
|
28
28
|
*/
|
|
29
|
-
export declare const SPEC_REVISION = "1.
|
|
29
|
+
export declare const SPEC_REVISION = "1.8";
|
|
30
30
|
/**
|
|
31
31
|
* Whether specification revision `revision` is later than `than`, both as
|
|
32
32
|
* `major.minor`. A runtime MAY warn when a package's `builtWith.specRevision`
|
package/dist/runtime.js
CHANGED
|
@@ -305,7 +305,7 @@ function readTickControllerResult(label, result) {
|
|
|
305
305
|
|
|
306
306
|
// cli/runtime/manifest-version.ts
|
|
307
307
|
var MANIFEST_VERSION = 3;
|
|
308
|
-
var SPEC_REVISION = "1.
|
|
308
|
+
var SPEC_REVISION = "1.8";
|
|
309
309
|
function isLaterSpecRevision(revision, than) {
|
|
310
310
|
const [major, minor] = revision.split(".").map(Number);
|
|
311
311
|
const [thanMajor, thanMinor] = than.split(".").map(Number);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@seriousgaming/sdk-tools",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.9.0",
|
|
4
4
|
"description": "SDK tooling for building Serious Gaming games",
|
|
5
5
|
"homepage": "https://sdk.seriousgaming.com/",
|
|
6
6
|
"license": "SEE LICENSE IN LICENSE",
|
|
@@ -74,7 +74,7 @@
|
|
|
74
74
|
"@mui/icons-material": "^9.5.0",
|
|
75
75
|
"@mui/material": "^9.5.0",
|
|
76
76
|
"@playwright/test": "^1.64.1",
|
|
77
|
-
"@seriousgaming/sdk": "1.
|
|
77
|
+
"@seriousgaming/sdk": "1.9.0",
|
|
78
78
|
"@testing-library/jest-dom": "^7.0.1",
|
|
79
79
|
"@testing-library/react": "^16.3.3",
|
|
80
80
|
"@types/express": "^5.0.6",
|
|
@@ -103,7 +103,7 @@
|
|
|
103
103
|
},
|
|
104
104
|
"peerDependencies": {
|
|
105
105
|
"@playwright/test": ">=1.50.0",
|
|
106
|
-
"@seriousgaming/sdk": "^1.
|
|
106
|
+
"@seriousgaming/sdk": "^1.9.0"
|
|
107
107
|
},
|
|
108
108
|
"peerDependenciesMeta": {
|
|
109
109
|
"@playwright/test": {
|