@seriousgaming/sdk-tools 1.4.0 → 1.6.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/bundling/ui-bundler.d.ts +12 -0
- package/dist/cli-25RWY5BQ.js +41 -0
- package/dist/cli-272KBNJH.js +97 -0
- package/dist/cli-2BH7FX27.js +52 -0
- package/dist/cli-2GOFEW26.js +81 -0
- package/dist/cli-3E3MD5U4.js +21 -0
- package/dist/cli-3HE4AVZG.js +115 -0
- package/dist/cli-4AKVLEC4.js +1387 -0
- package/dist/cli-4BV45LBH.js +126 -0
- package/dist/cli-4LKXZQ2B.js +48 -0
- package/dist/cli-4UWFQNGF.js +54 -0
- package/dist/cli-4YB3ROVR.js +78 -0
- package/dist/cli-57RXC3HQ.js +36 -0
- package/dist/cli-5JEGTVTG.js +96 -0
- package/dist/cli-6AMT3BUO.js +97 -0
- package/dist/cli-6RRVEGFB.js +80 -0
- package/dist/cli-6WXLXJVX.js +36 -0
- package/dist/cli-7OGYADZ3.js +97 -0
- package/dist/cli-AK7OIPWY.js +229 -0
- package/dist/cli-B4TN6PJP.js +124 -0
- package/dist/cli-B6YHEKIJ.js +248 -0
- package/dist/cli-BPYMTOUL.js +89 -0
- package/dist/cli-BWX5E7TQ.js +23 -0
- package/dist/cli-BYJWFFCF.js +37 -0
- package/dist/cli-C3NVCKO6.js +43 -0
- package/dist/cli-C47GJATR.js +42 -0
- package/dist/cli-C5QOJJWX.js +46 -0
- package/dist/cli-C6TH5S7K.js +6417 -0
- package/dist/cli-DL2CVMRF.js +89 -0
- package/dist/cli-DMW2OQIJ.js +76 -0
- package/dist/cli-DZW3XD5F.js +143 -0
- package/dist/cli-E2NLWIFE.js +1331 -0
- package/dist/cli-E33CJRRQ.js +36 -0
- package/dist/cli-E6DJIMYD.js +142 -0
- package/dist/cli-EEFJKIGL.js +151 -0
- package/dist/cli-EVFS55WN.js +185 -0
- package/dist/cli-F2D4GGUA.js +549 -0
- package/dist/cli-FBTRTIZJ.js +226 -0
- package/dist/cli-FWFRKQNE.js +11 -0
- package/dist/cli-FYINNRML.js +760 -0
- package/dist/cli-G522CPRL.js +88 -0
- package/dist/cli-G6KELFSX.js +2847 -0
- package/dist/cli-G6UE5NL4.js +90 -0
- package/dist/cli-GBFM76BF.js +16 -0
- package/dist/cli-GDQ6ILJY.js +101 -0
- package/dist/cli-GFBGYFYD.js +50 -0
- package/dist/cli-GGPDQNM3.js +35 -0
- package/dist/cli-GTSGLN3Z.js +307 -0
- package/dist/cli-GUXKQMJ7.js +13641 -0
- package/dist/cli-GXD36NF2.js +60 -0
- package/dist/cli-HCRTYQQS.js +16 -0
- package/dist/cli-HYY64SUD.js +185 -0
- package/dist/cli-I355WTAF.js +463 -0
- package/dist/cli-IDKYF5XB.js +59 -0
- package/dist/cli-ILKCQNM6.js +8 -0
- package/dist/cli-IRZ5KB7D.js +36 -0
- package/dist/cli-IUS2YCD3.js +31 -0
- package/dist/cli-J4DKUUTK.js +138 -0
- package/dist/cli-JFU22EJ2.js +187 -0
- package/dist/cli-JMZLT65J.js +226 -0
- package/dist/cli-JZM7XTNV.js +89 -0
- package/dist/cli-K2B6WHKA.js +81 -0
- package/dist/cli-KL3756X6.js +126 -0
- package/dist/cli-KNOOKGYW.js +88 -0
- package/dist/cli-LFGRFIEO.js +226 -0
- package/dist/cli-LFM7GJHI.js +0 -0
- package/dist/cli-LMDJCHHD.js +304 -0
- package/dist/cli-LXYPE3L5.js +99 -0
- package/dist/cli-M6BCQRID.js +153 -0
- package/dist/cli-MBNMPVDC.js +367 -0
- package/dist/cli-MJUYJIEP.js +13 -0
- package/dist/cli-MMN4BPO4.js +145 -0
- package/dist/cli-MYJGMA6U.js +40 -0
- package/dist/cli-N6H6T2E2.js +616 -0
- package/dist/cli-O5KP4OVN.js +61 -0
- package/dist/cli-O6PWMJTZ.js +25 -0
- package/dist/cli-ORIG557O.js +141 -0
- package/dist/cli-PFFCNGHI.js +243 -0
- package/dist/cli-PNLYX6R6.js +131 -0
- package/dist/cli-PQBXVLEU.js +649 -0
- package/dist/cli-PTT5RGKO.js +62 -0
- package/dist/cli-Q2XJF5AS.js +127 -0
- package/dist/cli-QEVDDBNO.js +60 -0
- package/dist/cli-QEVE5HUM.js +167 -0
- package/dist/cli-QUIJCBYB.js +391 -0
- package/dist/cli-QUNIRH7A.js +57 -0
- package/dist/cli-QVASWX2A.js +187 -0
- package/dist/cli-QWQMPCL6.js +253 -0
- package/dist/cli-R4PCG5YX.js +131 -0
- package/dist/cli-RA673NGF.js +53 -0
- package/dist/cli-RN6IWTL2.js +36 -0
- package/dist/cli-ROT3DRKU.js +145 -0
- package/dist/cli-RZITKPJX.js +367 -0
- package/dist/cli-S5IVGDDD.js +32 -0
- package/dist/cli-S5QDONIQ.js +218 -0
- package/dist/cli-SIPDUBFL.js +36 -0
- package/dist/cli-SMFSZF2G.js +4009 -0
- package/dist/cli-SRHBXZCN.js +159 -0
- package/dist/cli-TCY5LJ7E.js +88 -0
- package/dist/cli-TDSQSCX4.js +131 -0
- package/dist/cli-TIDQ4WUE.js +257 -0
- package/dist/cli-TLLA6KAP.js +79 -0
- package/dist/cli-TPU4TUR6.js +132 -0
- package/dist/cli-U2UE7I7J.js +30 -0
- package/dist/cli-UELGBQG7.js +101 -0
- package/dist/cli-UHSZBKYO.js +97 -0
- package/dist/cli-UJ4UCL2Z.js +38 -0
- package/dist/cli-UKQYZYFK.js +31 -0
- package/dist/cli-UMFFURZ7.js +81 -0
- package/dist/cli-UNAJ2OTE.js +15 -0
- package/dist/cli-UNJ5X6BU.js +89 -0
- package/dist/cli-UTJU4IYG.js +117 -0
- package/dist/cli-V4GHRWOV.js +1837 -0
- package/dist/cli-VCI3CG36.js +73 -0
- package/dist/cli-VCKOC2EV.js +256 -0
- package/dist/cli-VL2P354N.js +46 -0
- package/dist/cli-WAE26SVW.js +72 -0
- package/dist/cli-WOGIAU2E.js +100 -0
- package/dist/cli-WU43JT4T.js +52 -0
- package/dist/cli-XCO2VQOH.js +122 -0
- package/dist/cli-XSVGKI3R.js +39 -0
- package/dist/cli-YOTGR3NB.js +82 -0
- package/dist/cli-YVVXUD2G.js +197 -0
- package/dist/cli-ZISJ36MM.js +89 -0
- package/dist/cli-ZTWOE3ZT.js +65 -0
- package/dist/cli-ZVSFYDPQ.js +205 -0
- package/dist/cli-ZWPYIXNI.js +68 -0
- package/dist/cli.js +171 -42385
- package/dist/client/build-surfaces.d.ts +33 -0
- package/dist/client/dev-server.d.ts +6 -0
- package/dist/client/index.d.ts +1 -0
- package/dist/client/playwright.d.ts +62 -0
- package/dist/client.js +339 -56
- package/dist/core/session.d.ts +15 -1
- package/dist/dev/console/assets/{index-BvB-LFQZ.js → index-CuMOOH9m.js} +21 -21
- package/dist/dev/console/index.html +1 -1
- package/dist/dev/public-origins.d.ts +61 -0
- package/dist/dev/shell.d.ts +51 -4
- package/dist/dev/surfaces.d.ts +7 -0
- package/dist/docs/ai-agents.md +5 -0
- package/dist/docs/api/index.md +14 -12
- package/dist/docs/api/sdk-tools-client.md +29 -0
- package/dist/docs/api/sdk-tools-playwright.md +104 -0
- package/dist/docs/changelog-0.x.md +2 -2
- package/dist/docs/changelog.md +56 -4
- package/dist/docs/cli-and-dev-server.md +79 -0
- package/dist/docs/cli-error-codes.md +39 -36
- package/dist/docs/cli-reference.md +93 -32
- package/dist/docs/environment-variables.md +16 -5
- package/dist/docs/guides/ai-facilitation.md +2 -0
- package/dist/docs/guides/capabilities.md +2 -0
- package/dist/docs/guides/designing-a-game.md +31 -4
- package/dist/docs/guides/designing-screens.md +133 -0
- package/dist/docs/guides/endpoints.md +2 -0
- package/dist/docs/guides/engine-testing.md +5 -1
- package/dist/docs/guides/engine.md +2 -0
- package/dist/docs/guides/file-handling.md +3 -1
- package/dist/docs/guides/games.md +3 -1
- package/dist/docs/guides/global-settings.md +2 -0
- package/dist/docs/guides/guide.md +2 -0
- package/dist/docs/guides/hooks.md +2 -0
- package/dist/docs/guides/index.md +9 -0
- package/dist/docs/guides/internationalization.md +2 -0
- package/dist/docs/guides/llm-integration.md +4 -2
- package/dist/docs/guides/multi-team-games.md +3 -1
- package/dist/docs/guides/patterns.md +2 -0
- package/dist/docs/guides/presentation.md +1 -1
- package/dist/docs/guides/production-constraints.md +2 -0
- package/dist/docs/guides/scenario-editor.md +2 -0
- package/dist/docs/guides/scenarios.md +6 -2
- package/dist/docs/guides/session-game-flow.md +365 -0
- package/dist/docs/guides/session-hooks.md +205 -0
- package/dist/docs/guides/session.md +27 -565
- package/dist/docs/guides/settings.md +2 -0
- package/dist/docs/guides/setup.md +3 -1
- package/dist/docs/guides/speech-generation.md +2 -0
- package/dist/docs/guides/starter-game.md +63 -23
- package/dist/docs/guides/testing.md +35 -18
- package/dist/docs/guides/tick-controller.md +3 -1
- package/dist/docs/guides/type-safety.md +2 -0
- package/dist/docs/guides/ui-files-and-llms.md +328 -0
- package/dist/docs/guides/ui-participants.md +281 -0
- package/dist/docs/guides/ui-styling.md +263 -0
- package/dist/docs/guides/ui-ticks.md +247 -0
- package/dist/docs/guides/ui.md +11 -1092
- package/dist/docs/guides/upgrading.md +2 -0
- package/dist/docs/guides/validators.md +2 -0
- package/dist/docs/guides/waiting-room.md +1 -1
- package/dist/docs/index.md +2 -1
- package/dist/docs/page-index.md +146 -0
- package/dist/docs/recipes/adapt-a-game-for-walkthroughs.md +1 -1
- package/dist/docs/recipes/adapt-ui-for-observers.md +1 -1
- package/dist/docs/recipes/create-presentation.md +11 -0
- package/dist/docs/recipes/create-scenario-editor.md +1 -0
- package/dist/docs/recipes/create-session-ui.md +2 -1
- package/dist/docs/recipes/create-setup.md +1 -0
- package/dist/docs/recipes/create-user-interface.md +1 -0
- package/dist/docs/recipes/create-waiting-room-ui.md +1 -0
- package/dist/docs/recipes/design-state-for-concurrent-writes.md +1 -1
- package/dist/docs/recipes/e2e-testing.md +19 -20
- package/dist/docs/recipes/fix-duplicate-packages.md +2 -2
- package/dist/docs/recipes/index.md +3 -0
- package/dist/docs/recipes/screenshot-a-surface.md +80 -0
- package/dist/docs/recipes/test-a-multi-role-game.md +1 -1
- package/dist/docs/recipes/use-request-tick.md +2 -2
- package/dist/execution/config-resolver.d.ts +4 -1
- package/dist/playwright.js +32232 -0
- package/dist/runtime/manifest-version.d.ts +1 -1
- package/dist/runtime.js +1 -1
- package/dist/templates/package/CLAUDE.md.template +14 -5
- package/dist/templates/package/DESIGN.md.liquid +39 -7
- package/dist/templates/package/README.md.liquid +1 -1
- package/dist/templates/package/claude/rules/workflow-create-user-interface.md +1 -1
- package/dist/templates/package/claude/rules/workflow-test-engine-or-ui.md +1 -1
- package/dist/templates/package/global-setup.ts.template +7 -18
- package/dist/templates/package/playwright.config.ts.liquid +8 -11
- package/dist/templates/package/pnpm-workspace.yaml.template +13 -0
- package/dist/templates/starter-game/capabilities/pacing/capability.sdk.json +18 -0
- package/dist/templates/starter-game/package.json +2 -0
- package/dist/templates/starter-game/playwright.config.ts +8 -11
- package/dist/templates/starter-game/presentation/defaults.ts +52 -0
- package/dist/templates/starter-game/presentation/index.html +20 -0
- package/dist/templates/starter-game/presentation/presentation.sdk.json +10 -0
- package/dist/templates/starter-game/presentation/src/App.tsx +55 -0
- package/dist/templates/starter-game/presentation/src/Band.tsx +40 -0
- package/dist/templates/starter-game/presentation/src/Slides.tsx +415 -0
- package/dist/templates/starter-game/presentation/src/WeatherIcon.tsx +21 -0
- package/dist/templates/starter-game/presentation/src/i18n.ts +88 -0
- package/dist/templates/starter-game/presentation/src/main.tsx +15 -0
- package/dist/templates/starter-game/presentation/src/stalls.test.ts +196 -0
- package/dist/templates/starter-game/presentation/src/stalls.ts +199 -0
- package/dist/templates/starter-game/presentation/types.ts +94 -0
- package/dist/templates/starter-game/seriousgaming.sdk.json +2 -1
- package/dist/templates/starter-game/session/defaults.ts +6 -0
- package/dist/templates/starter-game/session/index.html +1 -1
- package/dist/templates/starter-game/session/session.sdk.json +2 -2
- package/dist/templates/starter-game/session/src/App.test.tsx +436 -115
- package/dist/templates/starter-game/session/src/App.tsx +372 -222
- package/dist/templates/starter-game/session/src/JoinCodes.tsx +184 -0
- package/dist/templates/starter-game/session/src/ManagePanel.tsx +188 -0
- package/dist/templates/starter-game/session/src/Results.tsx +340 -0
- package/dist/templates/starter-game/session/src/SessionBar.tsx +179 -0
- package/dist/templates/starter-game/session/src/SessionPanels.tsx +105 -0
- package/dist/templates/starter-game/session/src/SidePanel.tsx +89 -0
- package/dist/templates/starter-game/session/src/StallCard.tsx +253 -0
- package/dist/templates/starter-game/session/src/TopBar.tsx +36 -0
- package/dist/templates/starter-game/session/src/i18n.ts +91 -24
- package/dist/templates/starter-game/session/src/status.ts +28 -0
- package/dist/templates/starter-game/session/types.ts +8 -2
- package/dist/templates/starter-game/shared/Awning.tsx +31 -0
- package/dist/templates/starter-game/shared/HostLogo.test.tsx +38 -0
- package/dist/templates/starter-game/shared/HostLogo.tsx +48 -0
- package/dist/templates/starter-game/shared/StallIcons.tsx +83 -0
- package/dist/templates/starter-game/shared/days.ts +11 -0
- package/dist/templates/starter-game/shared/format.test.ts +13 -0
- package/dist/templates/starter-game/{ui/src → shared}/format.ts +1 -1
- package/dist/templates/starter-game/testing/e2e/game.spec.ts +43 -9
- package/dist/templates/starter-game/testing/e2e/global-setup.ts +7 -18
- package/dist/templates/starter-game/ui/defaults.ts +3 -0
- package/dist/templates/starter-game/ui/src/App.test.tsx +197 -29
- package/dist/templates/starter-game/ui/src/App.tsx +176 -99
- package/dist/templates/starter-game/ui/src/DayBar.test.tsx +50 -7
- package/dist/templates/starter-game/ui/src/DayBar.tsx +96 -38
- package/dist/templates/starter-game/ui/src/DaysTable.tsx +69 -0
- package/dist/templates/starter-game/ui/src/FirstDay.tsx +37 -0
- package/dist/templates/starter-game/ui/src/Header.tsx +257 -0
- package/dist/templates/starter-game/ui/src/Lesson.tsx +63 -0
- package/dist/templates/starter-game/ui/src/MakeRow.tsx +98 -71
- package/dist/templates/starter-game/ui/src/Notices.tsx +59 -0
- package/dist/templates/starter-game/ui/src/PastDay.tsx +88 -0
- package/dist/templates/starter-game/ui/src/Section.tsx +26 -26
- package/dist/templates/starter-game/ui/src/ThemeToggle.tsx +25 -11
- package/dist/templates/starter-game/ui/src/TodayPanel.test.tsx +37 -33
- package/dist/templates/starter-game/ui/src/TodayPanel.tsx +66 -52
- package/dist/templates/starter-game/ui/src/WeatherCard.tsx +47 -0
- package/dist/templates/starter-game/ui/src/WeekOver.tsx +145 -0
- package/dist/templates/starter-game/ui/src/YesterdayPanel.tsx +65 -114
- package/dist/templates/starter-game/ui/src/days.ts +58 -0
- package/dist/templates/starter-game/ui/src/i18n.ts +86 -32
- package/dist/templates/starter-game/ui/src/test-helpers.ts +1 -0
- package/dist/templates/starter-game/ui/src/theme.ts +8 -8
- package/dist/templates/starter-game/ui/types.ts +6 -0
- package/dist/templates/starter-game/ui/ui.sdk.json +1 -1
- package/dist/templates/starter-game/validators/daylimit/defaults.ts +13 -0
- package/dist/templates/starter-game/validators/daylimit/logic/logic.test.ts +20 -0
- package/dist/templates/starter-game/validators/daylimit/logic/logic.ts +23 -0
- package/dist/templates/starter-game/validators/daylimit/types.ts +23 -0
- package/dist/templates/starter-game/validators/daylimit/validator.sdk.json +10 -0
- package/dist/templates/starter-game/waiting_room/src/App.test.tsx +83 -5
- package/dist/templates/starter-game/waiting_room/src/App.tsx +262 -119
- package/dist/templates/starter-game/waiting_room/src/i18n.ts +8 -4
- package/dist/utils/error-codes.d.ts +12 -0
- package/dist/utils/prompt.d.ts +5 -5
- package/dist/utils/resource-scan.d.ts +39 -0
- package/package.json +15 -4
- package/dist/templates/starter-game/session/src/Section.tsx +0 -37
- package/dist/templates/starter-game/session/src/TeamDoor.tsx +0 -96
- package/dist/templates/starter-game/session/src/format.ts +0 -8
- package/dist/templates/starter-game/ui/src/HistoryPanel.test.tsx +0 -74
- package/dist/templates/starter-game/ui/src/HistoryPanel.tsx +0 -120
- package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +0 -25
- package/dist/templates/starter-game/ui/src/HostLogo.tsx +0 -38
|
@@ -11,10 +11,10 @@ The codes are the contract: branch on the code, never on the message. A code is
|
|
|
11
11
|
| Exit code | Category | Meaning | Codes |
|
|
12
12
|
| --------- | ------------- | ------------------- | ----- |
|
|
13
13
|
| 1 | `internal` | Internal error | 1 |
|
|
14
|
-
| 2 | `usage` | Usage error |
|
|
14
|
+
| 2 | `usage` | Usage error | 16 |
|
|
15
15
|
| 3 | `package` | Invalid package | 32 |
|
|
16
|
-
| 4 | `refused` | Refused by the game |
|
|
17
|
-
| 5 | `environment` | Environment |
|
|
16
|
+
| 4 | `refused` | Refused by the game | 12 |
|
|
17
|
+
| 5 | `environment` | Environment | 19 |
|
|
18
18
|
|
|
19
19
|
## Codes
|
|
20
20
|
|
|
@@ -40,6 +40,7 @@ A code marked as a diagnostic also appears in a failure's `diagnostics`, one fin
|
|
|
40
40
|
| `PROMPT_REQUIRED` | The command would have to ask a question, and prompts are off: there is no terminal, --json or SERIOUSGAMING_JSON is set, or CI is set. | |
|
|
41
41
|
| `INPUT_INVALID` | Input given to the command is not valid JSON, or does not match the shape it must have. | |
|
|
42
42
|
| `FILE_NOT_FOUND` | A file named on the command line does not exist or cannot be read. | |
|
|
43
|
+
| `DOCS_SECTION_NOT_FOUND` | The page `docs view --section` reads has no heading by that name; the details list the ones it has. | |
|
|
43
44
|
| `RESOURCE_TYPE_UNKNOWN` | The resource type does not exist, or does not support this operation. | |
|
|
44
45
|
| `RESOURCE_NOT_FOUND` | The package has no resource of that type with that identifier. | |
|
|
45
46
|
| `RESOURCE_EXISTS` | A resource with that identifier, or in that slot, already exists. | |
|
|
@@ -85,42 +86,44 @@ A code marked as a diagnostic also appears in a failure's `diagnostics`, one fin
|
|
|
85
86
|
|
|
86
87
|
### Exit 4: refused by the game
|
|
87
88
|
|
|
88
|
-
| Code
|
|
89
|
-
|
|
|
90
|
-
| `REFUSED_DENIED`
|
|
91
|
-
| `REFUSED_VALIDATION`
|
|
92
|
-
| `REFUSED_CONFLICT`
|
|
93
|
-
| `REFUSED_SUPERSEDED`
|
|
94
|
-
| `TICK_FAILED`
|
|
95
|
-
| `SESSION_ERROR`
|
|
96
|
-
| `INVALID_REQUEST`
|
|
97
|
-
| `HANDLER_ERROR`
|
|
98
|
-
| `INVALID_RESPONSE`
|
|
99
|
-
| `LOGIC_ERROR`
|
|
100
|
-
| `
|
|
89
|
+
| Code | When | Also a diagnostic |
|
|
90
|
+
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
|
|
91
|
+
| `REFUSED_DENIED` | The session refused the command (the 'denied' outcome). | |
|
|
92
|
+
| `REFUSED_VALIDATION` | A validator rejected the write (the 'validation-rejected' outcome). error.details.rejections lists why. | |
|
|
93
|
+
| `REFUSED_CONFLICT` | The write conflicted with a concurrent tick (the 'conflict' outcome). | |
|
|
94
|
+
| `REFUSED_SUPERSEDED` | The write arrived after the tick it was for (the 'superseded' outcome). | |
|
|
95
|
+
| `TICK_FAILED` | The tick failed, usually because game logic threw (the 'tick-failed' outcome). | |
|
|
96
|
+
| `SESSION_ERROR` | The session failed the command unexpectedly (the 'error' outcome). | |
|
|
97
|
+
| `INVALID_REQUEST` | The endpoint request failed its requestSchema, so the handler did not run. | |
|
|
98
|
+
| `HANDLER_ERROR` | The endpoint's handler threw, or ran past its execution bound. | |
|
|
99
|
+
| `INVALID_RESPONSE` | What the endpoint's handler returned broke its declaration. | |
|
|
100
|
+
| `LOGIC_ERROR` | Game logic (an engine, hook, endpoint, validator or tick controller) threw. A diagnostic, not an error code: it sits in `diagnostics` under the command's TICK_FAILED, SESSION_ERROR or HANDLER_ERROR, with the file, line and column it threw at. | Yes |
|
|
101
|
+
| `SURFACE_NOT_RENDERED` | `sdk screenshot` gave up on the page: its surface did not connect, or did not report its first paint before the timeout. error.details carries the page's console errors, failed requests and uncaught exceptions. | |
|
|
102
|
+
| `SETTINGS_STALE` | The package changed on disk since the session started in a way that applies only at initialisation (a setting, a manifest field such as `teams`, or a capability removed or moved to another scope), so a command that advances or changes play was refused. Run `sdk init`. | |
|
|
101
103
|
|
|
102
104
|
### Exit 5: environment
|
|
103
105
|
|
|
104
|
-
| Code | When
|
|
105
|
-
| ------------------------- |
|
|
106
|
-
| `NO_SESSION` | No dev server is running for this package, and the command will not start one.
|
|
107
|
-
| `SESSION_STALE` | The running session was started from an out-of-date package and must restart.
|
|
108
|
-
| `LOCK_HELD` | A dev server is already running for this package.
|
|
109
|
-
| `PORT_IN_USE` | No free port was found to listen on.
|
|
110
|
-
| `DEV_SERVER_OUTDATED` | The running dev server does not understand the command: it is older than this CLI. Restart it.
|
|
111
|
-
| `DEV_SERVER_UNREACHABLE` | The dev server the lock file names does not answer.
|
|
112
|
-
| `DEV_SERVER_UNRESPONSIVE` | A dev server holds the lock and accepts connections but does not answer, most often because logic is stuck in a synchronous loop. Run `sdk dev stop`.
|
|
113
|
-
| `DEV_SERVER_START_FAILED` | A dev server could not be started.
|
|
114
|
-
| `DEV_SERVER_STOP_FAILED` | The dev server could not be stopped.
|
|
115
|
-
| `
|
|
116
|
-
| `
|
|
117
|
-
| `
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
120
|
-
| `
|
|
121
|
-
| `
|
|
122
|
-
| `
|
|
123
|
-
| `
|
|
106
|
+
| Code | When | Also a diagnostic |
|
|
107
|
+
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
|
|
108
|
+
| `NO_SESSION` | No dev server is running for this package, and the command will not start one. | |
|
|
109
|
+
| `SESSION_STALE` | The running session was started from an out-of-date package and must restart. | |
|
|
110
|
+
| `LOCK_HELD` | A dev server is already running for this package. | |
|
|
111
|
+
| `PORT_IN_USE` | No free port was found to listen on. | |
|
|
112
|
+
| `DEV_SERVER_OUTDATED` | The running dev server does not understand the command: it is older than this CLI. Restart it. | |
|
|
113
|
+
| `DEV_SERVER_UNREACHABLE` | The dev server the lock file names does not answer. | |
|
|
114
|
+
| `DEV_SERVER_UNRESPONSIVE` | A dev server holds the lock and accepts connections but does not answer, most often because logic is stuck in a synchronous loop. Run `sdk dev stop`. | |
|
|
115
|
+
| `DEV_SERVER_START_FAILED` | A dev server could not be started. | |
|
|
116
|
+
| `DEV_SERVER_STOP_FAILED` | The dev server could not be stopped. | |
|
|
117
|
+
| `BROWSER_MISSING` | `sdk screenshot` found no Playwright in the package's dependencies, or no Chromium installed for it. Add `@playwright/test` and run `pnpm exec playwright install chromium`. | |
|
|
118
|
+
| `LLM_NOT_CONFIGURED` | Logic called generateText, and the dev server or in-process session running it has no platform API key configured. | |
|
|
119
|
+
| `PLATFORM_UNREACHABLE` | The Serious Gaming platform could not be reached. | |
|
|
120
|
+
| `PLATFORM_UNAUTHORISED` | The platform refused the API key, or its holder lacks the role the call needs. | |
|
|
121
|
+
| `PLATFORM_ERROR` | The platform failed the request. | |
|
|
122
|
+
| `API_KEY_MISSING` | No API key is configured: set SERIOUSGAMING_API_KEY, add it to .env, or pass --api-key. | |
|
|
123
|
+
| `INSTALL_FAILED` | Installing a new package's dependencies failed. | |
|
|
124
|
+
| `SDK_INCOMPLETE` | This install of the SDK tools is missing files it ships with, such as its docs. | |
|
|
125
|
+
| `SETTINGS_FILE_INVALID` | The global settings file (~/.seriousgaming-sdk/config.json) cannot be parsed. | |
|
|
126
|
+
| `WRITE_FAILED` | A file or directory could not be written, moved or removed. | |
|
|
124
127
|
|
|
125
128
|
## Diagnostic codes
|
|
126
129
|
|
|
@@ -1173,7 +1173,7 @@ The dev server owns the session in memory and is the only thing that runs your g
|
|
|
1173
1173
|
|
|
1174
1174
|
`.seriousgaming-sdk/session.json` is how a command finds it: a lock file, written once at startup and removed at shutdown, carrying the server's pid, port and instance id, the machine it runs on, the version and install path of the tools that started it, and whether a command started it in the background. Session state itself is never written to disk. Set `SERIOUSGAMING_DEV_STATE_DIR` to keep the lock outside the package, one entry per package, for example in a container whose project directory is restored from a snapshot.
|
|
1175
1175
|
|
|
1176
|
-
With no server running, a session command starts one in the background, says so on stderr, and carries on. That server outlives the command, and `SERIOUSGAMING_DEV_PORT` tells it where to start looking for a port.
|
|
1176
|
+
With no server running, a session command starts one in the background, says so on stderr, and carries on. That server outlives the command, until `sdk dev stop` or until its package directory is removed, and `SERIOUSGAMING_DEV_PORT` tells it where to start looking for a port.
|
|
1177
1177
|
|
|
1178
1178
|
Set `SERIOUSGAMING_DEV_URL` to send every session command to a server by its address instead of the one the lock names, such as one started with [`sdk dev --isolated`](#run-a-second-server-beside-your-own). A server that does not answer there fails the command with `DEV_SERVER_UNREACHABLE` (exit 5), and nothing is started in its place.
|
|
1179
1179
|
|
|
@@ -1641,7 +1641,7 @@ Open or close the session waiting room.
|
|
|
1641
1641
|
pnpm run sdk scenario [identifier] [options]
|
|
1642
1642
|
```
|
|
1643
1643
|
|
|
1644
|
-
Activate a scenario, or `none` to run on the settings defaults.
|
|
1644
|
+
Activate a scenario, or `none` to run on the settings defaults when no scenario is the default.
|
|
1645
1645
|
|
|
1646
1646
|
| Option | Default | Description |
|
|
1647
1647
|
| -------------------------- | --------------------- | ----------------------------------------------------- |
|
|
@@ -1740,7 +1740,7 @@ pnpm run sdk reset --walkthrough # back to tick 0
|
|
|
1740
1740
|
|
|
1741
1741
|
The run is built the first time something asks for it, so there is nothing to create. In `sdk dev` it is also a surface, at `/walkthrough`, listed in the drawer's Surfaces tab.
|
|
1742
1742
|
|
|
1743
|
-
Your logic reads `meta.runKind` and your surfaces read `useRunKind()` to tell the two apart. See [Engines](./guides/engine.md#walkthroughs) and [User interfaces](./guides/ui.md#walkthroughs).
|
|
1743
|
+
Your logic reads `meta.runKind` and your surfaces read `useRunKind()` to tell the two apart. See [Engines](./guides/engine.md#walkthroughs) and [User interfaces](./guides/ui-participants.md#walkthroughs).
|
|
1744
1744
|
|
|
1745
1745
|
### Upload a blob
|
|
1746
1746
|
|
|
@@ -1973,23 +1973,28 @@ pnpm run sdk dev [options]
|
|
|
1973
1973
|
|
|
1974
1974
|
Start the Serious Gaming development server with hot reload.
|
|
1975
1975
|
|
|
1976
|
-
| Option
|
|
1977
|
-
|
|
|
1978
|
-
| `-w, --working-dir [PATH]`
|
|
1979
|
-
| `-p, --port [PORT]`
|
|
1980
|
-
| `--vite-port [VITE_PORT]`
|
|
1981
|
-
| `--asset-port [ASSET_PORT]`
|
|
1982
|
-
| `--no-open`
|
|
1983
|
-
| `--api-key [KEY]`
|
|
1984
|
-
| `--host [URL]`
|
|
1985
|
-
| `--lan`
|
|
1986
|
-
| `--teams [NUMBER]`
|
|
1987
|
-
| `--participants [COUNT]`
|
|
1988
|
-
| `--scenario [ID]`
|
|
1989
|
-
| `--fake-clock`
|
|
1990
|
-
| `--reinit-on-change`
|
|
1991
|
-
| `--isolated`
|
|
1992
|
-
| `--brand <FILE>`
|
|
1976
|
+
| Option | Default | Description |
|
|
1977
|
+
| ----------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1978
|
+
| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in. |
|
|
1979
|
+
| `-p, --port [PORT]` | `3000` | Port to run the dev server on, or auto for any free port (can also be set via SERIOUSGAMING_DEV_PORT env var or .env file). |
|
|
1980
|
+
| `--vite-port [VITE_PORT]` | | Port to run the Vite dev server on (defaults to PORT + 1). |
|
|
1981
|
+
| `--asset-port [ASSET_PORT]` | | Port game UI bundles and their assets are served from, which is a separate origin from the console (defaults to the next free port after the Vite port). |
|
|
1982
|
+
| `--no-open` | | Do not automatically open browser. |
|
|
1983
|
+
| `--api-key [KEY]` | | Serious Gaming platform API key for LLM calls (can also be set via SERIOUSGAMING_API_KEY env var or .env file). |
|
|
1984
|
+
| `--host [URL]` | | Serious Gaming platform origin for LLM calls (can also be set via SERIOUSGAMING_API_HOST env var or .env file). |
|
|
1985
|
+
| `--lan` | | Listen on every network interface, so phones and tablets on the same network can connect (localhost only by default). |
|
|
1986
|
+
| `--teams [NUMBER]` | | Number of teams to simulate (each accessible at `/team/<n>);` omit to use the game's teams.min. |
|
|
1987
|
+
| `--participants [COUNT]` | | Participants to seed each team with, zero or more, or one per team as 3,0,2 (defaults to 1). |
|
|
1988
|
+
| `--scenario [ID]` | | Scenario identifier to activate (uses default scenario if omitted). |
|
|
1989
|
+
| `--fake-clock` | | Run on a clock that moves only when `sdk clock advance` moves it, to test automatic ticks without waiting. |
|
|
1990
|
+
| `--reinit-on-change` | | Restart the game at tick 0 whenever an edit applies only at initialisation (a setting, a manifest field such as teams, a capability added, removed or rescoped), rather than recording it as pending once play is under way. |
|
|
1991
|
+
| `--isolated` | | Run beside any dev server already running for this package, for tests and recordings: no lock file (CLI commands reach it through SERIOUSGAMING_DEV_URL), configuration from the package alone, and uploads in a temporary directory. |
|
|
1992
|
+
| `--brand <FILE>` | | A brand file to preview the game in, added to the brand picker and selected; repeat for more than one. |
|
|
1993
|
+
| `--public-url <ORIGIN>` | | The origin people reach the console at, when a proxy or gateway stands in front of the server; used for every link the server prints or hands out (can also be set via SERIOUSGAMING_DEV_PUBLIC_URL). |
|
|
1994
|
+
| `--public-asset-url <ORIGIN>` | | The origin browsers load game surfaces from behind that proxy, which must differ from the console's (defaults to the --public-url host on the asset port; can also be set via SERIOUSGAMING_DEV_PUBLIC_ASSET_URL). |
|
|
1995
|
+
| `--public-hmr-url <ORIGIN>` | | The origin a surface's hot-reload client connects to behind that proxy, as wss:// or ws:// (defaults to the public asset host on the Vite port; can also be set via SERIOUSGAMING_DEV_PUBLIC_HMR_URL). |
|
|
1996
|
+
| `--no-error-overlay` | | Show no Vite error overlay over a surface that fails to build, for a preview people who are not developers watch; the error still reaches this log and the browser console (can also be set via SERIOUSGAMING_DEV_ERROR_OVERLAY=false). |
|
|
1997
|
+
| `--built-surfaces <DIR>` | | Serve surfaces from a build, laid out as `sdk build` writes dist/, instead of compiling them through Vite: pages load at once, and an edit to a surface is not seen until the next build. For browser test runs. |
|
|
1993
1998
|
|
|
1994
1999
|
In more detail:
|
|
1995
2000
|
|
|
@@ -2003,10 +2008,12 @@ In more detail:
|
|
|
2003
2008
|
- `--reinit-on-change`: however far play has gone, rather than holding the edit as pending (see [What reloads](#what-reloads)). The console shows a short 'Settings changed, game restarted' notice each time. The hosted builder starts the dev server this way
|
|
2004
2009
|
- `--brand`: a brand file to preview the game in, added to the console's **Brand** menu and selected. Repeat it for more than one; the first is selected. See [Preview your game in another brand](./guides/theming-and-branding.md#preview-your-game-in-another-brand)
|
|
2005
2010
|
- `--isolated`: for a test run or a recording (see below)
|
|
2011
|
+
- `--no-error-overlay`: for a preview people who are not developers watch. Also set by `SERIOUSGAMING_DEV_ERROR_OVERLAY=false`. See [Hide the error overlay](./cli-and-dev-server.md#hide-the-error-overlay)
|
|
2012
|
+
- `--public-url`, `--public-asset-url` and `--public-hmr-url`: the addresses people reach the server at when a proxy or gateway stands in front of it. Each defaults to its `SERIOUSGAMING_DEV_PUBLIC_*` environment variable. See [Embedding the dev server](./cli-and-dev-server.md#embedding-the-dev-server)
|
|
2006
2013
|
|
|
2007
2014
|
A package holds one session, so a second `sdk dev` for the same package is refused whatever port it asks for, and names the one already running. Stop that one with `sdk dev stop` to move it elsewhere, or start the second with `--isolated`.
|
|
2008
2015
|
|
|
2009
|
-
The server prints the console's address and the address game surfaces are served from. With `-j, --json`, the envelope it writes when it stops carries `url`, `assetUrl`, `port`, `assetPort` and `isolated
|
|
2016
|
+
The server prints the console's address and the address game surfaces are served from. With `-j, --json`, the envelope it writes when it stops carries `url`, `assetUrl`, `port`, `assetPort` and `isolated`, and `publicUrl` and `publicAssetUrl` when a public origin is set.
|
|
2010
2017
|
|
|
2011
2018
|
### Run a second server beside your own
|
|
2012
2019
|
|
|
@@ -2026,6 +2033,15 @@ SERIOUSGAMING_DEV_URL=http://localhost:53712 pnpm run sdk tick
|
|
|
2026
2033
|
|
|
2027
2034
|
Pair it with `--port auto` so it never collides with yours. To start one from a test runner without spawning the CLI, use [`startDevServer`](./guides/testing.md#a-dev-server-for-browser-tests).
|
|
2028
2035
|
|
|
2036
|
+
### Serve built surfaces
|
|
2037
|
+
|
|
2038
|
+
```bash
|
|
2039
|
+
pnpm run sdk build
|
|
2040
|
+
pnpm run sdk dev --isolated --port auto --no-open --built-surfaces dist
|
|
2041
|
+
```
|
|
2042
|
+
|
|
2043
|
+
`--built-surfaces` serves each surface from a build, laid out as `sdk build` writes `dist/`, instead of compiling it through Vite. A page loads at once, and an edit to a surface is not seen until you build again. It is for browser test runs that start several servers, each of which would otherwise compile the same surfaces. A surface missing from the build answers 404 rather than being compiled, and a directory that is not there fails the start with `BUILD_NOT_FOUND`. A Playwright suite does not need the flag: the [Playwright fixture](./guides/testing.md#a-dev-server-for-browser-tests) builds once and passes the build to every worker's server.
|
|
2044
|
+
|
|
2029
2045
|
**Several teams.** Start with N teams, each at its own URL:
|
|
2030
2046
|
|
|
2031
2047
|
```bash
|
|
@@ -2087,6 +2103,36 @@ Stop the dev server running for this package.
|
|
|
2087
2103
|
|
|
2088
2104
|
`dev status` and `dev stop` report through the [envelope](#json-output) with `-j, --json`, like every command.
|
|
2089
2105
|
|
|
2106
|
+
### Screenshot a surface
|
|
2107
|
+
|
|
2108
|
+
```text
|
|
2109
|
+
pnpm run sdk screenshot <path> [options]
|
|
2110
|
+
```
|
|
2111
|
+
|
|
2112
|
+
Capture a surface as a PNG, as a participant sees it.
|
|
2113
|
+
|
|
2114
|
+
| Option | Default | Description |
|
|
2115
|
+
| -------------------------- | --------------------- | ------------------------------------------------------------------------------------- |
|
|
2116
|
+
| `-w, --working-dir [PATH]` | the current directory | The working directory to execute in. |
|
|
2117
|
+
| `--width <PIXELS>` | `1280` | Viewport width. |
|
|
2118
|
+
| `--height <PIXELS>` | `800` | Viewport height. |
|
|
2119
|
+
| `--scheme <SCHEME>` | | Colour scheme: light, dark or system. |
|
|
2120
|
+
| `--brand <ID>` | | Brand to show, from those the dev server offers. |
|
|
2121
|
+
| `--locale <CODE>` | | Session locale for the capture; a running server's is switched back after. |
|
|
2122
|
+
| `--full-page` | | Capture the surface's whole height, not just the viewport. |
|
|
2123
|
+
| `--out <FILE>` | | PNG to write (default: `.seriousgaming-sdk/screenshots/<path>-<width>x<height>.png).` |
|
|
2124
|
+
| `--timeout <SECONDS>` | `30` | How long to wait for the surface to render. |
|
|
2125
|
+
|
|
2126
|
+
```bash
|
|
2127
|
+
pnpm run sdk screenshot /team/1/player/1 --width 390 --height 844 --scheme dark --out plan.png --json
|
|
2128
|
+
```
|
|
2129
|
+
|
|
2130
|
+
The path is any surface's URL path, such as `/team/1/player/1` or `/` for the session surface; `?bare` is added for you. The capture waits for the surface to report its first paint, so it shows the screen as drawn rather than its loading state. With `--json` the data names the image (`path`), the `url` it opened, and the page's `consoleErrors`, `failedRequests` and `uncaughtExceptions`, those inside the surface's frame included.
|
|
2131
|
+
|
|
2132
|
+
It drives the game's own Playwright (`@playwright/test`, which every scaffolded game has), and fails with `BROWSER_MISSING` (exit 5) without it or its Chromium. A surface that does not connect, or does not report its first paint within `--timeout`, fails with `SURFACE_NOT_RENDERED` (exit 4), carrying the same three lists in `error.details`.
|
|
2133
|
+
|
|
2134
|
+
The locale is the session's, not a viewer's, so `--locale` switches the session for the capture, and switches a running dev server back afterwards. See [Screenshot a surface](./recipes/screenshot-a-surface.md).
|
|
2135
|
+
|
|
2090
2136
|
### Dev server features
|
|
2091
2137
|
|
|
2092
2138
|
- **Hot reloading**: edit logic, bundles, the manifest or UIs and see the change without a restart (see [What reloads](#what-reloads))
|
|
@@ -2102,16 +2148,16 @@ Every edit falls into one of three buckets. Knowing which saves guessing at why
|
|
|
2102
2148
|
|
|
2103
2149
|
**Live: applied straight away, keeping the session where it is.**
|
|
2104
2150
|
|
|
2105
|
-
| You edit | What happens
|
|
2106
|
-
| ---------------------------------------------------------------------------------------------------------------------- |
|
|
2107
|
-
| A user interface (`ui/src/**`) | Vite hot-replaces the UI
|
|
2108
|
-
| Resource logic (`engine/logic.ts`, `tick_controller/logic.ts`, or `logic.ts` in `hooks/`, `validators/`, `endpoints/`) | The next run uses the new code. Ticks already played are not re-run
|
|
2109
|
-
| A resource bundle (`*.sdk.json`) | The session uses it from the next operation. A bundle that does not load is reported and the last good one stays in use
|
|
2110
|
-
| A new surface, such as a `waiting_room/` or `presentation/` slot | Served at its URL as soon as its bundle is saved
|
|
2111
|
-
| A new capability, or one a resource starts to read or write |
|
|
2112
|
-
| `locales` or `supportedLocales` in `seriousgaming.sdk.json` | The session uses them from the next operation
|
|
2113
|
-
| Scenario or facilitator-guide markdown, or an asset file | The new content is served on the next request
|
|
2114
|
-
| A colocated test (`*.test.ts`, `*.spec.ts`) | Nothing. Tests are not part of a logic bundle
|
|
2151
|
+
| You edit | What happens |
|
|
2152
|
+
| ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
2153
|
+
| A user interface (`ui/src/**`) | Vite hot-replaces the UI |
|
|
2154
|
+
| Resource logic (`engine/logic.ts`, `tick_controller/logic.ts`, or `logic.ts` in `hooks/`, `validators/`, `endpoints/`) | The next run uses the new code. Ticks already played are not re-run |
|
|
2155
|
+
| A resource bundle (`*.sdk.json`) | The session uses it from the next operation. A bundle that does not load is reported and the last good one stays in use |
|
|
2156
|
+
| A new surface, such as a `waiting_room/` or `presentation/` slot | Served at its URL as soon as its bundle is saved |
|
|
2157
|
+
| A new capability, or one a resource starts to read or write | At tick 0, or under `--reinit-on-change`, the session re-initialises so `Init` runs for it. Once a tick has been played, every team's board gets it with its schema defaults instead. `Init` has not run for it, and the dev server and the console say so: run `sdk init` to start from `Init` |
|
|
2158
|
+
| `locales` or `supportedLocales` in `seriousgaming.sdk.json` | The session uses them from the next operation |
|
|
2159
|
+
| Scenario or facilitator-guide markdown, or an asset file | The new content is served on the next request |
|
|
2160
|
+
| A colocated test (`*.test.ts`, `*.spec.ts`) | Nothing. Tests are not part of a logic bundle |
|
|
2115
2161
|
|
|
2116
2162
|
**Pending until `sdk init`: applied when the session next initialises.** These reach the game through `Init` or session creation, so applying them mid-session would give a state no real session can reach, such as a setting `Init` used keeping its old effect while the next tick reads the new value.
|
|
2117
2163
|
|
|
@@ -2126,6 +2172,8 @@ What happens to a pending change depends on whether anything has been played:
|
|
|
2126
2172
|
- **Once a tick has been played**, the session keeps running on what it started with and records the change. The console shows 'Settings changed: re-initialise to apply' with a **Re-initialise** button. `sdk tick`, `sdk undo`, a context patch, a writing endpoint call and resuming the tick timer are refused with `SETTINGS_STALE` (exit 4) until you re-initialise, with a hint to run `sdk init`. `sdk view` still answers, with `stale` in its data naming what changed and a warning on stderr. Reads, roster and team changes, and the waiting room are unaffected
|
|
2127
2173
|
- **Under `sdk dev --reinit-on-change`**, the session always re-initialises, however far play has gone
|
|
2128
2174
|
|
|
2175
|
+
If `Init` throws while the session re-initialises, which is common while an edit spans several files, the dev server reports the error in its log and on the console and keeps serving. The change stays pending, and the next edit or `sdk init` tries again.
|
|
2176
|
+
|
|
2129
2177
|
Re-initialising from the console's button keeps the team count, the scenario and the locale, and returns play to tick 0. So does a session-wide reset. `sdk init` rebuilds the session from the package and takes `--teams`, `--scenario` and `--locale` as usual. Editing the file back to what the session started with clears the pending change.
|
|
2130
2178
|
|
|
2131
2179
|
**Needs a restart.** Only an upgrade of the SDK tools themselves. A command notices one (see [A server from other tools](#where-the-session-lives)): it replaces a server it started in the background, and otherwise asks you to stop yours with `sdk dev stop` and start it again.
|
|
@@ -2510,11 +2558,16 @@ Prints the installed SDK version to stdout.
|
|
|
2510
2558
|
### Browse the documentation
|
|
2511
2559
|
|
|
2512
2560
|
```text
|
|
2513
|
-
pnpm run sdk docs view [file]
|
|
2561
|
+
pnpm run sdk docs view [file] [options]
|
|
2514
2562
|
```
|
|
2515
2563
|
|
|
2516
2564
|
View Serious Gaming SDK documentation.
|
|
2517
2565
|
|
|
2566
|
+
| Option | Default | Description |
|
|
2567
|
+
| --------------------- | ------- | ------------------------------------------------------------------------- |
|
|
2568
|
+
| `--outline` | | List the page's headings, with each section's length in characters. |
|
|
2569
|
+
| `--section <heading>` | | Print only the section under this heading, named by its slug or its text. |
|
|
2570
|
+
|
|
2518
2571
|
```text
|
|
2519
2572
|
pnpm run sdk docs export [dir]
|
|
2520
2573
|
```
|
|
@@ -2524,6 +2577,14 @@ Export SDK documentation to your project.
|
|
|
2524
2577
|
The docs ship inside the package at `node_modules/@seriousgaming/sdk-tools/dist/docs`, so they match the installed version and need no network. Search them with your editor or `grep`.
|
|
2525
2578
|
|
|
2526
2579
|
- `docs view` with no argument prints the tree of documents; with a path (for example `guides/engine.md`) it prints that document
|
|
2580
|
+
- `docs view page-index.md` lists every page with a one-sentence summary and its length: the place to find the page for a subject
|
|
2581
|
+
- `docs view <path> --outline` lists a page's headings, each with its level, its slug and its section's length in characters; `--section <heading>` prints only that section, named by its slug or its text, up to the next heading of the same or a higher level. Both work with `--json`, and an unknown section fails with `DOCS_SECTION_NOT_FOUND`, listing the slugs the page has in `details.available`
|
|
2582
|
+
|
|
2583
|
+
```bash
|
|
2584
|
+
pnpm run --silent sdk docs view guides/session.md --outline
|
|
2585
|
+
pnpm run --silent sdk docs view guides/session.md --section building-the-session-ui
|
|
2586
|
+
```
|
|
2587
|
+
|
|
2527
2588
|
- `docs export` copies every document to `dir`, or `.seriousgaming-sdk/docs` by default, so an editor or agent can search them locally
|
|
2528
2589
|
|
|
2529
2590
|
## Environment variables
|
|
@@ -57,11 +57,16 @@ A relative path is an error. See the [global settings guide](./guides/global-set
|
|
|
57
57
|
|
|
58
58
|
A session command starts a dev server when none is running, and has no `--port` of its own to pass it. This is how to tell that server where to start looking. See [The CLI and the dev server](./cli-and-dev-server.md).
|
|
59
59
|
|
|
60
|
-
| Variable
|
|
61
|
-
|
|
|
62
|
-
| `SERIOUSGAMING_DEV_PORT`
|
|
63
|
-
| `SERIOUSGAMING_DEV_URL`
|
|
64
|
-
| `SERIOUSGAMING_DEV_STATE_DIR`
|
|
60
|
+
| Variable | Required | Default | Purpose |
|
|
61
|
+
| ------------------------------------ | -------- | --------------------------------------- | ------------------------------------------------------------------------------- |
|
|
62
|
+
| `SERIOUSGAMING_DEV_PORT` | No | `3000` | Where the dev server starts looking for a free port, or `auto` for any free one |
|
|
63
|
+
| `SERIOUSGAMING_DEV_URL` | No | Unset | The server every session command targets, in place of the one the lock names |
|
|
64
|
+
| `SERIOUSGAMING_DEV_STATE_DIR` | No | The package's `.seriousgaming-sdk/` | Where the lock file naming the running server is kept |
|
|
65
|
+
| `SERIOUSGAMING_DEV_PUBLIC_URL` | No | Unset | The origin people reach the console at, behind a proxy |
|
|
66
|
+
| `SERIOUSGAMING_DEV_PUBLIC_ASSET_URL` | No | The public URL's host on the asset port | The origin browsers load game surfaces from, behind a proxy |
|
|
67
|
+
| `SERIOUSGAMING_DEV_PUBLIC_HMR_URL` | No | The public asset host on the Vite port | The origin a surface's hot-reload client connects to, behind a proxy |
|
|
68
|
+
| `SERIOUSGAMING_DEV_ERROR_OVERLAY` | No | `true` | `false` hides Vite's error overlay over a surface that fails to build |
|
|
69
|
+
| `SERIOUSGAMING_BUILT_SURFACES` | No | Unset | A build of the surfaces that every Playwright worker's dev server serves |
|
|
65
70
|
|
|
66
71
|
`SERIOUSGAMING_DEV_PORT` is a starting point, not a binding: the server steps up to the first free port from there, and prints the one it lands on. Equivalent CLI flag on `pnpm run sdk dev`: `--port`.
|
|
67
72
|
|
|
@@ -69,6 +74,12 @@ A session command starts a dev server when none is running, and has no `--port`
|
|
|
69
74
|
|
|
70
75
|
`SERIOUSGAMING_DEV_STATE_DIR` moves the lock out of the project, since it is runtime state rather than project content: a container whose project directory is restored from a snapshot otherwise brings back a lock naming a process from before it. Each package gets its own entry inside it, so one directory can serve several. Saved configuration and uploads stay in the package. See [Where the session lives](./cli-reference.md#where-the-session-lives).
|
|
71
76
|
|
|
77
|
+
The three `SERIOUSGAMING_DEV_PUBLIC_*` variables are for a server behind a proxy or gateway, such as one shown in another page's frame, and change every address the server prints or hands out. Equivalent CLI flags on `pnpm run sdk dev`: `--public-url`, `--public-asset-url` and `--public-hmr-url`. See [Embedding the dev server](./cli-and-dev-server.md#embedding-the-dev-server).
|
|
78
|
+
|
|
79
|
+
`SERIOUSGAMING_BUILT_SURFACES` is set by the Playwright global setup in `@seriousgaming/sdk-tools/playwright` to the build it makes, and read by each worker's server. Set it yourself, to `dist` for instance, to serve your own `pnpm run sdk build` and build nothing. A relative path is from the package. Equivalent CLI flag on `pnpm run sdk dev`: `--built-surfaces`. See [A dev server for browser tests](./guides/testing.md#a-dev-server-for-browser-tests).
|
|
80
|
+
|
|
81
|
+
`SERIOUSGAMING_DEV_ERROR_OVERLAY=false` is for a server whose surfaces people who are not developers watch. Equivalent CLI flag on `pnpm run sdk dev`: `--no-error-overlay`. See [Hide the error overlay](./cli-and-dev-server.md#hide-the-error-overlay).
|
|
82
|
+
|
|
72
83
|
## Output and prompts
|
|
73
84
|
|
|
74
85
|
| Variable | Required | Default | Purpose |
|
|
@@ -8,6 +8,8 @@ Most of it is not new machinery. An agent acting for a facilitator is close to a
|
|
|
8
8
|
|
|
9
9
|
Write for an agent that supports the facilitator's judgement rather than replacing it: the facilitator still reads the room and decides what happens next.
|
|
10
10
|
|
|
11
|
+
**Keywords:** AI facilitation, facilitator's AI agent, AI assistant, agent tools, external endpoint, endpoint visibility, describe data for a model, schema descriptions, what an agent can see
|
|
12
|
+
|
|
11
13
|
## What the agent can see
|
|
12
14
|
|
|
13
15
|
A game's data lives in named capabilities. Every screen declares which ones it needs, and receives exactly those. The agent is handed data the same way, so nothing you have not declared reaches it.
|
|
@@ -4,6 +4,8 @@ Capabilities hold your game's state: named groups of variables that the engine a
|
|
|
4
4
|
|
|
5
5
|
This guide explains the state model, who sees and writes each capability, and how long its values last, then covers creating capabilities and every kind of variable they hold.
|
|
6
6
|
|
|
7
|
+
**Keywords:** capability, game state, variables, variablesSchema, context, reads and writes, private capability, scope, lifetime, keyed collection, variable types, new capability
|
|
8
|
+
|
|
7
9
|
## The state model
|
|
8
10
|
|
|
9
11
|
A capability is a named collection of related variables, declared by a schema. For example:
|
|
@@ -4,12 +4,20 @@ A serious game teaches by letting people act and then see what their actions cau
|
|
|
4
4
|
|
|
5
5
|
The rest of the docs explain how to build each part. This page is about what to build, so read it before you replace the lemonade stand with your own game.
|
|
6
6
|
|
|
7
|
+
What follows are suggestions, not rules. Each one steers towards a game people learn from, and any of them can be set aside when your game has a reason to.
|
|
8
|
+
|
|
9
|
+
**Keywords:** game design, design a serious game, learning outcome, decisions, rounds, feedback, debrief, pacing, facilitator, brief to game, plan a simulation
|
|
10
|
+
|
|
7
11
|
## Start from what people should take away
|
|
8
12
|
|
|
9
13
|
Write down the one or two things a participant should understand, or do differently, by the end. Everything else in the design serves them.
|
|
10
14
|
|
|
11
15
|
Lemonade Stand has one: making too much and making too little are both mistakes, they cost different amounts, and the costlier one is the one you cannot see. A good learning outcome is like that: specific enough that you can tell whether a round of play showed it.
|
|
12
16
|
|
|
17
|
+
Write an aim, not a topic. 'Teamwork' is a topic. 'Teams that share information early recover from a crisis faster' is an aim: it says what changes in the people who play.
|
|
18
|
+
|
|
19
|
+
Then find the one tension the game is built around: a trade-off players keep facing, round after round. Lemonade Stand's is waste against lost sales. If you cannot name it yet, find it before you design anything else.
|
|
20
|
+
|
|
13
21
|
Then ask what experience would make the point land better than being told it. A serious game earns its place when the lesson is easy to agree with and hard to act on: people nod at 'unsold stock is waste' and then over-correct after one bad day. Play lets them make that mistake, feel it, and talk about it in the debrief.
|
|
14
22
|
|
|
15
23
|
## Choose the decisions
|
|
@@ -19,6 +27,9 @@ A decision is what a team changes each round. Pick the smallest set that carries
|
|
|
19
27
|
- **Few, and meaningful**: every decision should pull against another. Lemonade Stand has one per menu item, how many to make, and they all draw on the same 120 a day the stall can make
|
|
20
28
|
- **No right answer from the screen**: if the best choice can be worked out from what is shown, the game becomes arithmetic. Lemonade Stand's forecast is close to the day's demand, never exact
|
|
21
29
|
- **Something to talk about**: a decision a team can disagree on gives the facilitator something to listen for
|
|
30
|
+
- **Three to five a round**: fewer in the first round, while people learn the screen. The team decides; the engine works out what happens
|
|
31
|
+
- **Every option has its moment**: each option should be the right choice in some situation. One that never wins is a design problem, fixed by changing what it does rather than its numbers. Playing the game shows you which those are, so leave the numbers until it plays (see [Build it playable, then balance it](#build-it-playable-then-balance-it))
|
|
32
|
+
- **Everything earns its place**: each mechanic should serve the learning outcome. 'It makes it more engaging' is not enough on its own: a simulation is no more motivating than other teaching unless the design makes it so
|
|
22
33
|
|
|
23
34
|
Each decision becomes a value in a [capability](./capabilities.md), the state a team writes to. Lemonade Stand's live in `plan`, one number per item. Key them so two teammates changing two decisions never overwrite each other: see [Design state for concurrent writes](../recipes/design-state-for-concurrent-writes.md).
|
|
24
35
|
|
|
@@ -29,6 +40,7 @@ Feedback is where the learning happens during play. After each round, a team sho
|
|
|
29
40
|
- **Consequences, not just a score**: Lemonade Stand's 'How yesterday went' shows what sold, what was poured away, and who was turned away, not just the money
|
|
30
41
|
- **Both sides of the trade-off**: if one mistake is visible and the other is not, show the invisible one. The lemonade stand counts the people it turned away for exactly this reason
|
|
31
42
|
- **Enough to change their mind**: the round's results should suggest what to try next, without telling them
|
|
43
|
+
- **Score what the aim teaches**: a score rewards a behaviour, so make it the behaviour you want. Ask whether a ranking helps the lesson or gets in its way, rather than assuming either. If you rank teams, a scorecard of several measures, shown at the end, keeps any one measure from deciding it
|
|
32
44
|
|
|
33
45
|
The rules that turn decisions into consequences are the [engine](./engine.md): its `Run` plays one round, and the results go into capabilities the screens read. What the screens show, and how, is the [game UI](./ui.md).
|
|
34
46
|
|
|
@@ -37,8 +49,10 @@ The rules that turn decisions into consequences are the [engine](./engine.md): i
|
|
|
37
49
|
How many rounds, and who decides when each one ends, is a learning-design choice as much as a technical one:
|
|
38
50
|
|
|
39
51
|
- **Enough rounds to try, fail, and try again**: a lesson about adjusting needs at least three or four rounds after the first mistake. Lemonade Stand runs ten days; its Heatwave scenario runs five
|
|
40
|
-
- **Who ends the round**: when the facilitator or the team ends each round, there is time to discuss. When a [tick controller](./tick-controller.md) ends it on a timer, there is pressure, which suits a lesson about deciding with too little time
|
|
41
|
-
- **Together or apart**: in an independent game, each team plays at its own pace, as the lemonade stalls do. In a shared one, teams play the same market or the same world, and every round waits for all of them. See [Multi-team games](./multi-team-games.md)
|
|
52
|
+
- **Who ends the round**: when the facilitator or the team ends each round, there is time to discuss. When a [tick controller](./tick-controller.md) ends it on a timer, there is pressure, which suits a lesson about deciding with too little time. Timers, scarcity, and loss all cost psychological safety, so use pressure only where it is the lesson, and otherwise let the facilitator end each round
|
|
53
|
+
- **Together or apart**: in an independent game, each team plays at its own pace, as the lemonade stalls do. In a shared one, teams play the same market or the same world, and every round waits for all of them. Choose independent teams unless interaction between them is the lesson. See [Multi-team games](./multi-team-games.md)
|
|
54
|
+
- **Stuck and trailing teams**: in a shared world, decide how one stuck team is kept from holding up the room. If teams compete, decide what stops a leader being out of reach by round three, and what keeps a trailing team playing
|
|
55
|
+
- **Teams, not individuals**: teams of three to five, who discuss before they decide, learn more than people playing alone
|
|
42
56
|
|
|
43
57
|
The number of rounds is `maxTicks`, a [setting](./settings.md) a scenario or a facilitator can change.
|
|
44
58
|
|
|
@@ -46,7 +60,8 @@ The number of rounds is `maxTicks`, a [setting](./settings.md) a scenario or a f
|
|
|
46
60
|
|
|
47
61
|
The facilitator turns play into learning. Give them what they need to do that:
|
|
48
62
|
|
|
49
|
-
- **A view of the whole room**: the [session UI](./session.md) shows every team side by side, so a facilitator can spot a team that has stopped thinking and go and talk to them
|
|
63
|
+
- **A view of the whole room**: the [session UI](./session.md) shows every team side by side, so a facilitator can spot a team that has stopped thinking and go and talk to them. A cross-team view that makes a teaching point is worth more than a dashboard to watch
|
|
64
|
+
- **Things to do**: nudges and prompts to send during play give a facilitator a part in the game, not just a seat beside it
|
|
50
65
|
- **Control**: holding the room in the [waiting room](./waiting-room.md) for a briefing, undoing a round a team did not mean to play, and ending the game
|
|
51
66
|
- **A guide**: the [facilitator guide](./guide.md) is the run-sheet: timings, what to say, what to watch for, and the debrief questions. Write it alongside the game, not after
|
|
52
67
|
- **Room to adapt**: put every number a facilitator might want to change in [settings](./settings.md), and offer them a [setup screen](./setup.md) for the ones that change from group to group
|
|
@@ -57,7 +72,9 @@ Make mistakes safe. Undo, a practice round, and results that point at the decisi
|
|
|
57
72
|
|
|
58
73
|
The debrief is where the experience becomes lasting learning, so design it from the start rather than adding it at the end:
|
|
59
74
|
|
|
60
|
-
- **Questions first**:
|
|
75
|
+
- **Questions first**: settle two or three questions early, such as 'which mistake did you make more often, and which cost you more?'. Then make sure the game produces the evidence for each answer
|
|
76
|
+
- **Record the evidence**: keep each team's decisions and results, and their reasons where you can ask for them, in [capabilities](./capabilities.md), so there is something to discuss
|
|
77
|
+
- **Time for it**: plan the debrief as a real part of the session, not a few minutes at the end
|
|
61
78
|
- **Evidence from the session**: a [presentation](./presentation.md) builds its slides from the session's own results, so the room sees its own numbers, not a generic example
|
|
62
79
|
- **Look back**: a team can [review a past round](../recipes/review-a-past-day.md) to see the moment a decision went wrong
|
|
63
80
|
|
|
@@ -67,6 +84,16 @@ Lemonade Stand's guide closes its debrief on the two kinds of mistake, with ques
|
|
|
67
84
|
|
|
68
85
|
One game can serve different groups and different objectives through [scenarios](./scenarios.md): named sets of settings and assets. Lemonade Stand has two, 'An ordinary week' and 'Heatwave', which teach the same outcome with different pressure. A scenario changes values, never rules, so decide early which numbers belong in settings.
|
|
69
86
|
|
|
87
|
+
## Build it playable, then balance it
|
|
88
|
+
|
|
89
|
+
Get the game playing before you tune it. Balancing numbers while the mechanics are still changing is wasted work, because the next change to a mechanic undoes it.
|
|
90
|
+
|
|
91
|
+
- **One round first**: pin one round end to end before anything else, with its decisions, its rules, what it shows, and what the debrief will ask about it. Make it a real decision in a world that already has a history, rather than a blank start, with a worked example first if players are new to the idea
|
|
92
|
+
- **An order that keeps it running**: the state and the engine with their [tests](./testing.md) first, then the screens players use, then the facilitator's screens, the guide, and the presentation
|
|
93
|
+
- **Sensible numbers, not tuned ones**: start from values that look plausible, and settle the mechanics by playing
|
|
94
|
+
- **Targets written as outcomes**: while you design, write down what balance should look like in play, such as 'a team that chases this week's profit leads early and finishes behind one that holds a steady strategy'. They are what you balance against later
|
|
95
|
+
- **Balance last**: once the game plays end to end, play whole games with a handful of strategies (careful, greedy, reactive), tune two or three numbers by hand, and note why each one changed
|
|
96
|
+
|
|
70
97
|
## From design to package
|
|
71
98
|
|
|
72
99
|
| Design decision | Where it goes |
|