@seriousgaming/sdk-tools 1.5.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 +148 -43093
- 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 +228 -48
- package/dist/core/session.d.ts +15 -1
- package/dist/dev/console/assets/{index-BVF8exas.js → index-CuMOOH9m.js} +1 -1
- package/dist/dev/console/index.html +1 -1
- package/dist/dev/shell.d.ts +19 -0
- package/dist/dev/surfaces.d.ts +7 -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.md +19 -0
- package/dist/docs/cli-and-dev-server.md +21 -0
- package/dist/docs/cli-reference.md +45 -31
- package/dist/docs/environment-variables.md +6 -0
- package/dist/docs/guides/designing-a-game.md +29 -4
- package/dist/docs/guides/starter-game.md +2 -2
- package/dist/docs/guides/testing.md +33 -18
- package/dist/docs/page-index.md +8 -7
- package/dist/docs/recipes/e2e-testing.md +19 -20
- package/dist/playwright.js +32232 -0
- 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/starter-game/playwright.config.ts +8 -11
- package/dist/templates/starter-game/testing/e2e/game.spec.ts +1 -1
- package/dist/templates/starter-game/testing/e2e/global-setup.ts +7 -18
- package/dist/utils/prompt.d.ts +5 -5
- package/dist/utils/resource-scan.d.ts +39 -0
- package/package.json +7 -3
|
@@ -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
|
|
|
@@ -1973,26 +1973,28 @@ pnpm run sdk dev [options]
|
|
|
1973
1973
|
|
|
1974
1974
|
Start the Serious Gaming development server with hot reload.
|
|
1975
1975
|
|
|
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 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).
|
|
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. |
|
|
1996
1998
|
|
|
1997
1999
|
In more detail:
|
|
1998
2000
|
|
|
@@ -2006,6 +2008,7 @@ In more detail:
|
|
|
2006
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
|
|
2007
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)
|
|
2008
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)
|
|
2009
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)
|
|
2010
2013
|
|
|
2011
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`.
|
|
@@ -2030,6 +2033,15 @@ SERIOUSGAMING_DEV_URL=http://localhost:53712 pnpm run sdk tick
|
|
|
2030
2033
|
|
|
2031
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).
|
|
2032
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
|
+
|
|
2033
2045
|
**Several teams.** Start with N teams, each at its own URL:
|
|
2034
2046
|
|
|
2035
2047
|
```bash
|
|
@@ -2136,16 +2148,16 @@ Every edit falls into one of three buckets. Knowing which saves guessing at why
|
|
|
2136
2148
|
|
|
2137
2149
|
**Live: applied straight away, keeping the session where it is.**
|
|
2138
2150
|
|
|
2139
|
-
| You edit | What happens
|
|
2140
|
-
| ---------------------------------------------------------------------------------------------------------------------- |
|
|
2141
|
-
| A user interface (`ui/src/**`) | Vite hot-replaces the UI
|
|
2142
|
-
| 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
|
|
2143
|
-
| 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
|
|
2144
|
-
| A new surface, such as a `waiting_room/` or `presentation/` slot | Served at its URL as soon as its bundle is saved
|
|
2145
|
-
| A new capability, or one a resource starts to read or write |
|
|
2146
|
-
| `locales` or `supportedLocales` in `seriousgaming.sdk.json` | The session uses them from the next operation
|
|
2147
|
-
| Scenario or facilitator-guide markdown, or an asset file | The new content is served on the next request
|
|
2148
|
-
| 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 |
|
|
2149
2161
|
|
|
2150
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.
|
|
2151
2163
|
|
|
@@ -2160,6 +2172,8 @@ What happens to a pending change depends on whether anything has been played:
|
|
|
2160
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
|
|
2161
2173
|
- **Under `sdk dev --reinit-on-change`**, the session always re-initialises, however far play has gone
|
|
2162
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
|
+
|
|
2163
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.
|
|
2164
2178
|
|
|
2165
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.
|
|
@@ -65,6 +65,8 @@ A session command starts a dev server when none is running, and has no `--port`
|
|
|
65
65
|
| `SERIOUSGAMING_DEV_PUBLIC_URL` | No | Unset | The origin people reach the console at, behind a proxy |
|
|
66
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
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 |
|
|
68
70
|
|
|
69
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`.
|
|
70
72
|
|
|
@@ -74,6 +76,10 @@ A session command starts a dev server when none is running, and has no `--port`
|
|
|
74
76
|
|
|
75
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).
|
|
76
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
|
+
|
|
77
83
|
## Output and prompts
|
|
78
84
|
|
|
79
85
|
| Variable | Required | Default | Purpose |
|
|
@@ -4,6 +4,8 @@ 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
|
+
|
|
7
9
|
**Keywords:** game design, design a serious game, learning outcome, decisions, rounds, feedback, debrief, pacing, facilitator, brief to game, plan a simulation
|
|
8
10
|
|
|
9
11
|
## Start from what people should take away
|
|
@@ -12,6 +14,10 @@ Write down the one or two things a participant should understand, or do differen
|
|
|
12
14
|
|
|
13
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.
|
|
14
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
|
+
|
|
15
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.
|
|
16
22
|
|
|
17
23
|
## Choose the decisions
|
|
@@ -21,6 +27,9 @@ A decision is what a team changes each round. Pick the smallest set that carries
|
|
|
21
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
|
|
22
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
|
|
23
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
|
|
24
33
|
|
|
25
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).
|
|
26
35
|
|
|
@@ -31,6 +40,7 @@ Feedback is where the learning happens during play. After each round, a team sho
|
|
|
31
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
|
|
32
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
|
|
33
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
|
|
34
44
|
|
|
35
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).
|
|
36
46
|
|
|
@@ -39,8 +49,10 @@ The rules that turn decisions into consequences are the [engine](./engine.md): i
|
|
|
39
49
|
How many rounds, and who decides when each one ends, is a learning-design choice as much as a technical one:
|
|
40
50
|
|
|
41
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
|
|
42
|
-
- **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
|
|
43
|
-
- **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
|
|
44
56
|
|
|
45
57
|
The number of rounds is `maxTicks`, a [setting](./settings.md) a scenario or a facilitator can change.
|
|
46
58
|
|
|
@@ -48,7 +60,8 @@ The number of rounds is `maxTicks`, a [setting](./settings.md) a scenario or a f
|
|
|
48
60
|
|
|
49
61
|
The facilitator turns play into learning. Give them what they need to do that:
|
|
50
62
|
|
|
51
|
-
- **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
|
|
52
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
|
|
53
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
|
|
54
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
|
|
@@ -59,7 +72,9 @@ Make mistakes safe. Undo, a practice round, and results that point at the decisi
|
|
|
59
72
|
|
|
60
73
|
The debrief is where the experience becomes lasting learning, so design it from the start rather than adding it at the end:
|
|
61
74
|
|
|
62
|
-
- **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
|
|
63
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
|
|
64
79
|
- **Look back**: a team can [review a past round](../recipes/review-a-past-day.md) to see the moment a decision went wrong
|
|
65
80
|
|
|
@@ -69,6 +84,16 @@ Lemonade Stand's guide closes its debrief on the two kinds of mistake, with ques
|
|
|
69
84
|
|
|
70
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.
|
|
71
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
|
+
|
|
72
97
|
## From design to package
|
|
73
98
|
|
|
74
99
|
| Design decision | Where it goes |
|
|
@@ -182,7 +182,7 @@ Whole-game tests that play several days in-process with `createTestSession`: no
|
|
|
182
182
|
|
|
183
183
|
### `testing/e2e/`
|
|
184
184
|
|
|
185
|
-
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).
|
|
186
186
|
|
|
187
187
|
The unit and component tests sit beside the code they test (`*.test.ts`, `*.test.tsx`) and run with `pnpm test:run`.
|
|
188
188
|
|
|
@@ -195,7 +195,7 @@ These are written by `new package` for every package, starter game or not:
|
|
|
195
195
|
| `package.json` | Dependencies, and the scripts: `sdk`, `generate`, `build`, `test:run`, `test:engine`, `test:e2e`, `typecheck`, `lint` |
|
|
196
196
|
| `tsconfig.json`, `globals.d.ts` | TypeScript settings, and declarations for the font imports |
|
|
197
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 |
|
|
198
|
-
| `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 |
|
|
199
199
|
| `pnpm-workspace.yaml` | Dependency overrides and install-script decisions the SDK tooling needs |
|
|
200
200
|
| `.oxlintrc.json`, `.oxfmtrc.json` | Lint and format settings |
|
|
201
201
|
| `README.md`, `DESIGN.md` | A readme, and prompts for writing down your game's design as you build it |
|
|
@@ -518,7 +518,7 @@ Unit and integration tests cover logic and components in isolation. Browser E2E
|
|
|
518
518
|
The SDK provides selectors and helpers via a dedicated subpath export with no Playwright dependency of its own:
|
|
519
519
|
|
|
520
520
|
```typescript
|
|
521
|
-
import { expect, test } from '@playwright
|
|
521
|
+
import { expect, test } from '@seriousgaming/sdk-tools/playwright';
|
|
522
522
|
import { DEV_SERVER, reinitialiseSession } from '@seriousgaming/sdk/e2e';
|
|
523
523
|
|
|
524
524
|
test.beforeEach(async () => {
|
|
@@ -545,38 +545,53 @@ makes the 'Try again' path your UI offers reachable. `waitForState` waits for
|
|
|
545
545
|
something that happens after its command answers, and `advanceClock` moves the
|
|
546
546
|
time of a server started with a `FakeClock` on, so automatic ticks are tested without waiting.
|
|
547
547
|
|
|
548
|
-
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.
|
|
549
549
|
|
|
550
550
|
### A dev server for browser tests
|
|
551
551
|
|
|
552
|
-
|
|
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:
|
|
553
553
|
|
|
554
554
|
- It takes free ports, so it starts beside your own dev server rather than asking you to stop it
|
|
555
555
|
- It writes no lock file, so `sdk tick` in your terminal still reaches your own server
|
|
556
556
|
- It reads configuration from the package alone, ignoring what you last ran `sdk configure` with
|
|
557
|
-
- 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`.
|
|
558
560
|
|
|
559
561
|
```typescript
|
|
560
|
-
//
|
|
561
|
-
import {
|
|
562
|
+
// playwright.config.ts, as the scaffold writes it
|
|
563
|
+
import { defineConfig } from '@playwright/test';
|
|
562
564
|
|
|
563
|
-
|
|
564
|
-
|
|
565
|
+
export default defineConfig({
|
|
566
|
+
testDir: './testing/e2e',
|
|
567
|
+
globalSetup: './testing/e2e/global-setup.ts',
|
|
568
|
+
fullyParallel: true,
|
|
569
|
+
});
|
|
570
|
+
```
|
|
565
571
|
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
});
|
|
570
|
-
process.env.SERIOUSGAMING_DEV_URL = server.url;
|
|
571
|
-
return () => server.stop();
|
|
572
|
-
}
|
|
572
|
+
```typescript
|
|
573
|
+
// testing/e2e/global-setup.ts
|
|
574
|
+
export { globalSetup as default } from '@seriousgaming/sdk-tools/playwright';
|
|
573
575
|
```
|
|
574
576
|
|
|
575
|
-
|
|
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.
|
|
576
591
|
|
|
577
|
-
|
|
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.
|
|
578
593
|
|
|
579
|
-
|
|
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.
|
|
580
595
|
|
|
581
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.
|
|
582
597
|
|
package/dist/docs/page-index.md
CHANGED
|
@@ -24,11 +24,11 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
|
|
|
24
24
|
- [`ai-agents.md`](ai-agents.md), about 5k characters: An AI coding agent can build, check, and play a serious game with this SDK from the terminal alone, with no browser and no prompt to answer.
|
|
25
25
|
- [`changelog-0.x.md`](changelog-0.x.md): Every release before 1.0, from 0.0.1 to 0.6.0, kept as history.
|
|
26
26
|
- [`changelog.md`](changelog.md): All notable changes to the Serious Gaming SDK are recorded here.
|
|
27
|
-
- [`cli-and-dev-server.md`](cli-and-dev-server.md), about
|
|
27
|
+
- [`cli-and-dev-server.md`](cli-and-dev-server.md), about 15k characters: The dev server runs your game on your own machine, with every screen in the browser, and the CLI plays and inspects the same session from the terminal.
|
|
28
28
|
- [`cli-error-codes.md`](cli-error-codes.md), about 31k characters: Every code a failed `seriousgaming-sdk` command can report.
|
|
29
|
-
- [`cli-reference.md`](cli-reference.md), about
|
|
29
|
+
- [`cli-reference.md`](cli-reference.md), about 161k characters: Every `seriousgaming-sdk` command and flag, in one place.
|
|
30
30
|
- [`cli-simulation-testing.md`](cli-simulation-testing.md), about 11k characters: Play a game from the terminal: configure it, start a session, make decisions, advance ticks, and read the state back as JSON.
|
|
31
|
-
- [`environment-variables.md`](environment-variables.md), about
|
|
31
|
+
- [`environment-variables.md`](environment-variables.md), about 10k characters: A single reference for every environment variable the dev server and CLI read.
|
|
32
32
|
- [`getting-started.md`](getting-started.md), about 11k characters: Scaffold the starter game, play it in the dev server, change one thing, and see the change.
|
|
33
33
|
- [`troubleshooting.md`](troubleshooting.md), about 34k characters: Find the symptom you are seeing, then read its cause and fix.
|
|
34
34
|
|
|
@@ -42,7 +42,7 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
|
|
|
42
42
|
- [`guides/index.md`](guides/index.md), about 5k characters: Each guide is the one page for a resource kind or a topic: it explains the model, then serves as the reference, with every field, every option, and the rules behind them.
|
|
43
43
|
- [`guides/ai-facilitation.md`](guides/ai-facilitation.md), about 14k characters: A facilitator running your game may have an AI agent beside them: something they can ask 'how is Team B doing', 'why has their profit fallen', or 'set their unit price to 3.53'.
|
|
44
44
|
- [`guides/capabilities.md`](guides/capabilities.md), about 20k characters: Capabilities hold your game's state: named groups of variables that the engine and screens read and write.
|
|
45
|
-
- [`guides/designing-a-game.md`](guides/designing-a-game.md), about
|
|
45
|
+
- [`guides/designing-a-game.md`](guides/designing-a-game.md), about 13k characters: A serious game teaches by letting people act and then see what their actions caused.
|
|
46
46
|
- [`guides/designing-screens.md`](guides/designing-screens.md), about 12k characters: What a good simulation screen looks like, whatever the brand: how to decide what a screen should be before you build it, and how to check it afterwards.
|
|
47
47
|
- [`guides/endpoints.md`](guides/endpoints.md), about 29k characters: An endpoint is a named, server-side handler that a caller invokes by identifier: one of the game's own user interfaces, or a caller outside the game, such as a facilitator's AI agent or a platform API, when the endpoint allows it.
|
|
48
48
|
- [`guides/engine-testing.md`](guides/engine-testing.md), about 28k characters: Test your whole game in-process: no dev server, no browser, and no LLM API key required, because service callbacks are stubbed by default.
|
|
@@ -67,7 +67,7 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
|
|
|
67
67
|
- [`guides/setup.md`](guides/setup.md), about 9k characters: The `setup` slot holds the small form a facilitator fills in when they create a session.
|
|
68
68
|
- [`guides/speech-generation.md`](guides/speech-generation.md), about 10k characters: Give characters and briefings a voice: generate speech from server-side logic and play it in any UI.
|
|
69
69
|
- [`guides/starter-game.md`](guides/starter-game.md), about 18k characters: `new package` hands you Lemonade Stand, a complete game rather than an empty shell.
|
|
70
|
-
- [`guides/testing.md`](guides/testing.md), about
|
|
70
|
+
- [`guides/testing.md`](guides/testing.md), about 34k characters: Test your engine's logic and your user interfaces, so a broken rule or a broken screen fails on your machine rather than in front of a room.
|
|
71
71
|
- [`guides/theming-and-branding.md`](guides/theming-and-branding.md), about 11k characters: Dress every surface of your game in the host's colours, logo and fonts, so a game run by a white-label host looks like that host's product.
|
|
72
72
|
- [`guides/tick-controller.md`](guides/tick-controller.md), about 30k characters: A tick controller makes ticks happen on their own, on a schedule your logic decides, and can say when the game is finished.
|
|
73
73
|
- [`guides/type-safety.md`](guides/type-safety.md), about 16k characters: The SDK generates TypeScript types from your schemas, so a misspelt variable fails when you build rather than in front of a room.
|
|
@@ -107,7 +107,7 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
|
|
|
107
107
|
- [`recipes/declare-api-uses.md`](recipes/declare-api-uses.md), about 4k characters: A logic-bearing resource (engine, hook, tick controller, endpoint) must declare the runtime callbacks it intends to call.
|
|
108
108
|
- [`recipes/design-state-for-concurrent-writes.md`](recipes/design-state-for-concurrent-writes.md), about 6k characters: Shape capabilities and `setData` calls so that several participants writing at once never overwrite each other.
|
|
109
109
|
- [`recipes/distribute-package.md`](recipes/distribute-package.md), about 3k characters: Wrap a built `dist/` directory into a single zip archive that a production runtime can ingest as an upload.
|
|
110
|
-
- [`recipes/e2e-testing.md`](recipes/e2e-testing.md), about
|
|
110
|
+
- [`recipes/e2e-testing.md`](recipes/e2e-testing.md), about 6k characters: Test your game's screens in a real browser against an isolated dev server.
|
|
111
111
|
- [`recipes/end-game-on-condition.md`](recipes/end-game-on-condition.md), about 5k characters: Stop a game automatically when a goal is reached, rather than after a fixed number of ticks.
|
|
112
112
|
- [`recipes/fix-duplicate-packages.md`](recipes/fix-duplicate-packages.md), about 4k characters: Resolve 'Invalid hook call' and similar errors caused by multiple copies of the same package being loaded by the dev server.
|
|
113
113
|
- [`recipes/make-a-guide-follow-the-scenario.md`](recipes/make-a-guide-follow-the-scenario.md), about 5k characters: Show the session's settings in the facilitator guide, and show content only to the scenarios that need it.
|
|
@@ -133,13 +133,14 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
|
|
|
133
133
|
|
|
134
134
|
## API reference
|
|
135
135
|
|
|
136
|
-
- [`api/index.md`](api/index.md), about
|
|
136
|
+
- [`api/index.md`](api/index.md), about 8k characters: Every type, function, hook and component your game imports, one page per entry point.
|
|
137
137
|
- [`api/deck.md`](api/deck.md), about 8k characters: Every export of `@seriousgaming/deck`, with the declaration it is published with.
|
|
138
138
|
- [`api/sdk-commands.md`](api/sdk-commands.md), about 7k characters: What a client may ask a session to do.
|
|
139
139
|
- [`api/sdk-e2e.md`](api/sdk-e2e.md), about 11k characters: End-to-end testing helpers for Serious Gaming SDK consumers.
|
|
140
140
|
- [`api/sdk-projection.md`](api/sdk-projection.md), about 5k characters: The one documented shape of a session's observable state.
|
|
141
141
|
- [`api/sdk-testing.md`](api/sdk-testing.md), about 7k characters: Helpers for unit-testing a game's logic without a runtime.
|
|
142
142
|
- [`api/sdk-tools-client.md`](api/sdk-tools-client.md), about 14k characters: Programmatic API for testing a game in-process.
|
|
143
|
+
- [`api/sdk-tools-playwright.md`](api/sdk-tools-playwright.md), about 3k characters: Playwright for a game's browser tests: a dev server for each worker.
|
|
143
144
|
- [`api/sdk-ui-testing.md`](api/sdk-ui-testing.md), about 8k characters: Every export of `@seriousgaming/sdk/ui/testing`, with the declaration it is published with.
|
|
144
145
|
- [`api/sdk-ui.md`](api/sdk-ui.md), about 35k characters: Every export of `@seriousgaming/sdk/ui`, with the declaration it is published with.
|
|
145
146
|
- [`api/sdk.md`](api/sdk.md), about 58k characters: Every export of `@seriousgaming/sdk`, with the declaration it is published with.
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Test your game's screens in a real browser against an isolated dev server.
|
|
4
4
|
|
|
5
|
-
**Keywords:** e2e, playwright, browser test, integration test, UI test, iframe, reinitialiseSession, resetSession, runCommand, waitForState, advanceClock, armFault, startDevServer
|
|
5
|
+
**Keywords:** e2e, playwright, browser test, integration test, UI test, iframe, reinitialiseSession, resetSession, runCommand, waitForState, advanceClock, armFault, startDevServer, fullyParallel, workers, buildSurfaces
|
|
6
6
|
|
|
7
7
|
## Prerequisites
|
|
8
8
|
|
|
@@ -20,21 +20,10 @@ Test your game's screens in a real browser against an isolated dev server.
|
|
|
20
20
|
|
|
21
21
|
`--only-shell` installs only the headless shell, which is all a headless run needs. `--headed`, `--debug` and `--ui` open a real browser window, so to use them run the command again without the flag to install full Chromium.
|
|
22
22
|
|
|
23
|
-
2. Create `testing/e2e/global-setup.ts`, which
|
|
23
|
+
2. Create `testing/e2e/global-setup.ts`, which builds your surfaces once for the whole run and removes the build when it ends:
|
|
24
24
|
|
|
25
25
|
```typescript
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
import { startDevServer } from '@seriousgaming/sdk-tools/client';
|
|
29
|
-
import type { FullConfig } from '@playwright/test';
|
|
30
|
-
|
|
31
|
-
export default async function globalSetup(config: FullConfig): Promise<() => Promise<void>> {
|
|
32
|
-
const server = await startDevServer({
|
|
33
|
-
packagePath: config.configFile ? dirname(config.configFile) : process.cwd(),
|
|
34
|
-
});
|
|
35
|
-
process.env.SERIOUSGAMING_DEV_URL = server.url;
|
|
36
|
-
return () => server.stop();
|
|
37
|
-
}
|
|
26
|
+
export { globalSetup as default } from '@seriousgaming/sdk-tools/playwright';
|
|
38
27
|
```
|
|
39
28
|
|
|
40
29
|
3. Create `playwright.config.ts`, and add `"test:e2e": "playwright test"` to `package.json`:
|
|
@@ -45,17 +34,16 @@ Test your game's screens in a real browser against an isolated dev server.
|
|
|
45
34
|
export default defineConfig({
|
|
46
35
|
testDir: './testing/e2e',
|
|
47
36
|
globalSetup: './testing/e2e/global-setup.ts',
|
|
48
|
-
|
|
49
|
-
use: { baseURL: process.env.SERIOUSGAMING_DEV_URL },
|
|
37
|
+
fullyParallel: true,
|
|
50
38
|
});
|
|
51
39
|
```
|
|
52
40
|
|
|
53
|
-
|
|
41
|
+
Each Playwright worker starts its own isolated dev server, on free ports, and serves the surfaces the global setup built. Tests in different workers never share a session, so they run side by side. Do not start the server with `webServer` running `pnpm run sdk dev`: Playwright cannot stop it through `pnpm`, and the run hangs.
|
|
54
42
|
|
|
55
43
|
4. Start each test from a fresh session, and open a surface with `?bare` so the page holds your game and none of the console:
|
|
56
44
|
|
|
57
45
|
```typescript
|
|
58
|
-
import { expect, test } from '@playwright
|
|
46
|
+
import { expect, test } from '@seriousgaming/sdk-tools/playwright';
|
|
59
47
|
import { DEV_SERVER, reinitialiseSession } from '@seriousgaming/sdk/e2e';
|
|
60
48
|
|
|
61
49
|
test.beforeEach(async () => {
|
|
@@ -70,6 +58,8 @@ Test your game's screens in a real browser against an isolated dev server.
|
|
|
70
58
|
});
|
|
71
59
|
```
|
|
72
60
|
|
|
61
|
+
Import `test` from `@seriousgaming/sdk-tools/playwright`, not `@playwright/test`: it is what starts the worker's server and points `baseURL` and the `/e2e` helpers at it. Tests that land in the same worker share its session one after another, so `reinitialiseSession()` is still needed.
|
|
62
|
+
|
|
73
63
|
`playerUrl(team, participant?)` is 1-based. `observeUrl`, `waitingRoomUrl`, `setupUrl`, and the other builders are in the [e2e API reference](../api/sdk-e2e.md#dev_server).
|
|
74
64
|
|
|
75
65
|
5. Act through the game's own controls, or as the facilitator with `runCommand`, and read the result with `getState`:
|
|
@@ -91,7 +81,15 @@ Test your game's screens in a real browser against an isolated dev server.
|
|
|
91
81
|
|
|
92
82
|
The faults are `conflict`, `denied`, `llm-failure`, `hook-throw`, `endpoint-timeout`, and `tick-failure`.
|
|
93
83
|
|
|
94
|
-
7. Wait for what happens later with `waitForState`, never a sleep. For automatic ticks,
|
|
84
|
+
7. Wait for what happens later with `waitForState`, never a sleep. For automatic ticks, give the spec's servers a fake clock and move time with `advanceClock(ms)`:
|
|
85
|
+
|
|
86
|
+
```typescript
|
|
87
|
+
import { FakeClock } from '@seriousgaming/sdk-tools/client';
|
|
88
|
+
|
|
89
|
+
test.use({ devServerOptions: { clock: new FakeClock(Date.now()) } });
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
`devServerOptions` takes what `startDevServer` does (`teams`, `participants`, `scenarioId`, `locale`, `callbacks`), for every server the file's workers start
|
|
95
93
|
|
|
96
94
|
## Verify
|
|
97
95
|
|
|
@@ -105,7 +103,8 @@ Every spec passes. Add `--headed` to watch, or `--debug` to step through.
|
|
|
105
103
|
|
|
106
104
|
| Problem | Solution |
|
|
107
105
|
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
108
|
-
| The run hangs after the last test | The server was started with `webServer`;
|
|
106
|
+
| The run hangs after the last test | The server was started with `webServer`; use the `test` from `@seriousgaming/sdk-tools/playwright` instead (step 4) |
|
|
107
|
+
| A change to a surface does not show | The run serves the build its global setup made at the start; run the suite again |
|
|
109
108
|
| Tests pass alone and fail in a suite | Call `reinitialiseSession()` in `beforeEach`; `resetSession()` keeps teams an earlier test added |
|
|
110
109
|
| Iframe content is not there yet | Wait on a locator inside the frame (`await frame.locator('#x').waitFor()`) |
|
|
111
110
|
| The `/e2e` import does not resolve | Set `moduleResolution` to `"bundler"` or `"nodenext"` in `tsconfig.json` |
|