@seriousgaming/sdk-tools 1.10.0 → 1.12.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/agent/guidance.md +35 -23
- package/dist/{cli-F2D4GGUA.js → cli-2BKEIIA3.js} +66 -0
- package/dist/{cli-NQSL2CIH.js → cli-2QGTDHRX.js} +21 -21
- package/dist/{cli-33MZSPPK.js → cli-2SDG3SZ7.js} +21 -21
- package/dist/{cli-CLO7HKEQ.js → cli-2VXP34R5.js} +5 -3
- package/dist/{cli-P3NUTOPK.js → cli-2W4B6PD5.js} +1 -1
- package/dist/{cli-SOO6SEIS.js → cli-2X7DKSXN.js} +28 -25
- package/dist/{cli-LNEZ6KDW.js → cli-2ZP4N7HK.js} +19 -19
- package/dist/{cli-5O7XENQY.js → cli-3GJYZH4C.js} +5 -5
- package/dist/{cli-NAZTYKZT.js → cli-3GO3M2MX.js} +30 -14
- package/dist/{cli-YZJBFKRI.js → cli-3LDLUNME.js} +17 -17
- package/dist/{cli-J42N4PJG.js → cli-3WY6L2WP.js} +31 -29
- package/dist/{cli-WG7MAOCS.js → cli-44MBABRD.js} +25 -25
- package/dist/{cli-MGZYQDCH.js → cli-4IO7MKLR.js} +20 -20
- package/dist/{cli-HNDFANQG.js → cli-4U2PY7W3.js} +1 -1
- package/dist/{cli-4JNF3O5N.js → cli-4WI4LTBI.js} +2 -2
- package/dist/{cli-OTBCA54D.js → cli-55EIGGZK.js} +1 -1
- package/dist/{cli-5TKPT3CY.js → cli-5AQV6FTL.js} +18 -18
- package/dist/{cli-KNXY43YV.js → cli-5CW7BEU7.js} +3 -3
- package/dist/{cli-5V4N4BR4.js → cli-5JUVHNZF.js} +12 -12
- package/dist/{cli-F3YJKP6D.js → cli-5KERL6HV.js} +9 -4
- package/dist/{cli-HN442ZVK.js → cli-5KSA24NQ.js} +24 -24
- package/dist/{cli-5VZBFMCK.js → cli-5PIFO3EN.js} +8 -0
- package/dist/{cli-IQBY7Z7Q.js → cli-5QN2Z43X.js} +20 -20
- package/dist/cli-5XSPAA5X.js +69 -0
- package/dist/{cli-QW7VXL2V.js → cli-62KAYGXO.js} +20 -20
- package/dist/{cli-TDLIPYKT.js → cli-6IMV5ZZU.js} +26 -26
- package/dist/{cli-UULZSQBV.js → cli-6KWCIAN2.js} +764 -66
- package/dist/{cli-2ANX6E3A.js → cli-6NWETIX5.js} +20 -20
- package/dist/{cli-EXUPHPDJ.js → cli-774W3MN5.js} +26 -26
- package/dist/cli-7BUD3VAD.js +16 -0
- package/dist/{cli-7NUFHMGE.js → cli-7KEP57S7.js} +12 -12
- package/dist/{cli-6CYAOUYT.js → cli-7OYFJMA6.js} +18 -18
- package/dist/{cli-ILHHJR2S.js → cli-7ZNEDQ3G.js} +20 -20
- package/dist/{cli-5RRPUL6V.js → cli-AFK6OUID.js} +12 -12
- package/dist/{cli-A3AJQZEN.js → cli-AIYQFWXN.js} +25 -25
- package/dist/{cli-B5DWKRZ4.js → cli-ARAAEWIQ.js} +2 -2
- package/dist/cli-AVQYV3N4.js +36 -0
- package/dist/{cli-35GV2F6R.js → cli-B54Z6CXH.js} +16 -16
- package/dist/{cli-467VRXGP.js → cli-B5TC4MEL.js} +5 -5
- package/dist/{cli-5Z4D3F6Y.js → cli-BCXGOLU3.js} +3 -3
- package/dist/{cli-G2GLW5Z4.js → cli-BHAODVTZ.js} +1 -1
- package/dist/{cli-XR3O2YTV.js → cli-BPS2JG74.js} +20 -20
- package/dist/{cli-W3RG2MRI.js → cli-BVO55SR2.js} +2 -2
- package/dist/{cli-PYAST3G5.js → cli-CFH3JZP5.js} +21 -21
- package/dist/{cli-VZVHS5AP.js → cli-CTK2OIK6.js} +20 -20
- package/dist/{cli-ATWJCB2G.js → cli-CW5MV4VX.js} +4 -4
- package/dist/{cli-TCQJL2GY.js → cli-D5VOSJZ7.js} +1 -1
- package/dist/{cli-KIZTASLL.js → cli-DAEPMK7A.js} +5 -5
- package/dist/{cli-44CM2AH2.js → cli-DAHR7PKB.js} +1 -1
- package/dist/{cli-XW3JLRSA.js → cli-DWDSBTYL.js} +1 -1
- package/dist/cli-DYSDPGXW.js +95 -0
- package/dist/{cli-GRSQRFRG.js → cli-DZCLRZXJ.js} +9 -2
- package/dist/{cli-RSF5R3HC.js → cli-EJ47IE45.js} +28 -25
- package/dist/{cli-QDBYFITU.js → cli-EK4OSJHA.js} +2 -2
- package/dist/{cli-GO64NABP.js → cli-FCJHNXDA.js} +1 -1
- package/dist/{cli-ZNQBF4Z3.js → cli-FNESSE3L.js} +1 -1
- package/dist/{cli-MUOLHQNL.js → cli-FTLH4WCE.js} +17 -17
- package/dist/{cli-JHLWBRXB.js → cli-FYV77YS2.js} +18 -18
- package/dist/cli-GMJX6Q4Q.js +36 -0
- package/dist/{cli-7JUNA74L.js → cli-GRBVNGDW.js} +1 -1
- package/dist/{cli-XKAIDYIE.js → cli-HAFCFY77.js} +33 -19
- package/dist/{cli-OXLOGXT3.js → cli-HCJLYI24.js} +3 -3
- package/dist/{cli-HHRP6FP6.js → cli-HCXS5EXU.js} +25 -25
- package/dist/cli-HEUNNHDH.js +36 -0
- package/dist/{cli-36GABN2A.js → cli-HNUTIWDZ.js} +19 -19
- package/dist/{cli-JXQLHJO2.js → cli-HXT25ETJ.js} +244 -243
- package/dist/{cli-5EH4WTH4.js → cli-IGEL7UJQ.js} +5 -5
- package/dist/{cli-JMNPMDXH.js → cli-IO32YA5N.js} +26 -26
- package/dist/cli-IPTGZDBB.js +36 -0
- package/dist/{cli-L54SXUK6.js → cli-J25TYFKB.js} +19 -19
- package/dist/{cli-CQ4ZR3ZQ.js → cli-J7XYMEMX.js} +20 -20
- package/dist/{cli-5DWR7RPQ.js → cli-JC5OJRID.js} +2 -2
- package/dist/{cli-25SJZI7N.js → cli-JD563OF4.js} +126 -27
- package/dist/{cli-JAVMRERQ.js → cli-JRJF2WHU.js} +20 -20
- package/dist/{cli-UQC46YSV.js → cli-JTFLIMIG.js} +3 -3
- package/dist/{cli-2AH6D32V.js → cli-K2BSJ2PK.js} +2 -2
- package/dist/{cli-XB5PI2XT.js → cli-K4QTYMN2.js} +25 -25
- package/dist/{cli-5SHG2M7E.js → cli-KFJDD4C4.js} +20 -20
- package/dist/{cli-WW54THXN.js → cli-KVQ2JPVD.js} +1 -1
- package/dist/{cli-O5WYATAI.js → cli-L6AHMW2Z.js} +4 -2
- package/dist/{cli-IKSLPAZN.js → cli-LCYUBCVY.js} +4 -4
- package/dist/{cli-HGCOEL5T.js → cli-LEWSCDH5.js} +4 -4
- package/dist/{cli-HNG6PZW2.js → cli-LI6G7GND.js} +27 -27
- package/dist/{cli-2AVPNSAX.js → cli-LU2GCWIU.js} +21 -21
- package/dist/{cli-UEQMK4WX.js → cli-M3Z2KOEB.js} +1 -1
- package/dist/{cli-226ZJ72R.js → cli-M6E3E3I2.js} +170 -3
- package/dist/{cli-OXU6TTEN.js → cli-MCRPA4Z6.js} +20 -20
- package/dist/{cli-BQ36DV5C.js → cli-MI2DEDMA.js} +3 -3
- package/dist/{cli-6O7YCK2M.js → cli-MITZ6SE7.js} +3 -3
- package/dist/{cli-VALLLE6Y.js → cli-MTIYD3BX.js} +26 -26
- package/dist/{cli-5M6KDNVX.js → cli-MTZUJGBK.js} +2 -2
- package/dist/{cli-GSOV26O5.js → cli-NCLMUXLC.js} +14 -14
- package/dist/{cli-Z3DITVBE.js → cli-NLS3DKWH.js} +26 -26
- package/dist/{cli-AH6AMAIB.js → cli-NMDGS7IE.js} +1 -1
- package/dist/cli-O3DJO2CS.js +30 -0
- package/dist/{cli-BC67QHD5.js → cli-O47D5BFN.js} +2 -2
- package/dist/{cli-MDVC5ZNM.js → cli-OBRZ36VP.js} +14 -14
- package/dist/{cli-267QJ2DS.js → cli-OMG4E53H.js} +20 -20
- package/dist/{cli-C32Q5E5I.js → cli-P6V3NSU4.js} +1 -1
- package/dist/{cli-PBSLPO6G.js → cli-PAMQMTHK.js} +21 -21
- package/dist/{cli-RUEPTOWG.js → cli-PKTHOCT3.js} +26 -26
- package/dist/{cli-PTXOKO2Y.js → cli-QK7QAP5H.js} +18 -18
- package/dist/cli-QQ432JEN.js +36 -0
- package/dist/{cli-YFLQ7XOO.js → cli-QVNDPTBU.js} +20 -20
- package/dist/{cli-KJA6GLZI.js → cli-R2DFD6ZZ.js} +15 -15
- package/dist/{cli-6BLVI2JM.js → cli-RMVJMOWU.js} +111 -7
- package/dist/{cli-M6AZFIMV.js → cli-RQISHMJF.js} +88 -23
- package/dist/{cli-X64BNBQH.js → cli-RVZH462G.js} +585 -8
- package/dist/{cli-LLJQI2QP.js → cli-SEEOQVUL.js} +12 -12
- package/dist/{cli-QTCTWYCM.js → cli-SO354HPI.js} +3 -3
- package/dist/{cli-URCHZDTS.js → cli-T76HDH7F.js} +90 -5
- package/dist/{cli-ZJW6HQ6N.js → cli-TIS7DWRR.js} +7 -7
- package/dist/{cli-WOFYI7HZ.js → cli-TY3B6XS7.js} +21 -21
- package/dist/{cli-4FJL3KQZ.js → cli-UKEZJFIT.js} +2 -2
- package/dist/cli-VQAMW4RF.js +95 -0
- package/dist/{cli-4A7RWFNO.js → cli-W4LMRVZT.js} +78 -47
- package/dist/cli-W7I5KGIB.js +84 -0
- package/dist/{cli-B3EFE7ZF.js → cli-WXGJFA4F.js} +1 -1
- package/dist/{cli-IPTHJT3J.js → cli-XCG33I77.js} +28 -25
- package/dist/{cli-WLSACMYA.js → cli-YHLSG5HB.js} +30 -28
- package/dist/cli-YNH5DTHY.js +36 -0
- package/dist/cli-YPMJWPDA.js +69 -0
- package/dist/{cli-PXQYY6KM.js → cli-YSXIR7EM.js} +0 -0
- package/dist/cli-ZPFWO4VW.js +85 -0
- package/dist/cli.js +53 -53
- package/dist/client/index.d.ts +1 -1
- package/dist/client/test-session.d.ts +44 -6
- package/dist/client.js +1934 -286
- package/dist/core/assessment-moves.d.ts +32 -0
- package/dist/core/assessment-reports.d.ts +38 -0
- package/dist/core/assessment-settings.d.ts +15 -0
- package/dist/core/benchmark-samples.d.ts +28 -0
- package/dist/core/session-host.d.ts +4 -0
- package/dist/core/session-roster.d.ts +6 -0
- package/dist/core/session-timers.d.ts +40 -0
- package/dist/core/session.d.ts +14 -1
- package/dist/core/tick-timer.d.ts +18 -0
- package/dist/dev/console/assets/{index-Ch6HHb2T.js → index-zd--5H1f.js} +26 -26
- package/dist/dev/console/index.html +1 -1
- package/dist/dev/shell.d.ts +8 -0
- package/dist/dev/view/commands.d.ts +3 -1
- package/dist/docs/api/index.md +4 -2
- package/dist/docs/api/sdk-commands.md +29 -0
- package/dist/docs/api/sdk-e2e.md +30 -0
- package/dist/docs/api/sdk-projection.md +5 -0
- package/dist/docs/api/sdk-tools-client.md +68 -6
- package/dist/docs/api/sdk-tools-vite.md +21 -0
- package/dist/docs/api/sdk-ui.md +7 -0
- package/dist/docs/api/sdk.md +834 -19
- package/dist/docs/changelog.md +67 -0
- package/dist/docs/cli-error-codes.md +5 -1
- package/dist/docs/cli-reference.md +76 -2
- package/dist/docs/concepts/index.md +2 -0
- package/dist/docs/concepts/terminology.md +12 -0
- package/dist/docs/guides/assessments.md +248 -0
- package/dist/docs/guides/benchmarks.md +241 -0
- package/dist/docs/guides/endpoints.md +1 -1
- package/dist/docs/guides/engine-testing.md +49 -14
- package/dist/docs/guides/engine.md +10 -2
- package/dist/docs/guides/index.md +2 -0
- package/dist/docs/guides/presentation.md +11 -9
- package/dist/docs/guides/session-hooks.md +24 -22
- package/dist/docs/guides/testing.md +3 -8
- package/dist/docs/guides/tick-controller.md +22 -1
- package/dist/docs/guides/ui.md +24 -0
- package/dist/docs/guides/upgrading.md +36 -0
- package/dist/docs/page-index.md +18 -13
- package/dist/docs/recipes/create-assessment.md +124 -0
- package/dist/docs/recipes/create-benchmark.md +115 -0
- package/dist/docs/recipes/create-game.md +1 -1
- package/dist/docs/recipes/fix-duplicate-packages.md +8 -19
- package/dist/docs/recipes/index.md +2 -0
- package/dist/execution/context-composition.d.ts +39 -4
- package/dist/execution/engine-state.d.ts +13 -0
- package/dist/execution/executor.d.ts +16 -0
- package/dist/execution/logic-result.d.ts +13 -2
- package/dist/help-examples.d.ts +12 -0
- package/dist/host/adapter.d.ts +24 -1
- package/dist/host/protocol.d.ts +115 -1
- package/dist/host.js +29 -1
- package/dist/oxlint/logic.json +184 -0
- package/dist/playwright.js +1928 -280
- package/dist/runtime/index.d.ts +3 -1
- package/dist/runtime/manifest-version.d.ts +1 -1
- package/dist/runtime.js +298 -16
- package/dist/schema.json +189 -0
- package/dist/templates/package/README.md.liquid +1 -0
- package/dist/templates/package/claude/rules/workflow-create-engine.md +1 -1
- package/dist/templates/package/claude/rules/workflow-create-user-interface.md +1 -1
- package/dist/templates/package/claude/rules/workflow-test-engine-or-ui.md +1 -1
- package/dist/templates/package/claude/rules/workflow-update-sdk-version.md +2 -2
- package/dist/templates/package/claude/settings.json.template +1 -0
- package/dist/templates/package/oxfmtrc.json.template +8 -1
- package/dist/templates/package/oxlintrc.json.template +1 -180
- package/dist/templates/package/package.json.liquid +1 -0
- package/dist/templates/package/vite.config.ts.liquid +2 -8
- package/dist/templates/package/vitest.config.ts.liquid +2 -8
- package/dist/templates/starter-game/package.json +2 -1
- package/dist/templates/starter-game/testing/engine/game.engine.test.ts +62 -37
- package/dist/templates/starter-game/vite.config.ts +2 -8
- package/dist/templates/starter-game/vitest.config.ts +4 -3
- package/dist/templating/resource-metadata.d.ts +1 -1
- package/dist/utils/error-codes.d.ts +9 -1
- package/dist/utils/resource-scan.d.ts +5 -0
- package/dist/validation/assessment-validation.d.ts +34 -0
- package/dist/validation/benchmark-validation.d.ts +20 -0
- package/dist/validation/schema-validation.d.ts +4 -0
- package/dist/vite/index.d.ts +30 -0
- package/dist/vite.js +12 -0
- package/package.json +12 -4
- package/dist/cli-27Z5T52R.js +0 -30
- package/dist/cli-5XE4OMFL.js +0 -36
- package/dist/cli-BB6CU4ZC.js +0 -36
- package/dist/cli-FGP6YYM7.js +0 -36
- package/dist/cli-I3ZAZYWP.js +0 -36
- package/dist/cli-RFAPPYXK.js +0 -36
- package/dist/cli-WZNIW6ZO.js +0 -16
- package/dist/cli-XEEOJGBL.js +0 -36
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
# Benchmarks
|
|
2
|
+
|
|
3
|
+
A benchmark lets a debrief compare a team with everyone who has played the game, not just the other teams in the room.
|
|
4
|
+
|
|
5
|
+
This guide explains what a benchmark records and who sees it, then covers declaring one, writing it from the engine, and reading the pooled figures on a screen.
|
|
6
|
+
|
|
7
|
+
**Keywords:** benchmark, benchmarks, compare with other sessions, how you compare, debrief comparison, pooled results, percentile, median, getBenchmark, sample.json, tags, filters, requires benchmarks, BENCHMARK_UNWRITTEN
|
|
8
|
+
|
|
9
|
+
## The model
|
|
10
|
+
|
|
11
|
+
A debrief can only compare a team with the other teams in its room. With one team there is nothing to compare against, and even a full room wants to know how it did against everyone who has played.
|
|
12
|
+
|
|
13
|
+
A benchmark is a small, named record of outcomes and decisions that the engine keeps for each team (or for the session). The platform pools those records anonymously across sessions of the same game, and a screen reads back statistics: a count, a median, percentiles, or how many chose each option.
|
|
14
|
+
|
|
15
|
+
- **The engine is the only writer.** It declares the benchmarks it writes, and returns writes under `benchmarks`, beside `capabilities`
|
|
16
|
+
- **Screens only read the pool.** The game UI, the waiting room UI, the session UI and the presentation call `getBenchmark`, and receive statistics, never another team's record
|
|
17
|
+
- **A team's own record stays in the session.** It is part of the team's state, so undo and reset rewind it, but no screen, hook, validator or endpoint ever receives it. A screen shows the team's own figure from its capabilities, as it always has, and puts the pooled figures beside it
|
|
18
|
+
- **The platform owns the pool.** Whose results are pooled (your organisation first, with a global pool only where it is enabled), which sessions are eligible, how many results a figure needs before it is shown, and how long records are kept are all the platform's decisions. A walkthrough is never recorded
|
|
19
|
+
|
|
20
|
+
## Declaring a benchmark
|
|
21
|
+
|
|
22
|
+
A benchmark lives at `benchmarks/<name>/benchmark.sdk.json`, named by its directory, and is created from JSON:
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
pnpm run sdk new benchmark '{
|
|
26
|
+
"definition": {
|
|
27
|
+
"identifier": "outcome",
|
|
28
|
+
"revision": 1,
|
|
29
|
+
"tags": ["difficulty"],
|
|
30
|
+
"fields": {
|
|
31
|
+
"NetProfit": { "type": "number", "description": "Profit over the whole game" },
|
|
32
|
+
"Round1Pricing": { "enum": ["premium", "match", "discount"] }
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
}'
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
This writes the bundle and a `sample.json` beside it, which the dev server answers from (see [Previewing with sample.json](#previewing-with-samplejson)). The build leaves `sample.json` out: a benchmark ships no files.
|
|
39
|
+
|
|
40
|
+
| Field | What it holds |
|
|
41
|
+
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
|
42
|
+
| `revision` | A whole number, at least 1. Results are pooled per revision |
|
|
43
|
+
| `level` | `'team'` (the default): one record per team. `'session'`: one record for the whole session, written by an aggregate engine |
|
|
44
|
+
| `tags` | Up to five names a record can be grouped by, such as a difficulty or a market |
|
|
45
|
+
| `fields` | One to 20 fields. `{ "type": "number" }` is pooled as a distribution; `{ "enum": [...] }` (one to 20 options) as a count per option |
|
|
46
|
+
|
|
47
|
+
Field and tag names start with a letter and hold letters, digits and underscores. `tags` and `excluded` are reserved: every record has them, and a benchmark cannot declare a field with either name.
|
|
48
|
+
|
|
49
|
+
Then wire it in, in two places:
|
|
50
|
+
|
|
51
|
+
1. **List it in the engine's `benchmarks`:**
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
pnpm run sdk update engine --patch '[
|
|
55
|
+
{ "op": "add", "path": "/definition/benchmarks", "value": ["outcome"] }
|
|
56
|
+
]'
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
The engine's generated `types.ts` then exports `Benchmarks`, with each record's fields typed, and `SessionBenchmarks` for session-level ones
|
|
60
|
+
|
|
61
|
+
2. **List the `benchmarks` feature in `requires`** in `seriousgaming.sdk.json`, so a runtime that cannot record benchmarks refuses the package rather than the first round that writes one:
|
|
62
|
+
|
|
63
|
+
```json
|
|
64
|
+
{
|
|
65
|
+
"requires": ["benchmarks"]
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### Choosing what to record
|
|
70
|
+
|
|
71
|
+
Record the few figures a debrief will actually show: an outcome or two, and the decisions that explain them. A benchmark is not a log of the game. Keep fields to numbers and short option lists; there is no free text, so nothing a participant typed can leave the session.
|
|
72
|
+
|
|
73
|
+
There is no 'higher is better' flag. Whether a high figure is good is for the screen to say, in its own words.
|
|
74
|
+
|
|
75
|
+
### When to change the revision
|
|
76
|
+
|
|
77
|
+
A pool carries on across releases of the game that leave the benchmark alone. Bump `revision` when a change makes earlier results no longer comparable, such as a new demand model that halves typical profits: the new revision starts a new pool, which fills as sessions on it are played.
|
|
78
|
+
|
|
79
|
+
## Writing from the engine
|
|
80
|
+
|
|
81
|
+
The engine's `Init` and `Run` receive `benchmarks` beside `context`: the team's current records, keyed by identifier, holding what the engine last wrote. A benchmark not yet written is absent. They return writes under `benchmarks`:
|
|
82
|
+
|
|
83
|
+
```typescript
|
|
84
|
+
import type { RunFunction } from '@seriousgaming/sdk';
|
|
85
|
+
|
|
86
|
+
import type { Benchmarks, Callbacks, Context, Settings } from './types';
|
|
87
|
+
|
|
88
|
+
export const Run: RunFunction<Context, Settings, Callbacks, never, Benchmarks> = async ({
|
|
89
|
+
context,
|
|
90
|
+
settings,
|
|
91
|
+
meta,
|
|
92
|
+
}) => {
|
|
93
|
+
const next = await playRound(context, settings);
|
|
94
|
+
return {
|
|
95
|
+
capabilities: next,
|
|
96
|
+
benchmarks: {
|
|
97
|
+
outcome: {
|
|
98
|
+
NetProfit: next.finance.TotalProfit,
|
|
99
|
+
tags: { difficulty: settings.setup.Difficulty },
|
|
100
|
+
...(meta.tick === 1 ? { Round1Pricing: pricingStance(next.pricing.Price) } : {}),
|
|
101
|
+
},
|
|
102
|
+
},
|
|
103
|
+
};
|
|
104
|
+
};
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
`Benchmarks` is the fifth type parameter of `RunFunction` and `InitializationFunction`, after the engine's private `state` (pass `never` when the engine keeps none). The compiler then checks every field name, every option and every tag.
|
|
108
|
+
|
|
109
|
+
A write is a patch, so a record can be filled in round by round:
|
|
110
|
+
|
|
111
|
+
- **Each field it carries replaces that field.** A field it leaves out keeps its value, which is why `Round1Pricing` above is written once and then left alone
|
|
112
|
+
- **`null` removes a field**, and `null` in place of the whole write removes the record. A record with nothing left in it is removed
|
|
113
|
+
- **`tags` replaces the record's tags whole**
|
|
114
|
+
- **Tag values are short.** One to 64 letters, digits, `:`, `.`, `_` or `-`: enough for a difficulty or a team count, too short to carry a name or a sentence out of the session
|
|
115
|
+
|
|
116
|
+
### Aggregate engines
|
|
117
|
+
|
|
118
|
+
In an aggregate engine, each `teams` entry carries its team's `benchmarks`, and `shared.benchmarks` holds the session's own records. A team-level benchmark is written in a `teams` entry (or by a per-team `Init` or `Run`), and a session-level one only under `shared`. Type them with the last two parameters of `InitAggregateFunction` and `RunAggregateFunction`, after the two state parameters: `Benchmarks`, then `SessionBenchmarks`.
|
|
119
|
+
|
|
120
|
+
### A bad write is dropped, not fatal
|
|
121
|
+
|
|
122
|
+
Every write is checked against its benchmark: each field declared, each number finite, each option and tag declared, `excluded` a boolean, and the benchmark written at its own level. A write that fails is dropped whole, the record keeps its previous value, and the round carries on. A failed round in front of a room costs far more than one missing figure.
|
|
123
|
+
|
|
124
|
+
The problem comes back as a warning: `sdk tick` prints it and adds it to `warnings` in its `--json` output, and a test session's `tick()` returns it in `warnings`. Only the shape of `benchmarks` itself is strict: an engine that declares no benchmarks and returns the key fails the call, as any unexpected key does.
|
|
125
|
+
|
|
126
|
+
## Deciding when values count
|
|
127
|
+
|
|
128
|
+
At any moment, the pool holds each team's record as the session now holds it. A later write replaces the earlier value, an undo that takes a record back takes it back in the pool too, and a removed record leaves the pool. So the game, not the platform, decides when a team's figures count:
|
|
129
|
+
|
|
130
|
+
- **Count everyone, as they go.** Write every round, as the example above does. A team counts with whatever it last reached, even in a session that stops early
|
|
131
|
+
- **Count only finished teams.** Write the outcome on the last round only, or hold `excluded: true` until then and write `excluded: null` with the final figures
|
|
132
|
+
- **Leave a team out.** `excluded: true` withdraws the record from every pool while keeping it in the session, for a run under settings too unusual to compare
|
|
133
|
+
|
|
134
|
+
## Tags and filters
|
|
135
|
+
|
|
136
|
+
Tags let a screen compare like with like: a team on a hard difficulty with others who played it hard. Declare the names in the bundle, and set a value for each on the record:
|
|
137
|
+
|
|
138
|
+
```typescript
|
|
139
|
+
tags: { difficulty: settings.setup.Difficulty, teams: String(teamCount) }
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
A screen never sees a team's own tags. It builds its filters from the settings it reads, which hold the same values, and never from the scenario's name, which differs between organisations and says nothing about how the game was set up.
|
|
143
|
+
|
|
144
|
+
## Reading benchmarks on a screen
|
|
145
|
+
|
|
146
|
+
`getBenchmark(identifier, query?)` is on `useUserInterfaceCallbacks()` (the game UI and the waiting room UI), on `useSessionUserInterfaceCallbacks()` (the session UI), and on `usePresentation()`, where it works with or without a session. It is not gated by `uses`.
|
|
147
|
+
|
|
148
|
+
```typescript
|
|
149
|
+
const stats = await getBenchmark('outcome', {
|
|
150
|
+
where: [{ difficulty: settings.setup.Difficulty }, {}],
|
|
151
|
+
});
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
- **`where`** is a filter on tag values, or a list of filters tried in order, narrowest first. The first with enough results answers. Left out, it is `{}`: everyone
|
|
155
|
+
- **`matched`** in the answer is the filter that answered, so the screen can label what it shows: 'compared with other hard games', or 'compared with everyone'
|
|
156
|
+
- **`scope`** is `'organisation'` or `'global'`: whose results were pooled, for the screen to say so
|
|
157
|
+
- **`fields`** holds an entry per field with figures to show. A numeric field is `{ kind: 'number', count, mean?, min?, max?, p10?, p25?, p50?, p75?, p90? }`; a field with options is `{ kind: 'choice', count, options }`
|
|
158
|
+
|
|
159
|
+
The types are `BenchmarkStatistics`, `NumericBenchmarkStatistics` and `ChoiceBenchmarkStatistics`, from `@seriousgaming/sdk`. See the [API reference](../api/sdk.md#benchmarkstatistics).
|
|
160
|
+
|
|
161
|
+
### Write for missing figures
|
|
162
|
+
|
|
163
|
+
The answer is often thinner than the sample. Every screen that reads a benchmark handles three cases:
|
|
164
|
+
|
|
165
|
+
- **`null`**: nothing to show. No results yet, too few for any filter, or a runtime that keeps no pool. Show the team's own figure on its own, or hide the comparison
|
|
166
|
+
- **A missing figure.** Only `count` is always present. The platform may hold back any figure until enough results back it, and `min` and `max` most of all, since each is one team's real result. An option chosen by too few may be absent from `options`. Check each figure before you show it
|
|
167
|
+
- **A missing field.** A field with nothing to show is absent from `fields`
|
|
168
|
+
|
|
169
|
+
```tsx
|
|
170
|
+
const profit = stats?.fields.NetProfit;
|
|
171
|
+
const median = profit?.kind === 'number' ? profit.p50 : undefined;
|
|
172
|
+
|
|
173
|
+
return median === undefined ? (
|
|
174
|
+
<Typography>{t('compare.notYet')}</Typography>
|
|
175
|
+
) : (
|
|
176
|
+
<Typography>{t('compare.median', { value: median })}</Typography>
|
|
177
|
+
);
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
### Results may be stale
|
|
181
|
+
|
|
182
|
+
The pool may lag behind, and may leave out the current session. Treat the figures as context for a debrief, never as a live leaderboard. The SDK's wrapper keeps an answer for a minute, so a second call with the same query in that time reuses it, and settles on `null` if the host does not answer within 10 seconds, so a debrief never hangs on it.
|
|
183
|
+
|
|
184
|
+
An identifier the package declares no benchmark for rejects, so a typo fails in your own call rather than looking like an empty pool.
|
|
185
|
+
|
|
186
|
+
## Previewing with sample.json
|
|
187
|
+
|
|
188
|
+
The dev server has no other sessions to pool, so it answers `getBenchmark` from `benchmarks/<name>/sample.json`. `new benchmark` writes one with placeholder figures for every field:
|
|
189
|
+
|
|
190
|
+
```json
|
|
191
|
+
{
|
|
192
|
+
"scope": "organisation",
|
|
193
|
+
"fields": {
|
|
194
|
+
"NetProfit": {
|
|
195
|
+
"kind": "number",
|
|
196
|
+
"count": 120,
|
|
197
|
+
"mean": 50,
|
|
198
|
+
"min": 0,
|
|
199
|
+
"max": 100,
|
|
200
|
+
"p10": 10,
|
|
201
|
+
"p25": 25,
|
|
202
|
+
"p50": 50,
|
|
203
|
+
"p75": 75,
|
|
204
|
+
"p90": 90
|
|
205
|
+
},
|
|
206
|
+
"Round1Pricing": {
|
|
207
|
+
"kind": "choice",
|
|
208
|
+
"count": 120,
|
|
209
|
+
"options": { "premium": 40, "match": 40, "discount": 40 }
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
}
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
Replace the figures with ones that look like your game. The file is read on every call, so an edit shows on the next read without a restart. It answers every query alike, with `matched` set to the first filter tried.
|
|
216
|
+
|
|
217
|
+
Use it to rehearse the thin cases too: delete `min` and `max`, or a field, to see the screen without them, and delete the file to see the `null` case. A sample that is not valid JSON, or not the right shape, makes `getBenchmark` reject, naming the file.
|
|
218
|
+
|
|
219
|
+
## Testing
|
|
220
|
+
|
|
221
|
+
- **The engine's writes.** In a unit test, assert on `result.benchmarks` from `Run`. To test a write that depends on what the engine wrote before, pass `benchmarks` beside the arguments `logicArgs.run` builds: `Run({ ...logicArgs.run({ context, settings }), benchmarks: { outcome: { NetProfit: 120 } } })`
|
|
222
|
+
- **A whole game.** In an engine test, `session.state().teams[0].benchmarks` holds each team's records, and `state().sharedBenchmarks` the session's own. Check `warnings` on what `tick()` returns, so a dropped write fails the test rather than going unnoticed
|
|
223
|
+
- **From the CLI.** `pnpm run --silent sdk view --full --json` shows the same `benchmarks` and `sharedBenchmarks`, and `sdk tick` prints a warning for each dropped write
|
|
224
|
+
- **A screen.** The render helpers in `@seriousgaming/sdk/ui/testing` supply a `getBenchmark` that answers `null`. Pass your own in `callbacks` to render the comparison: `renderUserInterface(<App />, { callbacks: { getBenchmark: async () => stats } })`
|
|
225
|
+
|
|
226
|
+
See [Engine testing](./engine-testing.md) and [Testing](./testing.md).
|
|
227
|
+
|
|
228
|
+
## Rules the build checks
|
|
229
|
+
|
|
230
|
+
- **The `benchmarks` feature in `requires`** for a game that declares any benchmark (`FEATURE_UNDECLARED`)
|
|
231
|
+
- **At most 20 benchmarks** in a game
|
|
232
|
+
- **Every name in the engine's `benchmarks` is a benchmark the package declares** (`REFERENCE_UNKNOWN`)
|
|
233
|
+
- **A session-level benchmark needs an aggregate engine**, the only kind with a session result to write it under
|
|
234
|
+
- **A benchmark the engine does not list** can never hold a value, so the build warns on it (`BENCHMARK_UNWRITTEN`)
|
|
235
|
+
|
|
236
|
+
## Next steps
|
|
237
|
+
|
|
238
|
+
- [Create a benchmark](../recipes/create-benchmark.md): the steps, start to finish
|
|
239
|
+
- [Engines](./engine.md): the result a write sits beside
|
|
240
|
+
- [Multi-team games](./multi-team-games.md): aggregate engines, which write session-level benchmarks
|
|
241
|
+
- [Building presentations](./presentation.md): a debrief deck that compares the room with everyone else
|
|
@@ -344,7 +344,7 @@ An internal endpoint's request may take any shape. Which outside callers may use
|
|
|
344
344
|
|
|
345
345
|
## When a call fails
|
|
346
346
|
|
|
347
|
-
A failed call is never a bare message, because a caller has to tell a call that changed nothing from one whose writes landed before an action failed. A UI's call rejects with an [`EndpointError`](../api/sdk-ui.md#endpointerror), `pnpm run sdk endpoint call --json` prints the same thing, and a `createTestSession` call answers `{ type: 'endpointFailure', failure }`. Each carries:
|
|
347
|
+
A failed call is never a bare message, because a caller has to tell a call that changed nothing from one whose writes landed before an action failed. A UI's call rejects with an [`EndpointError`](../api/sdk-ui.md#endpointerror), `pnpm run --silent sdk endpoint call --json` prints the same thing, and a `createTestSession` call answers `{ type: 'endpointFailure', failure }`. Each carries:
|
|
348
348
|
|
|
349
349
|
- `outcome`: why, as `outcome.kind` and usually `outcome.message`. The kinds are those of a refused write (`denied`, `conflict`, `tick-failed` and the rest) plus three only an endpoint has: `invalid-request` (the request failed `requestSchema`, so the handler did not run), `handler-error` (the handler threw or overran its time limit), and `invalid-response` (what it returned broke its declaration)
|
|
350
350
|
- `applied`: the steps that committed before the failure, in order: `{ kind: 'capabilities' }`, `{ kind: 'teams', teamId }`, or `{ kind: 'action', index, type }`. Empty when nothing changed
|
|
@@ -116,6 +116,16 @@ it('adds Delta to Total on each tick', async () => {
|
|
|
116
116
|
});
|
|
117
117
|
```
|
|
118
118
|
|
|
119
|
+
When the refusal came from logic that threw, the result also carries `logicError`: the resource whose logic it was, the message, the tick and team it ran for, and the `file`, `line` and `column` of the source, which is what `sdk tick` reports from the command line. Put it in the failure message and a failing test says where to look:
|
|
120
|
+
|
|
121
|
+
```typescript
|
|
122
|
+
const result = await session.tick();
|
|
123
|
+
if (!result.ok) {
|
|
124
|
+
const at = result.logicError;
|
|
125
|
+
throw new Error(`${result.outcome.kind} at ${at?.file}:${at?.line} (tick ${at?.tick})`);
|
|
126
|
+
}
|
|
127
|
+
```
|
|
128
|
+
|
|
119
129
|
Every helper is a command underneath, and `send` takes any command directly: `session.tick()` is `session.send({ type: 'tick' })`.
|
|
120
130
|
|
|
121
131
|
`state()` is the whole session: `session.completedTicks`, `session.complete`, every team with its `context`, `completedTicks` and `participants`, the shared store, the timer and `settings`, every settings resource's resolved values keyed by identifier.
|
|
@@ -278,6 +288,27 @@ await createTestSession({ packagePath: PACKAGE_PATH, scenarioId: null });
|
|
|
278
288
|
|
|
279
289
|
A game that marks a default scenario never runs on none, so `scenarioId: null` is refused for it, naming the default. Pin one of its scenarios instead.
|
|
280
290
|
|
|
291
|
+
### Playing every scenario
|
|
292
|
+
|
|
293
|
+
A scenario overrides settings, and a value the engine cannot work with only shows when the game is played on it. Start every scenario and play a tick, reading the list from disk so a new scenario is covered the day it is added:
|
|
294
|
+
|
|
295
|
+
```typescript
|
|
296
|
+
const scenarios = readdirSync(join(PACKAGE_PATH, 'scenarios'), { withFileTypes: true })
|
|
297
|
+
.filter((entry) => entry.isDirectory())
|
|
298
|
+
.map((entry) => entry.name);
|
|
299
|
+
|
|
300
|
+
it.each(scenarios)('%s starts and plays a tick', async (scenarioId) => {
|
|
301
|
+
const session = await createTestSession<Context>({ packagePath: PACKAGE_PATH, scenarioId });
|
|
302
|
+
try {
|
|
303
|
+
expect(await session.tick()).toMatchObject({ ok: true });
|
|
304
|
+
} finally {
|
|
305
|
+
await session.close();
|
|
306
|
+
}
|
|
307
|
+
});
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
The starter game's `testing/engine/game.engine.test.ts` ends with this test.
|
|
311
|
+
|
|
281
312
|
### The configuration step
|
|
282
313
|
|
|
283
314
|
A game with a `setup` slot starts at its configuration step. `createTestSession` presses Play for you, so a tick has a game to run. Pass `play: false` to test the step itself, then send `updateSettings` (keyed by settings identifier, for example `{ type: 'updateSettings', payload: { engine: { BaseDemand: 200 } } }`) and `play` as the setup screen would. Settings are fixed from Play onwards, so `state().settings` after `play` is what every tick reads.
|
|
@@ -383,6 +414,10 @@ pnpm exec vitest --config vitest.engine.config.ts testing/engine/game.engine.tes
|
|
|
383
414
|
|
|
384
415
|
Engine tests run in milliseconds per test because there are no subprocesses, no HTTP, and no browser startup.
|
|
385
416
|
|
|
417
|
+
They run logic in the same restricted runtime as `sdk tick` and the dev server, which exposes only the ECMAScript intrinsics. A host global the production runtime lacks, such as `structuredClone` or `fetch`, fails an engine test with a `ReferenceError`, where a unit test calling `Run` directly runs in Node and passes.
|
|
418
|
+
|
|
419
|
+
`pnpm check` runs them last, after validating the package, typechecking, linting and the unit tests. Run it after every change.
|
|
420
|
+
|
|
386
421
|
## CI integration
|
|
387
422
|
|
|
388
423
|
Engine tests require nothing beyond Node.js: no dev server, no browser, and no platform API key, because the service callbacks are stubbed unless a test asks for the platform. Add them to your CI pipeline alongside unit tests:
|
|
@@ -418,20 +453,20 @@ Run Playwright tests in a separate job or stage, since they need a browser and t
|
|
|
418
453
|
|
|
419
454
|
### `TestSession`
|
|
420
455
|
|
|
421
|
-
| Member | Returns
|
|
422
|
-
| -------------------------------- |
|
|
423
|
-
| `send(command)` | `Promise<
|
|
424
|
-
| `state()` | `TestSessionState<Context, Shared>`
|
|
425
|
-
| `team(index)` | `TestSessionTeam<Context>`
|
|
426
|
-
| `shared` | `{ context: Shared }`
|
|
427
|
-
| `tick(options?)` | `Promise<
|
|
428
|
-
| `requestTick(team, options?)` | `Promise<
|
|
429
|
-
| `setData(team, patch, options?)` | `Promise<
|
|
430
|
-
| `setSharedData(patch, options?)` | `Promise<
|
|
431
|
-
| `settled()` | `Promise<void>`
|
|
432
|
-
| `close()` | `Promise<void>`
|
|
433
|
-
|
|
434
|
-
`Command`, `MutationCommand`, `QueryCommand`, `QueryResult`, `MutationResult`, `StateProjection`, `TestSessionState`, `TestSessionTeam`, `TestSessionSetDataOptions`, `TestSessionSetSharedDataOptions`, `ContextUpdate`, `ContextDeletePath`, `FakeClock`, `ParticipantCounts`, `TestServices`, `createStubServices` and `stubGenerateText` are exported from the same module.
|
|
456
|
+
| Member | Returns | Description |
|
|
457
|
+
| -------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
|
|
458
|
+
| `send(command)` | `Promise<TestMutationResult>` or `Promise<QueryResult>` | Run a command as the dev server would. A refusal is an answer, not a throw |
|
|
459
|
+
| `state()` | `TestSessionState<Context, Shared>` | The whole session now, each team's context typed |
|
|
460
|
+
| `team(index)` | `TestSessionTeam<Context>` | One team by stable index: `context`, `participants`, `completedTicks` and the rest. Throws for an unknown one |
|
|
461
|
+
| `shared` | `{ context: Shared }` | The shared store now, under `context` as a session surface's `sessionData.shared` holds it |
|
|
462
|
+
| `tick(options?)` | `Promise<TestMutationResult>` | A facilitator's tick. `{ team }` ticks one team in independent mode |
|
|
463
|
+
| `requestTick(team, options?)` | `Promise<TestMutationResult>` | A participant's request, which `RequestTick` gates judge. `{ participantId }` to choose who asks |
|
|
464
|
+
| `setData(team, patch, options?)` | `Promise<TestMutationResult>` | A participant's write through `ui`, or `{ as: 'system' }` for a trusted one. Also `deletes`, `participantId`, `ui` |
|
|
465
|
+
| `setSharedData(patch, options?)` | `Promise<TestMutationResult>` | A write to the shared store. `{ ui }` holds it to that session surface's `writes`; also `deletes` |
|
|
466
|
+
| `settled()` | `Promise<void>` | Resolves once everything queued has run, including a timer's tick |
|
|
467
|
+
| `close()` | `Promise<void>` | Stop the session's timers. Call it in `afterEach` |
|
|
468
|
+
|
|
469
|
+
A `TestMutationResult` is a `MutationResult` that may carry `logicError`, a `LogicErrorLocation`. `Command`, `MutationCommand`, `QueryCommand`, `QueryResult`, `MutationResult`, `TestMutationResult`, `LogicErrorLocation`, `StateProjection`, `TestSessionState`, `TestSessionTeam`, `TestSessionSetDataOptions`, `TestSessionSetSharedDataOptions`, `ContextUpdate`, `ContextDeletePath`, `FakeClock`, `ParticipantCounts`, `TestServices`, `createStubServices` and `stubGenerateText` are exported from the same module.
|
|
435
470
|
|
|
436
471
|
To call one logic function directly instead, with no session, build its arguments with `logicArgs` from `@seriousgaming/sdk/testing` (see [Testing](./testing.md#testing-the-run-function)).
|
|
437
472
|
|
|
@@ -201,7 +201,7 @@ This is not how a UI's `setData` behaves. A UI deep-merges its patch, because it
|
|
|
201
201
|
|
|
202
202
|
### Removing a key
|
|
203
203
|
|
|
204
|
-
A variable you
|
|
204
|
+
A variable you return replaces the old one whole, so an entry of a map is gone only if the map you return leaves it out. The usual way to build that map spreads the old one (`{ ...context.orders.Open, [id]: order }`), which carries every entry forward, the one you meant to remove included. Rather than rebuild the map without it, name the entry in `deletes`:
|
|
205
205
|
|
|
206
206
|
```typescript
|
|
207
207
|
return {
|
|
@@ -262,6 +262,14 @@ A step (`StepFunction`) receives `state` too, so a step can read it; only the ex
|
|
|
262
262
|
|
|
263
263
|
Reach for a capability instead when anything else reads the value. `scope: 'private'` keeps a capability off every screen while leaving it readable by hooks and endpoints, so a value an endpoint reports on, such as last round's profit for a trend, stays a capability.
|
|
264
264
|
|
|
265
|
+
### Recording benchmarks
|
|
266
|
+
|
|
267
|
+
An engine that lists [benchmarks](./benchmarks.md) in its bundle's `benchmarks` receives each team's records as `benchmarks`, beside `state`, and returns writes to them under `benchmarks`, beside `capabilities`. Type them with the generated `Benchmarks`, the fifth type parameter of `InitializationFunction` and `RunFunction`. A write that does not match its benchmark is dropped with a warning, and the round carries on. See [Writing from the engine](./benchmarks.md#writing-from-the-engine).
|
|
268
|
+
|
|
269
|
+
### Scoring assessments
|
|
270
|
+
|
|
271
|
+
An engine that lists [assessments](./assessments.md) in its bundle's `assessments` receives each team's results as `assessments`, beside `state`, and returns writes to them under `assessments`, beside `capabilities`: one result for a team-level assessment, a result per participant id for a participant-level one. Type them with the generated `Assessments`, the sixth type parameter of `InitializationFunction` and `RunFunction`. A write that does not match its assessment is dropped with a warning, and the round carries on. See [Scoring from the engine](./assessments.md#scoring-from-the-engine).
|
|
272
|
+
|
|
265
273
|
## Ordering the simulation
|
|
266
274
|
|
|
267
275
|
A game holds one engine, so there is no cross-engine ordering to resolve. Split the simulation into steps, one responsibility each, and order them by the order `Run` calls them:
|
|
@@ -305,7 +313,7 @@ Engine logic runs in a **bare V8 isolate**. The runtime provides the ECMAScript
|
|
|
305
313
|
Referencing one throws `ReferenceError` at tick time. Two things protect you:
|
|
306
314
|
|
|
307
315
|
- **The dev server and CLI enforce it.** `sdk dev` and `tick` run your logic in the same restricted environment, so the failure surfaces locally rather than on deploy
|
|
308
|
-
- **Lint catches it before you run anything.** A scaffolded package restricts these globals in `engine/`, `tick_controller/`, `hooks/*/logic/`, `validators/*/logic/` and `endpoints/*/logic/`, so `pnpm run lint` (and your editor) flags the reference with the replacement to use. The UI slots are deliberately out of scope: `ui/`, `session/` and `waiting_room/` run in a browser, where these globals exist
|
|
316
|
+
- **Lint catches it before you run anything.** A scaffolded package restricts these globals in `engine/`, `tick_controller/`, `hooks/*/logic/`, `validators/*/logic/` and `endpoints/*/logic/`, so `pnpm run lint` (and your editor) flags the reference with the replacement to use. The rules ship in the SDK, and the package's `.oxlintrc.json` extends them (`./node_modules/@seriousgaming/sdk-tools/dist/oxlint/logic.json`), so the list keeps up with the runtime. The UI slots are deliberately out of scope: `ui/`, `session/` and `waiting_room/` run in a browser, where these globals exist
|
|
309
317
|
|
|
310
318
|
### What to use instead
|
|
311
319
|
|
|
@@ -43,6 +43,8 @@ New to the SDK? Start with [Designing a serious game](./designing-a-game.md), fo
|
|
|
43
43
|
|
|
44
44
|
- **[Facilitator guides](./guide.md)**: markdown facilitation content shown on the facilitator's page
|
|
45
45
|
- **[Building presentations](./presentation.md)**: the facilitator's slide deck, its deck library, resume and export
|
|
46
|
+
- **[Benchmarks](./benchmarks.md)**: outcomes the engine records, pooled across sessions so a debrief can compare a team with everyone who has played
|
|
47
|
+
- **[Assessments](./assessments.md)**: scores the engine gives each participant or team, placed in bands and judged a pass, for a debrief or a learning management system
|
|
46
48
|
- **[File handling (assets and blobs)](./file-handling.md)**: uploading files from UIs, showing them, and reading them in logic
|
|
47
49
|
- **[LLM integration guide](./llm-integration.md)**: generating text through the platform LLM API
|
|
48
50
|
- **[Speech generation guide](./speech-generation.md)**: synthesising audio with `generateSpeech`
|
|
@@ -53,15 +53,17 @@ const { game, session, settings, theme, locale, getPastState, getAssetUrl } = us
|
|
|
53
53
|
>();
|
|
54
54
|
```
|
|
55
55
|
|
|
56
|
-
| Field
|
|
57
|
-
|
|
|
58
|
-
| `game`
|
|
59
|
-
| `session`
|
|
60
|
-
| `settings`
|
|
61
|
-
| `theme`
|
|
62
|
-
| `locale`
|
|
63
|
-
| `getPastState`
|
|
64
|
-
| `
|
|
56
|
+
| Field | What it holds |
|
|
57
|
+
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
58
|
+
| `game` | `name` in the current locale, `maxTicks` (or `null` when the engine or tick controller decides), `mode`, and `scenarioName` (or `null`). Present with or without a session |
|
|
59
|
+
| `session` | `null` with no session. Otherwise its `id`, `name`, `completedTicks` (the most rounds any team has completed, 0 before the first), `data` (the shared store and every team, narrowed to `reads`), `teams`, and how the room joins: `participants`, `joinLinks`, `sessionJoinLink` and `joinPin` (see [Showing the room how to join](#showing-the-room-how-to-join)) |
|
|
60
|
+
| `settings` | The settings resources the presentation declares, resolved for the scenario, and for the session when there is one |
|
|
61
|
+
| `theme` | The host's theme, to map onto the deck's colours |
|
|
62
|
+
| `locale` | The locale to render in |
|
|
63
|
+
| `getPastState` | Reads past rounds, as the session UI does, with `teams` defaulting to every team. Rejects when there is no session |
|
|
64
|
+
| `getBenchmark` | Reads a [benchmark](./benchmarks.md)'s statistics pooled across sessions, with or without a session. `null` when there is nothing to show |
|
|
65
|
+
| `getAssessment` | Reads an [assessment](./assessments.md)'s results for the whole session. Rejects when there is no session |
|
|
66
|
+
| `getAssetUrl` | Turns an `asset:`, `shared:` or `blob:` reference into a URL |
|
|
65
67
|
|
|
66
68
|
A presentation sees every team: it is the facilitator's view of the room.
|
|
67
69
|
|
|
@@ -167,28 +167,30 @@ const { requestTick, pauseTimer, resumeTimer, undoTick, resetGame } =
|
|
|
167
167
|
useSessionUserInterfaceCallbacks();
|
|
168
168
|
```
|
|
169
169
|
|
|
170
|
-
| Callback | Signature
|
|
171
|
-
| -------------------- |
|
|
172
|
-
| `requestTick` | `(teamId?: string) => Promise<void>`
|
|
173
|
-
| `pauseTimer` | `(teamId?: string) => Promise<void>`
|
|
174
|
-
| `resumeTimer` | `(teamId?: string) => Promise<void>`
|
|
175
|
-
| `undoTick` | `(teamId?: string) => Promise<void>`
|
|
176
|
-
| `resetGame` | `(teamId?: string) => Promise<void>`
|
|
177
|
-
| `getPastState` | `(query) => Promise<PastStateEntry[]>`
|
|
178
|
-
| `
|
|
179
|
-
| `
|
|
180
|
-
| `
|
|
181
|
-
| `
|
|
182
|
-
| `
|
|
183
|
-
| `
|
|
184
|
-
| `
|
|
185
|
-
| `
|
|
186
|
-
| `
|
|
187
|
-
| `
|
|
188
|
-
| `
|
|
189
|
-
| `
|
|
190
|
-
| `
|
|
191
|
-
| `
|
|
170
|
+
| Callback | Signature | Description |
|
|
171
|
+
| -------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
172
|
+
| `requestTick` | `(teamId?: string) => Promise<void>` | Advance the game by one tick; omit `teamId` to advance all teams |
|
|
173
|
+
| `pauseTimer` | `(teamId?: string) => Promise<void>` | Pause automatic ticking; omit `teamId` to pause all teams |
|
|
174
|
+
| `resumeTimer` | `(teamId?: string) => Promise<void>` | Resume automatic ticking; omit `teamId` to resume all teams |
|
|
175
|
+
| `undoTick` | `(teamId?: string) => Promise<void>` | Un-run the last tick, keeping the tick's decisions; omit `teamId` to undo all teams. Naming one is independent mode only |
|
|
176
|
+
| `resetGame` | `(teamId?: string) => Promise<void>` | Re-initialise the game from scratch; omit `teamId` to reset all teams |
|
|
177
|
+
| `getPastState` | `(query) => Promise<PastStateEntry[]>` | Read committed past rounds; `teams` defaults to every team, or name one team by id |
|
|
178
|
+
| `getBenchmark` | `(identifier, query?) => Promise<BenchmarkStatistics \| null>` | Read a [benchmark](./benchmarks.md)'s pooled statistics; `null` when there is nothing to show |
|
|
179
|
+
| `getAssessment` | `(identifier) => Promise<AssessmentReport>` | Read an [assessment](./assessments.md)'s results for every team and participant |
|
|
180
|
+
| `extendTick` | `(byMs, teamId?) => Promise<void>` | Move the currently scheduled tick's deadline by `byMs` milliseconds; negative pulls it in |
|
|
181
|
+
| `openHostOverlay` | `(overlay, target?) => Promise<void>` | Ask the host to open the guide or a print sheet |
|
|
182
|
+
| `uploadBlob` | `(file: File) => Promise<string>` | Upload a file, returns a `blob:<id>` reference |
|
|
183
|
+
| `getAssetUrl` | `(reference: string) => string` | Resolve an `asset:`, `shared:`, or `blob:` reference to a URL |
|
|
184
|
+
| `readAsset` | `(reference: string) => Promise<{ data, mimeType, name }>` | Read bytes for an `asset:`, `shared:`, or `blob:` reference |
|
|
185
|
+
| `endpoints` | `Record<string, (request) => Promise<Response>>` | Call a declared endpoint by identifier |
|
|
186
|
+
| `setWaitingRoom` | `(open: boolean) => Promise<void>` | Open or close the session's waiting room; no `teamId` |
|
|
187
|
+
| `resetWalkthrough` | `() => Promise<void>` | Throw the walkthrough away and restart it at tick 0; rejects while the session has no walkthrough |
|
|
188
|
+
| `createTeam` | `(name?: string) => Promise<void>` | Add a team; the host assigns the index |
|
|
189
|
+
| `renameTeam` | `(teamId, name) => Promise<void>` | Rename a team |
|
|
190
|
+
| `renameParticipant` | `(participantId, name) => Promise<void>` | Rename a participant; the host resolves their team |
|
|
191
|
+
| `moveParticipant` | `(participantId, teamId) => Promise<void>` | Reassign a participant to another team |
|
|
192
|
+
| `deleteTeam` | `(teamId) => Promise<void>` | Delete an empty team; independent mode only, and never the last team |
|
|
193
|
+
| `setThemePreference` | `(preference: ThemePreference) => void` | Set the host's theme preference |
|
|
192
194
|
|
|
193
195
|
The promise-returning callbacks resolve and reject as described in [Controlling game flow](./session-game-flow.md#controlling-game-flow). The wrapper supplies every callback, so none needs an optional-chaining guard.
|
|
194
196
|
|
|
@@ -412,16 +412,11 @@ setData({}, { deletes: ['pinboard.Notes.p1'] }); // the note's key is gone, not
|
|
|
412
412
|
Two copies of React are loaded: one from your package and one from the `file://` SDK dependency. Add `resolve.dedupe` to your `vitest.config.ts`, with the SDK packages beside React so a second copy of the SDK cannot hide the providers either:
|
|
413
413
|
|
|
414
414
|
```typescript
|
|
415
|
+
import { REACT_CONTEXT_PACKAGES } from '@seriousgaming/sdk-tools/vite';
|
|
416
|
+
|
|
415
417
|
export default defineConfig({
|
|
416
418
|
resolve: {
|
|
417
|
-
dedupe: [
|
|
418
|
-
'react',
|
|
419
|
-
'react-dom',
|
|
420
|
-
'@emotion/react',
|
|
421
|
-
'@emotion/styled',
|
|
422
|
-
'@seriousgaming/sdk',
|
|
423
|
-
'@seriousgaming/deck',
|
|
424
|
-
],
|
|
419
|
+
dedupe: [...REACT_CONTEXT_PACKAGES],
|
|
425
420
|
},
|
|
426
421
|
// ...
|
|
427
422
|
});
|
|
@@ -4,7 +4,7 @@ A tick controller makes ticks happen on their own, on a schedule your logic deci
|
|
|
4
4
|
|
|
5
5
|
This guide explains the model, then is the reference for writing one.
|
|
6
6
|
|
|
7
|
-
**Keywords:** tick controller, timer, automatic ticks, interval, schedule, timed rounds, nextTickAt, game completion, complete, enabled, pause, extend a tick, cron
|
|
7
|
+
**Keywords:** tick controller, timer, automatic ticks, interval, schedule, timed rounds, nextTickAt, game completion, complete, enabled, pause, extend a tick, cron, dormant, unattended session
|
|
8
8
|
|
|
9
9
|
## The model
|
|
10
10
|
|
|
@@ -415,6 +415,27 @@ pnpm run sdk timer resume --team 2 # one team, in an independent game
|
|
|
415
415
|
|
|
416
416
|
The current schedule, a [`TimerState`](../api/sdk-ui.md#timerstate) with every duration and timestamp in milliseconds, is pushed to every game UI. UIs subscribe with `useUserInterfaceTimer` and render their own countdown or progress bar. See [Displaying the tick timer](./ui-ticks.md#displaying-the-tick-timer) in the user interfaces guide.
|
|
417
417
|
|
|
418
|
+
## Unattended sessions
|
|
419
|
+
|
|
420
|
+
A session left running with nobody using it may be suspended by its host. Once nothing has used the session for at least 24 hours and at least 100 automatic ticks, the host may stop its automatic ticking. The session is then **dormant**. Both numbers are minimums you can rely on: a host may wait longer, or never suspend at all, but never suspends sooner.
|
|
421
|
+
|
|
422
|
+
Nobody has to do anything to bring a dormant session back. The next time somebody or something uses it, it wakes before that use is handled, and the timer carries on as it does after a pause: an interval schedule continues from the time it had left, and a `nextTickAt` schedule asks `GetTickController` again without firing the ticks it missed. Each of these always wakes a session:
|
|
423
|
+
|
|
424
|
+
- A surface or facilitator page opening
|
|
425
|
+
- A write from any surface or caller
|
|
426
|
+
- A facilitator action, such as a manual tick, a timer control or a roster change
|
|
427
|
+
- An endpoint call, from any caller
|
|
428
|
+
|
|
429
|
+
A host may count more, such as a surface that stays open: the dev server keeps a session awake while any page is open on it. Reading the session's state never wakes it. Waking never ends a facilitator's pause, so a timer paused before the session went dormant stays paused.
|
|
430
|
+
|
|
431
|
+
What this means for a long-running game:
|
|
432
|
+
|
|
433
|
+
- **A slow game is safe.** The tick count is there so a game that ticks daily or weekly is not suspended after one quiet day. It is counted across the session, so a game of ten independent teams reaches 100 after ten rounds each
|
|
434
|
+
- **Plan for the clock stopping.** A game that ticks every few minutes for weeks will stop ticking a day after everyone stops using it, and resume when they come back. If your simulation must run on whether or not anybody looks at it, have something call one of its endpoints, which counts as using it
|
|
435
|
+
- **Showing it.** While dormant, the [`TimerState`](../api/sdk-ui.md#timerstate) your UIs receive has `dormant: true` and `dormantAt`, and `nextTickAt` is null. A UI left open while its session went dormant can say why the countdown stopped. Opening a surface wakes the session first, so a surface opened later never sees it. On waking, the dormant time is added to `pausedMs`, so a progress bar built from it stays right
|
|
436
|
+
|
|
437
|
+
To see how your UIs show a dormant session, press **Make dormant** in the dev drawer's Session tab, or post `{ "type": "makeDormant" }` to `/api/command`. The session goes dormant at once, without waiting a day, and the next thing that uses it wakes it.
|
|
438
|
+
|
|
418
439
|
## Testing without waiting
|
|
419
440
|
|
|
420
441
|
A one-minute timer takes a minute to test, and the 30-second floor means none takes less. Start the dev server on a fake clock instead, and move time yourself:
|
package/dist/docs/guides/ui.md
CHANGED
|
@@ -144,6 +144,30 @@ const { entries, error, loading, refetch } = usePastState<Context>(
|
|
|
144
144
|
|
|
145
145
|
Pass `null` to read nothing yet. `refetch()` reads the same query again. It works on the game UI, the waiting room, the session UI and a presentation, the surfaces that have `getPastState`.
|
|
146
146
|
|
|
147
|
+
### Comparing with other sessions
|
|
148
|
+
|
|
149
|
+
`useUserInterfaceCallbacks()` also exposes `getBenchmark(identifier, query?)`, which reads a [benchmark](./benchmarks.md): anonymous statistics for this game pooled across sessions, so a debrief can show where a team sits against everyone who has played. Pass a list of filters on tag values, narrowest first, built from the settings your UI reads:
|
|
150
|
+
|
|
151
|
+
```typescript
|
|
152
|
+
const { getBenchmark } = useUserInterfaceCallbacks();
|
|
153
|
+
const stats = await getBenchmark('outcome', {
|
|
154
|
+
where: [{ difficulty: settings.setup.Difficulty }, {}],
|
|
155
|
+
});
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
It resolves to `null` when there is nothing to show, and any figure but `count` may be missing, so render the team's own figure first and the comparison only where a figure is present. The waiting room, the session UI and a presentation have it too. See [Reading benchmarks on a screen](./benchmarks.md#reading-benchmarks-on-a-screen).
|
|
159
|
+
|
|
160
|
+
### Showing a participant's results
|
|
161
|
+
|
|
162
|
+
`useUserInterfaceCallbacks()` also exposes `getAssessment(identifier)`, which reads an [assessment](./assessments.md): the scores the engine gave, each placed in a band and judged a pass with the thresholds in force for the session. A participant's screen receives only their own result and their team's, and an observer's the team's:
|
|
163
|
+
|
|
164
|
+
```typescript
|
|
165
|
+
const { getAssessment } = useUserInterfaceCallbacks();
|
|
166
|
+
const mine = (await getAssessment('teamwork')).results[0];
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
`mine` is absent until the engine has scored this participant. Read again after each round. See [Reading results on a screen](./assessments.md#reading-results-on-a-screen).
|
|
170
|
+
|
|
147
171
|
### Settings are what your UI declares
|
|
148
172
|
|
|
149
173
|
`settings` holds exactly the settings resources listed in the UI's `settings`, and no others. A UI that needs one of the engine's values lists the same settings resource the engine does (`"settings": ["engine"]`) and reads `settings.engine.X`: there is no need to copy it into context at `Init`, and no copy to go stale.
|