@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
|
@@ -6,6 +6,8 @@ This guide covers declaring them, reading them from logic and surfaces, overridi
|
|
|
6
6
|
|
|
7
7
|
Not to be confused with [global settings](./global-settings.md), the file in your home directory that holds API keys for every project.
|
|
8
8
|
|
|
9
|
+
**Keywords:** settings, parameters, settingsSchema, defaults, read settings, override settings, configure, scenario settings, locked settings, game settings, hidden values, sdk configure
|
|
10
|
+
|
|
9
11
|
## Overview
|
|
10
12
|
|
|
11
13
|
A settings resource is a schema and nothing else. It lives at `settings/<identifier>/settings.sdk.json`, and a package may hold any number of them, as it does capabilities.
|
|
@@ -4,6 +4,8 @@ The `setup` slot holds the small form a facilitator fills in when they create a
|
|
|
4
4
|
|
|
5
5
|
This guide covers creating one, building its form, and how it behaves in the dev server.
|
|
6
6
|
|
|
7
|
+
**Keywords:** setup screen, setup form, session creation, configures, per-session settings, number of rounds, requestPlay, start play, facilitator form
|
|
8
|
+
|
|
7
9
|
## What setup is
|
|
8
10
|
|
|
9
11
|
A game holds at most one setup screen, at `setup/`. It is a slot, like `session` or `waiting_room`, so it carries no name of its own: the slot is its identifier.
|
|
@@ -143,7 +145,7 @@ An endpoint called from setup sees `caller.role` as `'facilitator'`.
|
|
|
143
145
|
Setup is embedded in the host's page, not a page of its own:
|
|
144
146
|
|
|
145
147
|
- **Leave the ground to the host.** Do not paint a page background. MUI's `CssBaseline` paints the body, so override it with `<GlobalStyles styles={{ body: { backgroundColor: 'transparent' } }} />`
|
|
146
|
-
- **
|
|
148
|
+
- **Avoid dialogs with a backdrop.** A modal inside an iframe darkens only the frame, not the host's bar above it. Use a side panel, a confirmation beside the button that asked, or full screen
|
|
147
149
|
- **Do not reproduce host chrome.** The language picker, the theme control, and the Play action live outside your iframe
|
|
148
150
|
|
|
149
151
|
The [session UI guide](./session.md#rendering-inside-the-host) covers the same ground in more detail.
|
|
@@ -6,6 +6,8 @@ The SDK exposes a provider-agnostic text-to-speech callback, `generateSpeech`. E
|
|
|
6
6
|
|
|
7
7
|
The dev server ships with one provider adapter (ElevenLabs). Additional providers (OpenAI, Google Cloud, Azure, AWS Polly) will land behind a future `TTS_PROVIDER` env var without breaking changes to game code.
|
|
8
8
|
|
|
9
|
+
**Keywords:** speech, text-to-speech, TTS, generateSpeech, voice, voice presets, audio, ElevenLabs, ELEVENLABS_API_KEY, narration
|
|
10
|
+
|
|
9
11
|
## Overview
|
|
10
12
|
|
|
11
13
|
`generateSpeech` accepts either a bare string or a request object, mirroring `generateText`:
|
|
@@ -13,7 +13,8 @@ Most of the starter game is ordinary, but four decisions in it are the ones a fi
|
|
|
13
13
|
- **State keyed so participants cannot overwrite each other.** `plan.Make` is keyed by menu item, and a hook puts each participant in charge of one item, so two people changing two numbers write two different keys
|
|
14
14
|
- **A validator on the one thing they share.** Two changes can each fit while the merged plan busts the stall's capacity. No shape of state prevents that, so `validators/capacity` checks the merged result
|
|
15
15
|
- **Every write awaited.** The game UI reports a refused write to the participant who made it, instead of showing a decision the game never received
|
|
16
|
-
- **Teams run their own days.** The game is in independent mode: each team opens its stall when it is ready
|
|
16
|
+
- **Teams run their own days.** The game is in independent mode: each team opens its stall when it is ready. The facilitator does not run the day; they hold the room at a day with a limit a validator enforces, watch, and can undo
|
|
17
|
+
- **Screens designed for where they are used.** Each screen leads with its one decision, works at phone size, uses the host's colours and an icon set rather than drawn icons, and asks 'are you sure?' beside the button rather than in a dialog. See [Designing screens](./designing-screens.md)
|
|
17
18
|
|
|
18
19
|
[Design state for concurrent writes](../recipes/design-state-for-concurrent-writes.md) explains the first two in full.
|
|
19
20
|
|
|
@@ -35,13 +36,14 @@ See [Shaping games](./games.md).
|
|
|
35
36
|
|
|
36
37
|
Each directory is one capability, a named slice of the game's state with a JSON Schema for its variables. There is no logic here.
|
|
37
38
|
|
|
38
|
-
| Capability | Holds
|
|
39
|
-
| ---------- |
|
|
40
|
-
| `plan` | How many of each item to make today, keyed by item. The one capability participants write
|
|
41
|
-
| `weather` | Today's forecast and roughly how many people will want each item
|
|
42
|
-
| `results` | What happened yesterday, item by item, and the money: takings, spending, profit, and the running total in the jar
|
|
43
|
-
| `roles` | Which item each participant looks after, keyed by participant id
|
|
44
|
-
| `briefing` | A note from the facilitator shown on every team's screen. `shared` scope, so there is one value for the whole session
|
|
39
|
+
| Capability | Holds |
|
|
40
|
+
| ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
|
41
|
+
| `plan` | How many of each item to make today, keyed by item. The one capability participants write |
|
|
42
|
+
| `weather` | Today's forecast and roughly how many people will want each item |
|
|
43
|
+
| `results` | What happened yesterday, item by item, and the money: takings, spending, profit, and the running total in the jar |
|
|
44
|
+
| `roles` | Which item each participant looks after, keyed by participant id |
|
|
45
|
+
| `briefing` | A note from the facilitator shown on every team's screen. `shared` scope, so there is one value for the whole session |
|
|
46
|
+
| `pacing` | `LastOpenDay`, the last day a stall may open. `shared` scope, written only by the facilitator's screen; the default opens all ten |
|
|
45
47
|
|
|
46
48
|
See [Capabilities](./capabilities.md).
|
|
47
49
|
|
|
@@ -56,7 +58,7 @@ Each directory is one settings resource: read-only parameters, every one with a
|
|
|
56
58
|
| `menu` | `Capacity` (120) and the `Menu`, each item's name, cost, and price | The engine, every surface, the hook, and the validator |
|
|
57
59
|
| `engine` | `UsualDemand` for each item, `SunnyPull`, `RainyPull`, and `Variation`. Only the engine reads it, so no participant's browser ever holds the demand | The engine |
|
|
58
60
|
| `ui` | `Step` and `CurrencySymbol` | The game UI |
|
|
59
|
-
| `session` | `ShowJoinLinks` and `CurrencySymbol` | The session UI
|
|
61
|
+
| `session` | `ShowJoinLinks` and `CurrencySymbol` | The session UI and the presentation |
|
|
60
62
|
|
|
61
63
|
See [Settings](./settings.md).
|
|
62
64
|
|
|
@@ -84,39 +86,77 @@ See [Hooks](./hooks.md).
|
|
|
84
86
|
|
|
85
87
|
A validator that sees every change a UI makes to the plan before it is applied. It reads the `menu` settings, and refuses a plan that asks for more than the stall's capacity, a negative or fractional count, or an item not on the menu. It never changes state; it only says no, with a message the game UI shows.
|
|
86
88
|
|
|
89
|
+
### `validators/daylimit/`
|
|
90
|
+
|
|
91
|
+
A validator with a `RequestTick` gate and no `UpdateData`. It refuses a stall's request to open a day after `pacing.LastOpenDay`, so the facilitator's hold is enforced on the server rather than only by a disabled button. Only a participant's request reaches it; the facilitator's own actions are never held.
|
|
92
|
+
|
|
87
93
|
See [Validators](./validators.md).
|
|
88
94
|
|
|
89
95
|
## User interfaces
|
|
90
96
|
|
|
91
|
-
Each is a small React app built with Vite
|
|
97
|
+
Each is a small React app built with Vite, with its own `index.html`, `src/main.tsx` (the SDK wrapper, locale, and right-to-left set-up), and `src/i18n.ts` (every string on the screen). The three screens people use are built with MUI and add `src/theme.ts` (`createSurfaceTheme` over the host's theme, with Work Sans as the font); the presentation is built with the SDK's deck library instead.
|
|
98
|
+
|
|
99
|
+
### `shared/`
|
|
100
|
+
|
|
101
|
+
Code every screen uses, imported by relative path. It is not a slot, so the build and the scaffold treat it as ordinary source.
|
|
102
|
+
|
|
103
|
+
- `Awning.tsx`: the scalloped edge under each top bar, in the host's primary colour. It is the game's one drawn motif; everything else comes from the icon set
|
|
104
|
+
- `HostLogo.tsx`: the host's logo, with the variant chosen for the coloured bar, or nothing when the host sends none
|
|
105
|
+
- `StallIcons.tsx`: the Material icon and tint for each menu item and each kind of weather
|
|
106
|
+
- `format.ts`: money from pence, and counts. `days.ts`: the length of the week, read from the manifest's `maxTicks`
|
|
92
107
|
|
|
93
108
|
### `ui/`
|
|
94
109
|
|
|
95
|
-
The game UI: what each participant sees.
|
|
110
|
+
The game UI: what each participant sees. It leads with today's decision and keeps the button that opens the stall in a bar at the bottom of the layout, never floating over it.
|
|
96
111
|
|
|
97
|
-
- `src/App.tsx`: the layout
|
|
98
|
-
- `src/
|
|
99
|
-
- `src/
|
|
100
|
-
- `src/
|
|
101
|
-
- `src/
|
|
102
|
-
- `src/writes.ts`: one mutation reporter every write goes through
|
|
103
|
-
- `src/menu.ts`, `src/
|
|
104
|
-
- `ui.sdk.json`: reads every capability it shows, writes only `plan`, and reads the `ui` settings (`Step` and `CurrencySymbol`)
|
|
112
|
+
- `src/App.tsx`: the layout and the state it is in: before day 1 (`src/FirstDay.tsx`), mid-week, looking back at a past day (`src/PastDay.tsx`), and the week over (`src/WeekOver.tsx`)
|
|
113
|
+
- `src/Header.tsx`: the stall's name, the item the participant looks after, and a timeline of the days, where a day already played opens that day
|
|
114
|
+
- `src/WeatherCard.tsx`, `src/TodayPanel.tsx` and `src/MakeRow.tsx`: today's forecast and the controls for the plan, one row per item, with the participant's own item marked
|
|
115
|
+
- `src/DayBar.tsx`: the bottom bar. **Open the stall for day N** calls `requestTick`; when the facilitator's limit holds the stall it is disabled and says so
|
|
116
|
+
- `src/YesterdayPanel.tsx`, `src/Lesson.tsx` and `src/DaysTable.tsx`: yesterday as one profit figure and one lesson, and every day so far. Earlier days come from the host with `usePastState`, so nothing in context grows as the days go by (see [Review a past day in a UI](../recipes/review-a-past-day.md))
|
|
117
|
+
- `src/Notices.tsx` and `src/writes.ts`: the facilitator's notice, and the one mutation reporter every write goes through, so a refusal reaches the person who made it
|
|
118
|
+
- `src/menu.ts`, `src/days.ts`, `src/Section.tsx`, `src/ThemeToggle.tsx`: menu ordering, day helpers, the card layout, and a light or dark switch
|
|
119
|
+
- `ui.sdk.json`: reads every capability it shows, `pacing` included, writes only `plan`, and reads the `ui` settings (`Step` and `CurrencySymbol`)
|
|
105
120
|
|
|
106
121
|
See [Building user interfaces](./ui.md).
|
|
107
122
|
|
|
108
123
|
### `session/`
|
|
109
124
|
|
|
110
|
-
The session UI: the facilitator's whole screen, which the dev server shows at `/` as the console. It
|
|
125
|
+
The session UI: the facilitator's whole screen, which the dev server shows at `/` as the console. It follows what most facilitator screens need, and leaves out what only some games do:
|
|
126
|
+
|
|
127
|
+
- `src/SessionBar.tsx`: one line across the top. The day limit, which writes `pacing.LastOpenDay`, the waiting room, and the facilitator guide and slides when the host offers them
|
|
128
|
+
- `src/StallCard.tsx` and `src/status.ts`: a card per stall with the day it is on, who is connected, what is in the jar, and links to observe it or copy its join link
|
|
129
|
+
- `src/ManagePanel.tsx` and `src/SidePanel.tsx`: a panel beside the cards, with no backdrop, to rename a stall, move a person, or undo a day, confirmed in place
|
|
130
|
+
- `src/Results.tsx`: the room's averages and range above a sortable table, any day played so far, and full screen for the projector
|
|
131
|
+
- `src/JoinCodes.tsx`: each stall's join link in large type, one stall at a time, for the room to read
|
|
132
|
+
- `src/SessionPanels.tsx`: the notice to the room (the shared `briefing`) and starting the session again
|
|
133
|
+
|
|
134
|
+
`ShowJoinLinks`, in the `session` settings it reads, turns the per-team join and observe links off.
|
|
111
135
|
|
|
112
136
|
See [Building session UIs](./session.md).
|
|
113
137
|
|
|
114
138
|
### `waiting_room/`
|
|
115
139
|
|
|
116
|
-
The screen participants see while the session is held. It tells a held start ('
|
|
140
|
+
The screen participants see while the session is held. It tells a held start ('Your stall opens soon') from a pause part-way through, shows who is on the team, lets the team name its stall, and copies the join link for anyone else joining.
|
|
117
141
|
|
|
118
142
|
See [Building waiting room UIs](./waiting-room.md).
|
|
119
143
|
|
|
144
|
+
### `presentation/`
|
|
145
|
+
|
|
146
|
+
The facilitator's slide deck, which they project for the room. It is read-only, and it renders with or without a session, so a facilitator can rehearse it or export it before the day.
|
|
147
|
+
|
|
148
|
+
- `src/Slides.tsx`: a title slide, one slide a day with the forecast and how the room did the day before, and a results slide for the room. The projector shows the room, never a stall by name: each stall's figures are in the speaker notes
|
|
149
|
+
- `src/stalls.ts`: the room's figures, kept apart from the slides so `src/stalls.test.ts` can test them without a deck. The stalls run their own days, so a day's figures count only the stalls that have played it, read through `usePastState`
|
|
150
|
+
- `src/Band.tsx` and `src/WeatherIcon.tsx`: the awning and the weather icon in the deck's own colours, since a deck has no MUI theme
|
|
151
|
+
- `src/App.tsx`: the `Deck`, with the host's theme as its colours, and opening on the day the room has reached
|
|
152
|
+
- `presentation.sdk.json`: reads `plan`, `weather` and `results`, and the `session` settings for the currency symbol
|
|
153
|
+
|
|
154
|
+
The dev server shows it at `/presentation`, and at `/presentation?preview` with no session.
|
|
155
|
+
|
|
156
|
+
See [Building presentations](./presentation.md).
|
|
157
|
+
|
|
158
|
+
The starter has no `setup/` or `scenario_editor/`, to keep it a quick first read. `examples/factory` in the SDK repository has both, and [Building setup screens](./setup.md) and [Building scenario editors](./scenario-editor.md) cover them.
|
|
159
|
+
|
|
120
160
|
## Content
|
|
121
161
|
|
|
122
162
|
### `scenarios/`
|
|
@@ -142,7 +182,7 @@ Whole-game tests that play several days in-process with `createTestSession`: no
|
|
|
142
182
|
|
|
143
183
|
### `testing/e2e/`
|
|
144
184
|
|
|
145
|
-
Playwright tests against
|
|
185
|
+
Playwright tests against real dev servers, one for each worker, on free ports beside any you have running. `testing/e2e/global-setup.ts` builds the surfaces once for them all. Run them with `pnpm test:e2e`. See [Test UIs end to end with Playwright](../recipes/e2e-testing.md).
|
|
146
186
|
|
|
147
187
|
The unit and component tests sit beside the code they test (`*.test.ts`, `*.test.tsx`) and run with `pnpm test:run`.
|
|
148
188
|
|
|
@@ -155,7 +195,7 @@ These are written by `new package` for every package, starter game or not:
|
|
|
155
195
|
| `package.json` | Dependencies, and the scripts: `sdk`, `generate`, `build`, `test:run`, `test:engine`, `test:e2e`, `typecheck`, `lint` |
|
|
156
196
|
| `tsconfig.json`, `globals.d.ts` | TypeScript settings, and declarations for the font imports |
|
|
157
197
|
| `vite.config.ts`, `vitest.config.ts`, `test-setup.ts` | Build and component-test settings, including the single copy of React and the SDK every UI needs |
|
|
158
|
-
| `vitest.engine.config.ts`, `playwright.config.ts` | Settings for the whole-game and browser test suites, and `testing/e2e/global-setup.ts`, which
|
|
198
|
+
| `vitest.engine.config.ts`, `playwright.config.ts` | Settings for the whole-game and browser test suites, and `testing/e2e/global-setup.ts`, which builds the browser suite's surfaces |
|
|
159
199
|
| `pnpm-workspace.yaml` | Dependency overrides and install-script decisions the SDK tooling needs |
|
|
160
200
|
| `.oxlintrc.json`, `.oxfmtrc.json` | Lint and format settings |
|
|
161
201
|
| `README.md`, `DESIGN.md` | A readme, and prompts for writing down your game's design as you build it |
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
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.
|
|
4
4
|
|
|
5
|
+
**Keywords:** testing, unit tests, UI tests, Vitest, React Testing Library, renderUserInterface, createMock, test Run, test Init, Playwright, jsdom, test hooks
|
|
6
|
+
|
|
5
7
|
## Testing engine logic
|
|
6
8
|
|
|
7
9
|
### Starting from the generated defaults
|
|
@@ -516,7 +518,7 @@ Unit and integration tests cover logic and components in isolation. Browser E2E
|
|
|
516
518
|
The SDK provides selectors and helpers via a dedicated subpath export with no Playwright dependency of its own:
|
|
517
519
|
|
|
518
520
|
```typescript
|
|
519
|
-
import { expect, test } from '@playwright
|
|
521
|
+
import { expect, test } from '@seriousgaming/sdk-tools/playwright';
|
|
520
522
|
import { DEV_SERVER, reinitialiseSession } from '@seriousgaming/sdk/e2e';
|
|
521
523
|
|
|
522
524
|
test.beforeEach(async () => {
|
|
@@ -543,38 +545,53 @@ makes the 'Try again' path your UI offers reachable. `waitForState` waits for
|
|
|
543
545
|
something that happens after its command answers, and `advanceClock` moves the
|
|
544
546
|
time of a server started with a `FakeClock` on, so automatic ticks are tested without waiting.
|
|
545
547
|
|
|
546
|
-
When you create a project with `sdk new package`, a `playwright.config.ts`, the global setup that
|
|
548
|
+
When you create a project with `sdk new package`, a `playwright.config.ts`, the global setup that builds its surfaces (`testing/e2e/global-setup.ts`, below) and a `testing/e2e/game.spec.ts` starter are generated automatically.
|
|
547
549
|
|
|
548
550
|
### A dev server for browser tests
|
|
549
551
|
|
|
550
|
-
|
|
552
|
+
A dev server holds one session, so tests sharing one server have to run one at a time. The `test` exported by `@seriousgaming/sdk-tools/playwright` starts an isolated dev server for each Playwright worker instead, so tests in different workers never share a session and the suite runs in parallel:
|
|
551
553
|
|
|
552
554
|
- It takes free ports, so it starts beside your own dev server rather than asking you to stop it
|
|
553
555
|
- It writes no lock file, so `sdk tick` in your terminal still reaches your own server
|
|
554
556
|
- It reads configuration from the package alone, ignoring what you last ran `sdk configure` with
|
|
555
|
-
- Uploads go to a temporary directory, removed
|
|
557
|
+
- Uploads go to a temporary directory, removed when the worker ends
|
|
558
|
+
|
|
559
|
+
It points `baseURL` and the `@seriousgaming/sdk/e2e` helpers at the worker's server, so a test passes them no options. Tests that land in the same worker share its server one after another, which is why each spec still calls `reinitialiseSession()` in `beforeEach`.
|
|
556
560
|
|
|
557
561
|
```typescript
|
|
558
|
-
//
|
|
559
|
-
import {
|
|
562
|
+
// playwright.config.ts, as the scaffold writes it
|
|
563
|
+
import { defineConfig } from '@playwright/test';
|
|
560
564
|
|
|
561
|
-
|
|
562
|
-
|
|
565
|
+
export default defineConfig({
|
|
566
|
+
testDir: './testing/e2e',
|
|
567
|
+
globalSetup: './testing/e2e/global-setup.ts',
|
|
568
|
+
fullyParallel: true,
|
|
569
|
+
});
|
|
570
|
+
```
|
|
563
571
|
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
});
|
|
568
|
-
process.env.SERIOUSGAMING_DEV_URL = server.url;
|
|
569
|
-
return () => server.stop();
|
|
570
|
-
}
|
|
572
|
+
```typescript
|
|
573
|
+
// testing/e2e/global-setup.ts
|
|
574
|
+
export { globalSetup as default } from '@seriousgaming/sdk-tools/playwright';
|
|
571
575
|
```
|
|
572
576
|
|
|
573
|
-
|
|
577
|
+
The global setup builds the package's surfaces once, before any test runs, and every worker's server serves that build as files. Without it, each server would compile the same surfaces through Vite the first time a page asks for them. The build is removed when the run ends, and a change you make to a surface during a run is not seen until the next one. To serve the output of your own `pnpm run sdk build` and build nothing, set `SERIOUSGAMING_BUILT_SURFACES=dist`.
|
|
578
|
+
|
|
579
|
+
Set the servers' options with `devServerOptions`, in the config's `use` for every test or with `test.use` for one file. It takes `teams`, `participants`, `scenarioId`, `locale`, `clock` (a `FakeClock`) and `callbacks`, as [`createTestSession`](./engine-testing.md) does:
|
|
580
|
+
|
|
581
|
+
```typescript
|
|
582
|
+
import { FakeClock } from '@seriousgaming/sdk-tools/client';
|
|
583
|
+
import { test } from '@seriousgaming/sdk-tools/playwright';
|
|
584
|
+
|
|
585
|
+
test.use({ devServerOptions: { clock: new FakeClock(Date.now()) } });
|
|
586
|
+
```
|
|
587
|
+
|
|
588
|
+
#### Starting a server yourself
|
|
589
|
+
|
|
590
|
+
`startDevServer` from `@seriousgaming/sdk-tools/client` is what the fixture runs, for a recording script or another test runner. It is what `sdk dev --isolated --port auto` runs, without spawning the CLI and parsing its output, and resolves once the server answers. It returns `{ url, assetUrl, stop() }`: `url` is the console and API, and `assetUrl` is where game surfaces are served from. Pass `{ url: server.url }` to the `@seriousgaming/sdk/e2e` helpers, or set `SERIOUSGAMING_DEV_URL` to it, which also sends CLI commands there. Always call `stop()`: the server holds its ports and a file watcher open until then.
|
|
574
591
|
|
|
575
|
-
|
|
592
|
+
`buildSurfaces({ packagePath })` builds the surfaces into a temporary directory and returns `{ directory, remove() }`; pass `directory` to `startDevServer` as `builtSurfaces`. `sdk dev --built-surfaces <DIR>` does the same from the command line.
|
|
576
593
|
|
|
577
|
-
|
|
594
|
+
Do not start the server with Playwright's `webServer` running `pnpm run sdk dev`: Playwright stops it through `pnpm`, which never reaches the server, and the run hangs.
|
|
578
595
|
|
|
579
596
|
See [Recipe: Test UIs end to end with Playwright](../recipes/e2e-testing.md) for the full setup guide, all available selectors, and common patterns.
|
|
580
597
|
|
|
@@ -4,6 +4,8 @@ A tick controller makes ticks happen on their own, on a schedule your logic deci
|
|
|
4
4
|
|
|
5
5
|
This guide explains the model, then is the reference for writing one.
|
|
6
6
|
|
|
7
|
+
**Keywords:** tick controller, timer, automatic ticks, interval, schedule, timed rounds, nextTickAt, game completion, complete, enabled, pause, extend a tick, cron
|
|
8
|
+
|
|
7
9
|
## The model
|
|
8
10
|
|
|
9
11
|
By default, ticks are manual: a participant or facilitator presses a control, or a command is sent, to advance the game. That suits a game that moves one decision at a time. Some games need time to move on its own, or at a pace that depends on what is happening in the simulation. Some also need to end when a goal is met rather than after a fixed number of ticks.
|
|
@@ -410,7 +412,7 @@ pnpm run sdk timer extend 120 # two more minutes (the CLI takes second
|
|
|
410
412
|
pnpm run sdk timer resume --team 2 # one team, in an independent game
|
|
411
413
|
```
|
|
412
414
|
|
|
413
|
-
The current schedule, a [`TimerState`](../api/sdk-ui.md#timerstate) with every duration and timestamp in milliseconds, is pushed to every game UI. UIs subscribe with `useUserInterfaceTimer` and render their own countdown or progress bar. See [Displaying the tick timer](./ui.md#displaying-the-tick-timer) in the user interfaces guide.
|
|
415
|
+
The current schedule, a [`TimerState`](../api/sdk-ui.md#timerstate) with every duration and timestamp in milliseconds, is pushed to every game UI. UIs subscribe with `useUserInterfaceTimer` and render their own countdown or progress bar. See [Displaying the tick timer](./ui-ticks.md#displaying-the-tick-timer) in the user interfaces guide.
|
|
414
416
|
|
|
415
417
|
## Testing without waiting
|
|
416
418
|
|
|
@@ -4,6 +4,8 @@ The SDK generates TypeScript types from your schemas, so a misspelt variable fai
|
|
|
4
4
|
|
|
5
5
|
This guide covers the rules that keep that guarantee, and the shortcuts that quietly break it.
|
|
6
6
|
|
|
7
|
+
**Keywords:** type safety, TypeScript, generated types, types.ts, sdk generate, any, type casts, JSON Schema types, schema constraints, strict types
|
|
8
|
+
|
|
7
9
|
## Core principle
|
|
8
10
|
|
|
9
11
|
The Serious Gaming SDK uses TypeScript and JSON Schema to provide **end-to-end type safety**. When you define a capability's `variablesSchema` or a settings resource's `settingsSchema`, the SDK generates precise TypeScript types. Shortcuts and workarounds (using `any`, string-based JSON, etc.) break this guarantee and lead to runtime errors.
|