@seriousgaming/sdk-tools 1.5.0 → 1.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/agent/guidance.md +350 -0
- package/dist/bundling/ui-bundler.d.ts +12 -0
- package/dist/cli-25RWY5BQ.js +41 -0
- package/dist/cli-2BH7FX27.js +52 -0
- package/dist/cli-2GZYGRVL.js +36 -0
- package/dist/cli-2NU2LPEE.js +97 -0
- package/dist/cli-3BRC32CP.js +132 -0
- package/dist/cli-3D3ZXWOV.js +111 -0
- package/dist/cli-3ZKWV3PN.js +96 -0
- package/dist/cli-45OCBG53.js +60 -0
- package/dist/cli-4LKXZQ2B.js +48 -0
- package/dist/cli-4PXNOJQX.js +81 -0
- package/dist/cli-4SIWLHQO.js +717 -0
- package/dist/cli-4UWFQNGF.js +54 -0
- package/dist/cli-4VFZHLDG.js +202 -0
- package/dist/cli-4YB3ROVR.js +78 -0
- package/dist/cli-5ACDPCXI.js +21 -0
- package/dist/cli-5IAW3LIF.js +38 -0
- package/dist/cli-5SM367K7.js +30 -0
- package/dist/cli-64AB62PM.js +25 -0
- package/dist/cli-6K3VQQUS.js +307 -0
- package/dist/cli-6QB2VFPY.js +80 -0
- package/dist/cli-6SGCYEEC.js +649 -0
- package/dist/cli-6UTPHWRQ.js +207 -0
- package/dist/cli-6VNKQ3OX.js +391 -0
- package/dist/cli-72XDEFU3.js +61 -0
- package/dist/cli-7A6MKCUJ.js +463 -0
- package/dist/cli-7XLHO2FE.js +226 -0
- package/dist/cli-AV2FYC5G.js +225 -0
- package/dist/cli-B6YHEKIJ.js +248 -0
- package/dist/cli-BJMS3VX3.js +1837 -0
- package/dist/cli-BUQI5UU4.js +43 -0
- package/dist/cli-BWX5E7TQ.js +23 -0
- package/dist/cli-BYCHKSSH.js +1331 -0
- package/dist/cli-C3CMJSNL.js +89 -0
- package/dist/cli-C47GJATR.js +42 -0
- package/dist/cli-C5QOJJWX.js +46 -0
- package/dist/cli-C6ZLPK2U.js +124 -0
- package/dist/cli-CD5CIJZI.js +72 -0
- package/dist/cli-DDJYUKQG.js +36 -0
- package/dist/cli-DFBTZEBX.js +167 -0
- package/dist/cli-DOXRQ3S5.js +60 -0
- package/dist/cli-EVI36HEM.js +79 -0
- package/dist/cli-F2D4GGUA.js +549 -0
- package/dist/cli-FQRVFGN6.js +0 -0
- package/dist/cli-FWFRKQNE.js +11 -0
- package/dist/cli-G6CANSPL.js +88 -0
- package/dist/cli-GFNDW2DL.js +124 -0
- package/dist/cli-HCRTYQQS.js +16 -0
- package/dist/cli-HFX3YPUL.js +76 -0
- package/dist/cli-HKORECAG.js +53 -0
- package/dist/cli-HOE3WLFH.js +73 -0
- package/dist/cli-HSIHDN6K.js +187 -0
- package/dist/cli-HW53ICZC.js +89 -0
- package/dist/cli-IDVUHGKG.js +218 -0
- package/dist/cli-IEMKI7J7.js +1387 -0
- package/dist/cli-ILFDANBR.js +101 -0
- package/dist/cli-ILKCQNM6.js +8 -0
- package/dist/cli-IP4RXGHM.js +2847 -0
- package/dist/cli-IUS2YCD3.js +31 -0
- package/dist/cli-J4DKUUTK.js +138 -0
- package/dist/cli-J4UBELKF.js +37 -0
- package/dist/cli-JJSWBW4H.js +89 -0
- package/dist/cli-JVI24FI6.js +68 -0
- package/dist/cli-JZCLIT3O.js +135 -0
- package/dist/cli-JZOZOEZM.js +131 -0
- package/dist/cli-KGM6RRQW.js +185 -0
- package/dist/cli-KGT5L7VZ.js +13641 -0
- package/dist/cli-KOGRWFN7.js +89 -0
- package/dist/cli-KSGB2ZLK.js +101 -0
- package/dist/cli-L7VYSXQK.js +243 -0
- package/dist/cli-LK3V4RI5.js +36 -0
- package/dist/cli-LQOHATY2.js +126 -0
- package/dist/cli-MJUYJIEP.js +13 -0
- package/dist/cli-MJV47HKI.js +143 -0
- package/dist/cli-MMN4BPO4.js +145 -0
- package/dist/cli-MOPSZ3CS.js +88 -0
- package/dist/cli-MU5LB43S.js +136 -0
- package/dist/cli-MYJGMA6U.js +40 -0
- package/dist/cli-N24OHSAN.js +36 -0
- package/dist/cli-N45DREM4.js +99 -0
- package/dist/cli-N6H6T2E2.js +616 -0
- package/dist/cli-NROTDF5Y.js +182 -0
- package/dist/cli-O5ABH2WK.js +226 -0
- package/dist/cli-OMWC75CC.js +256 -0
- package/dist/cli-OXAUOWCN.js +50 -0
- package/dist/cli-PGCIHPU7.js +143 -0
- package/dist/cli-Q6ZBZYK2.js +35 -0
- package/dist/cli-QUNIRH7A.js +57 -0
- package/dist/cli-QUSCIUOM.js +142 -0
- package/dist/cli-QVASWX2A.js +187 -0
- package/dist/cli-QWQMPCL6.js +253 -0
- package/dist/cli-QY5NZAR7.js +97 -0
- package/dist/cli-R2MUZQE2.js +62 -0
- package/dist/cli-RCIWBCXD.js +36 -0
- package/dist/cli-RLEGRWFM.js +81 -0
- package/dist/cli-RSW6EBBD.js +89 -0
- package/dist/cli-RZITKPJX.js +367 -0
- package/dist/cli-S5IVGDDD.js +32 -0
- package/dist/cli-SRHBXZCN.js +159 -0
- package/dist/cli-TDSQSCX4.js +131 -0
- package/dist/cli-TIDQ4WUE.js +257 -0
- package/dist/cli-TT36JCU5.js +370 -0
- package/dist/cli-TTKICM5P.js +100 -0
- package/dist/cli-TTMBBEJC.js +131 -0
- package/dist/cli-UMEBPAZQ.js +16 -0
- package/dist/cli-UNAJ2OTE.js +15 -0
- package/dist/cli-UZZFNXRX.js +226 -0
- package/dist/cli-VDBW23SS.js +81 -0
- package/dist/cli-VL2P354N.js +46 -0
- package/dist/cli-VPRRICZA.js +304 -0
- package/dist/cli-VQ6HVQW4.js +4010 -0
- package/dist/cli-WR3NOY74.js +36 -0
- package/dist/cli-WU43JT4T.js +52 -0
- package/dist/cli-XAT25PRU.js +117 -0
- package/dist/cli-XOTNXEJA.js +124 -0
- package/dist/cli-XSLNH5PR.js +6417 -0
- package/dist/cli-XSVGKI3R.js +39 -0
- package/dist/cli-XZCJIKIV.js +124 -0
- package/dist/cli-Y3DDNMPX.js +97 -0
- package/dist/cli-Y3O5F4JN.js +90 -0
- package/dist/cli-YOTGR3NB.js +82 -0
- package/dist/cli-Z56ZIVA6.js +97 -0
- package/dist/cli-ZBN5KAIB.js +59 -0
- package/dist/cli-ZDOTXEKL.js +31 -0
- package/dist/cli-ZDUADFBY.js +88 -0
- package/dist/cli-ZJFQ7EEA.js +131 -0
- package/dist/cli-ZTWOE3ZT.js +65 -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/ai-agents.md +1 -1
- 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 +34 -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/getting-started.md +1 -1
- package/dist/docs/guides/designing-a-game.md +29 -4
- package/dist/docs/guides/starter-game.md +3 -3
- package/dist/docs/guides/testing.md +33 -18
- package/dist/docs/guides/upgrading.md +19 -2
- package/dist/docs/page-index.md +10 -9
- package/dist/docs/recipes/e2e-testing.md +19 -20
- package/dist/playwright.js +32232 -0
- package/dist/templates/package/CLAUDE.md.template +7 -346
- package/dist/templates/package/claude/rules/workflow-create-engine.md +2 -2
- package/dist/templates/package/claude/rules/workflow-create-guide.md +2 -2
- 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/claude/rules/workflow-update-sdk-version.md +3 -3
- 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
|
@@ -138,6 +138,23 @@ around it. It does not check that page's origin, so any page that frames the
|
|
|
138
138
|
console can change its scheme: harmless for a colour scheme, and the reason the
|
|
139
139
|
message carries nothing else.
|
|
140
140
|
|
|
141
|
+
### Hide the error overlay
|
|
142
|
+
|
|
143
|
+
When a surface fails to build, Vite draws a full-screen error overlay over it.
|
|
144
|
+
In a preview watched by people who are not developers, that reads as the game
|
|
145
|
+
being broken, and it is often a passing state: part way through an edit, one
|
|
146
|
+
file can import another that is not written yet. Turn the overlay off:
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
pnpm run sdk dev --no-error-overlay
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Or set `SERIOUSGAMING_DEV_ERROR_OVERLAY=false`, which also reaches a server a
|
|
153
|
+
command starts in the background. The error still appears in the server's log
|
|
154
|
+
and the browser console, and `sdk screenshot` still reports the failure with the
|
|
155
|
+
page's other problems. Without either, the package's own Vite config decides, and
|
|
156
|
+
Vite shows the overlay by default.
|
|
157
|
+
|
|
141
158
|
## How a command finds the session
|
|
142
159
|
|
|
143
160
|
`.seriousgaming-sdk/session.json` is a **lock file**, not state:
|
|
@@ -182,6 +199,10 @@ the thing to know before a test fixture calls a session command: whatever runs
|
|
|
182
199
|
first starts the session, and in Vitest a `describe` body runs at collection
|
|
183
200
|
time, before any `beforeAll`.
|
|
184
201
|
|
|
202
|
+
It runs until `sdk dev stop`, or until its package directory is removed: a
|
|
203
|
+
background server whose package has gone stops itself within a second or so,
|
|
204
|
+
so deleting a scratch game, or a test's temporary copy, leaves nothing running.
|
|
205
|
+
|
|
185
206
|
A server started this way has no flag to take a port from, so it reads
|
|
186
207
|
`SERIOUSGAMING_DEV_PORT` (from the environment or `.env`), and falls back to 3000. Either way it steps up to the first free port from there.
|
|
187
208
|
|
|
@@ -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 |
|
|
@@ -146,7 +146,7 @@ pnpm test:engine
|
|
|
146
146
|
|
|
147
147
|
## Working with an AI coding agent
|
|
148
148
|
|
|
149
|
-
A scaffolded package includes a `CLAUDE.md` and `.claude/rules/` written for coding agents. They cover the workflows an agent needs (creating resources, testing, publishing) and tell the agent to leave `sdk dev` for you to start. The points worth knowing:
|
|
149
|
+
A scaffolded package includes a `CLAUDE.md` and `.claude/rules/` written for coding agents. `CLAUDE.md` imports the SDK's guidance from the installed `@seriousgaming/sdk-tools`, so it stays current as you upgrade, and leaves the rest of the file for you to describe your game. They cover the workflows an agent needs (creating resources, testing, publishing) and tell the agent to leave `sdk dev` for you to start. The points worth knowing:
|
|
150
150
|
|
|
151
151
|
- Session commands print JSON, so an agent can read state with `view` and make decisions with `tick --patch`
|
|
152
152
|
- Use `pnpm run --silent` when parsing output, so pnpm's banner stays out of the JSON
|
|
@@ -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,11 +195,11 @@ 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 |
|
|
202
|
-
| `CLAUDE.md`, `.claude/` | Guidance and permissions for an AI coding agent
|
|
202
|
+
| `CLAUDE.md`, `.claude/` | Guidance and permissions for an AI coding agent. `CLAUDE.md` imports the SDK's guidance, then leaves a section to describe your game |
|
|
203
203
|
| `.gitignore` | Keeps `dist/`, `node_modules/`, `.seriousgaming-sdk/`, and Playwright's `test-results/` and `playwright-report/` out of version control |
|
|
204
204
|
|
|
205
205
|
Two directories appear once you use the package. `dist/` is what `sdk build` writes. `.seriousgaming-sdk/` holds the dev server's lock file (`session.json`) and the session overrides `sdk configure` writes (`configuration.json`); the session itself lives only in the dev server's memory.
|
|
@@ -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
|
|
|
@@ -634,7 +634,7 @@ Optional, but each item fixes a trap. A package created by `sdk new package` at
|
|
|
634
634
|
- **Playwright's output stays out of git.** Merge `gitignore.template` into `.gitignore`: it ignores `test-results/` and `playwright-report/`
|
|
635
635
|
- **A stray `test.only` fails CI.** `playwright.config.ts.liquid` sets `forbidOnly` when `CI` is set, so one focused test no longer skips every other test. Merge it into `playwright.config.ts` if you did not replace that file above
|
|
636
636
|
- **The wrappers set `lang` and `dir`.** Delete the lines in each `main.tsx` that set them on the document
|
|
637
|
-
- **A
|
|
637
|
+
- **A current `CLAUDE.md` and refreshed rules.** Replace the SDK's text in `CLAUDE.md` with the import described in [Optional: import the SDK's agent guidance](#optional-import-the-sdks-agent-guidance-in-claudemd), and merge in the new `claude/rules/` if you have not customised them heavily, as `workflow-update-sdk-version.md` describes
|
|
638
638
|
- **Refreshed dependencies.** Merge the versions in `package.json.liquid`, and after the Playwright bump run `pnpm exec playwright install chromium --only-shell` (drop `--only-shell` if you run tests with `--headed` or `--ui`)
|
|
639
639
|
|
|
640
640
|
Nothing breaks if you skip the new features 1.0 adds, but several replace workarounds games carry: the engine's private `state` and `complete: true` (see [Engine](./engine.md#keeping-memory-between-ticks) and [Game completion](./tick-controller.md#game-completion)), capabilities with `"lifetime": "session"` that undo and reset leave alone ([Lifetime](./capabilities.md#lifetime)), a facilitator's slide deck in the `presentation/` slot ([Building presentations](./presentation.md)), endpoints that act on the session or take files ([Endpoints](./endpoints.md)), and the `useAsset`, `usePastState` and `useViewerStorage` hooks ([User interfaces](./ui.md)).
|
|
@@ -667,7 +667,7 @@ pnpm run test:e2e
|
|
|
667
667
|
|
|
668
668
|
## After 1.0
|
|
669
669
|
|
|
670
|
-
A minor release that changes a public type a test may build by hand lists it here as well as in the [changelog](../changelog.md).
|
|
670
|
+
A minor release that changes a public type a test may build by hand lists it here as well as in the [changelog](../changelog.md), and so does an optional step that keeps an older package's scaffold current.
|
|
671
671
|
|
|
672
672
|
### 1.2: give `Brand.icon` a variant for each background
|
|
673
673
|
|
|
@@ -684,6 +684,23 @@ renderUserInterface(<App />, { callbacks: { requestTick } });
|
|
|
684
684
|
|
|
685
685
|
These types are outside semantic versioning from 1.3, so the helpers are the way to keep up with later additions too. See [What a minor release may change](./testing.md#what-a-minor-release-may-change).
|
|
686
686
|
|
|
687
|
+
### Optional: import the SDK's agent guidance in `CLAUDE.md`
|
|
688
|
+
|
|
689
|
+
A new package's `CLAUDE.md` no longer holds a copy of the SDK's guidance. Its first line imports the copy that ships with `@seriousgaming/sdk-tools`, so the guidance always matches the installed version, and the rest of the file is the package's own. An older package keeps the copy it was scaffolded with, which goes stale with every upgrade and, in a package that began as the starter game, describes the lemonade stand after a reskin.
|
|
690
|
+
|
|
691
|
+
Nothing breaks if you skip this. To adopt it:
|
|
692
|
+
|
|
693
|
+
1. Replace the SDK's text in `CLAUDE.md` (everything copied from the old template) with the first three lines of `node_modules/@seriousgaming/sdk-tools/dist/templates/package/CLAUDE.md.template`. The first is the import:
|
|
694
|
+
|
|
695
|
+
```
|
|
696
|
+
@node_modules/@seriousgaming/sdk-tools/dist/agent/guidance.md
|
|
697
|
+
```
|
|
698
|
+
|
|
699
|
+
2. Keep anything you wrote about the game itself below them, under a heading of its own
|
|
700
|
+
3. Leave `.claude/rules/` as it is: the rules are still copied into the package and merged by hand, as `workflow-update-sdk-version.md` describes
|
|
701
|
+
|
|
702
|
+
There is no command that refreshes the file: from here on, upgrading the SDK updates the guidance.
|
|
703
|
+
|
|
687
704
|
## Before you publish
|
|
688
705
|
|
|
689
706
|
A 1.0 build is a manifest version 3 package, and the platform must accept version 3 before you publish one. Until it does, the platform refuses the upload, and a version 2 package you published from 0.6 keeps running as it is. Check with Business Simulations that the platform you publish to accepts version 3 packages, and keep publishing from 0.6 until it does.
|
package/dist/docs/page-index.md
CHANGED
|
@@ -21,14 +21,14 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
|
|
|
21
21
|
## Start here and reference
|
|
22
22
|
|
|
23
23
|
- [`index.md`](index.md), about 6k characters: The Serious Gaming SDK is for building serious games: facilitated learning experiences, such as business simulations and experiential learning, in which teams make decisions and see the consequences.
|
|
24
|
-
- [`ai-agents.md`](ai-agents.md), about
|
|
24
|
+
- [`ai-agents.md`](ai-agents.md), about 6k 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.
|
|
@@ -76,7 +76,7 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
|
|
|
76
76
|
- [`guides/ui-styling.md`](guides/ui-styling.md), about 11k characters: How a game UI handles language, theme, and screen size, and how to customise the Vite build that serves and bundles it.
|
|
77
77
|
- [`guides/ui-ticks.md`](guides/ui-ticks.md), about 15k characters: How a game UI ends a round and shows the time left: requesting a tick, awaiting a write or tick and handling a `MutationError`, and driving a countdown from the tick timer.
|
|
78
78
|
- [`guides/ui.md`](guides/ui.md), about 17k characters: The game UI is what each participant sees and plays: where they read the situation, make decisions, and see what those decisions caused.
|
|
79
|
-
- [`guides/upgrading.md`](guides/upgrading.md), about
|
|
79
|
+
- [`guides/upgrading.md`](guides/upgrading.md), about 67k characters: This guide takes a game package on 0.6 to 1.0, in 13 steps.
|
|
80
80
|
- [`guides/validators.md`](guides/validators.md), about 23k characters: A validator is a read-only gate on what a participant does: a context write before it is applied, and a request for the next tick before it runs.
|
|
81
81
|
- [`guides/waiting-room.md`](guides/waiting-room.md), about 14k characters: The waiting room is the holding screen participants see while a session is parked, and you can replace the host's stock panel with your own.
|
|
82
82
|
|
|
@@ -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.
|