@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.
Files changed (219) hide show
  1. package/dist/agent/guidance.md +35 -23
  2. package/dist/{cli-F2D4GGUA.js → cli-2BKEIIA3.js} +66 -0
  3. package/dist/{cli-NQSL2CIH.js → cli-2QGTDHRX.js} +21 -21
  4. package/dist/{cli-33MZSPPK.js → cli-2SDG3SZ7.js} +21 -21
  5. package/dist/{cli-CLO7HKEQ.js → cli-2VXP34R5.js} +5 -3
  6. package/dist/{cli-P3NUTOPK.js → cli-2W4B6PD5.js} +1 -1
  7. package/dist/{cli-SOO6SEIS.js → cli-2X7DKSXN.js} +28 -25
  8. package/dist/{cli-LNEZ6KDW.js → cli-2ZP4N7HK.js} +19 -19
  9. package/dist/{cli-5O7XENQY.js → cli-3GJYZH4C.js} +5 -5
  10. package/dist/{cli-NAZTYKZT.js → cli-3GO3M2MX.js} +30 -14
  11. package/dist/{cli-YZJBFKRI.js → cli-3LDLUNME.js} +17 -17
  12. package/dist/{cli-J42N4PJG.js → cli-3WY6L2WP.js} +31 -29
  13. package/dist/{cli-WG7MAOCS.js → cli-44MBABRD.js} +25 -25
  14. package/dist/{cli-MGZYQDCH.js → cli-4IO7MKLR.js} +20 -20
  15. package/dist/{cli-HNDFANQG.js → cli-4U2PY7W3.js} +1 -1
  16. package/dist/{cli-4JNF3O5N.js → cli-4WI4LTBI.js} +2 -2
  17. package/dist/{cli-OTBCA54D.js → cli-55EIGGZK.js} +1 -1
  18. package/dist/{cli-5TKPT3CY.js → cli-5AQV6FTL.js} +18 -18
  19. package/dist/{cli-KNXY43YV.js → cli-5CW7BEU7.js} +3 -3
  20. package/dist/{cli-5V4N4BR4.js → cli-5JUVHNZF.js} +12 -12
  21. package/dist/{cli-F3YJKP6D.js → cli-5KERL6HV.js} +9 -4
  22. package/dist/{cli-HN442ZVK.js → cli-5KSA24NQ.js} +24 -24
  23. package/dist/{cli-5VZBFMCK.js → cli-5PIFO3EN.js} +8 -0
  24. package/dist/{cli-IQBY7Z7Q.js → cli-5QN2Z43X.js} +20 -20
  25. package/dist/cli-5XSPAA5X.js +69 -0
  26. package/dist/{cli-QW7VXL2V.js → cli-62KAYGXO.js} +20 -20
  27. package/dist/{cli-TDLIPYKT.js → cli-6IMV5ZZU.js} +26 -26
  28. package/dist/{cli-UULZSQBV.js → cli-6KWCIAN2.js} +764 -66
  29. package/dist/{cli-2ANX6E3A.js → cli-6NWETIX5.js} +20 -20
  30. package/dist/{cli-EXUPHPDJ.js → cli-774W3MN5.js} +26 -26
  31. package/dist/cli-7BUD3VAD.js +16 -0
  32. package/dist/{cli-7NUFHMGE.js → cli-7KEP57S7.js} +12 -12
  33. package/dist/{cli-6CYAOUYT.js → cli-7OYFJMA6.js} +18 -18
  34. package/dist/{cli-ILHHJR2S.js → cli-7ZNEDQ3G.js} +20 -20
  35. package/dist/{cli-5RRPUL6V.js → cli-AFK6OUID.js} +12 -12
  36. package/dist/{cli-A3AJQZEN.js → cli-AIYQFWXN.js} +25 -25
  37. package/dist/{cli-B5DWKRZ4.js → cli-ARAAEWIQ.js} +2 -2
  38. package/dist/cli-AVQYV3N4.js +36 -0
  39. package/dist/{cli-35GV2F6R.js → cli-B54Z6CXH.js} +16 -16
  40. package/dist/{cli-467VRXGP.js → cli-B5TC4MEL.js} +5 -5
  41. package/dist/{cli-5Z4D3F6Y.js → cli-BCXGOLU3.js} +3 -3
  42. package/dist/{cli-G2GLW5Z4.js → cli-BHAODVTZ.js} +1 -1
  43. package/dist/{cli-XR3O2YTV.js → cli-BPS2JG74.js} +20 -20
  44. package/dist/{cli-W3RG2MRI.js → cli-BVO55SR2.js} +2 -2
  45. package/dist/{cli-PYAST3G5.js → cli-CFH3JZP5.js} +21 -21
  46. package/dist/{cli-VZVHS5AP.js → cli-CTK2OIK6.js} +20 -20
  47. package/dist/{cli-ATWJCB2G.js → cli-CW5MV4VX.js} +4 -4
  48. package/dist/{cli-TCQJL2GY.js → cli-D5VOSJZ7.js} +1 -1
  49. package/dist/{cli-KIZTASLL.js → cli-DAEPMK7A.js} +5 -5
  50. package/dist/{cli-44CM2AH2.js → cli-DAHR7PKB.js} +1 -1
  51. package/dist/{cli-XW3JLRSA.js → cli-DWDSBTYL.js} +1 -1
  52. package/dist/cli-DYSDPGXW.js +95 -0
  53. package/dist/{cli-GRSQRFRG.js → cli-DZCLRZXJ.js} +9 -2
  54. package/dist/{cli-RSF5R3HC.js → cli-EJ47IE45.js} +28 -25
  55. package/dist/{cli-QDBYFITU.js → cli-EK4OSJHA.js} +2 -2
  56. package/dist/{cli-GO64NABP.js → cli-FCJHNXDA.js} +1 -1
  57. package/dist/{cli-ZNQBF4Z3.js → cli-FNESSE3L.js} +1 -1
  58. package/dist/{cli-MUOLHQNL.js → cli-FTLH4WCE.js} +17 -17
  59. package/dist/{cli-JHLWBRXB.js → cli-FYV77YS2.js} +18 -18
  60. package/dist/cli-GMJX6Q4Q.js +36 -0
  61. package/dist/{cli-7JUNA74L.js → cli-GRBVNGDW.js} +1 -1
  62. package/dist/{cli-XKAIDYIE.js → cli-HAFCFY77.js} +33 -19
  63. package/dist/{cli-OXLOGXT3.js → cli-HCJLYI24.js} +3 -3
  64. package/dist/{cli-HHRP6FP6.js → cli-HCXS5EXU.js} +25 -25
  65. package/dist/cli-HEUNNHDH.js +36 -0
  66. package/dist/{cli-36GABN2A.js → cli-HNUTIWDZ.js} +19 -19
  67. package/dist/{cli-JXQLHJO2.js → cli-HXT25ETJ.js} +244 -243
  68. package/dist/{cli-5EH4WTH4.js → cli-IGEL7UJQ.js} +5 -5
  69. package/dist/{cli-JMNPMDXH.js → cli-IO32YA5N.js} +26 -26
  70. package/dist/cli-IPTGZDBB.js +36 -0
  71. package/dist/{cli-L54SXUK6.js → cli-J25TYFKB.js} +19 -19
  72. package/dist/{cli-CQ4ZR3ZQ.js → cli-J7XYMEMX.js} +20 -20
  73. package/dist/{cli-5DWR7RPQ.js → cli-JC5OJRID.js} +2 -2
  74. package/dist/{cli-25SJZI7N.js → cli-JD563OF4.js} +126 -27
  75. package/dist/{cli-JAVMRERQ.js → cli-JRJF2WHU.js} +20 -20
  76. package/dist/{cli-UQC46YSV.js → cli-JTFLIMIG.js} +3 -3
  77. package/dist/{cli-2AH6D32V.js → cli-K2BSJ2PK.js} +2 -2
  78. package/dist/{cli-XB5PI2XT.js → cli-K4QTYMN2.js} +25 -25
  79. package/dist/{cli-5SHG2M7E.js → cli-KFJDD4C4.js} +20 -20
  80. package/dist/{cli-WW54THXN.js → cli-KVQ2JPVD.js} +1 -1
  81. package/dist/{cli-O5WYATAI.js → cli-L6AHMW2Z.js} +4 -2
  82. package/dist/{cli-IKSLPAZN.js → cli-LCYUBCVY.js} +4 -4
  83. package/dist/{cli-HGCOEL5T.js → cli-LEWSCDH5.js} +4 -4
  84. package/dist/{cli-HNG6PZW2.js → cli-LI6G7GND.js} +27 -27
  85. package/dist/{cli-2AVPNSAX.js → cli-LU2GCWIU.js} +21 -21
  86. package/dist/{cli-UEQMK4WX.js → cli-M3Z2KOEB.js} +1 -1
  87. package/dist/{cli-226ZJ72R.js → cli-M6E3E3I2.js} +170 -3
  88. package/dist/{cli-OXU6TTEN.js → cli-MCRPA4Z6.js} +20 -20
  89. package/dist/{cli-BQ36DV5C.js → cli-MI2DEDMA.js} +3 -3
  90. package/dist/{cli-6O7YCK2M.js → cli-MITZ6SE7.js} +3 -3
  91. package/dist/{cli-VALLLE6Y.js → cli-MTIYD3BX.js} +26 -26
  92. package/dist/{cli-5M6KDNVX.js → cli-MTZUJGBK.js} +2 -2
  93. package/dist/{cli-GSOV26O5.js → cli-NCLMUXLC.js} +14 -14
  94. package/dist/{cli-Z3DITVBE.js → cli-NLS3DKWH.js} +26 -26
  95. package/dist/{cli-AH6AMAIB.js → cli-NMDGS7IE.js} +1 -1
  96. package/dist/cli-O3DJO2CS.js +30 -0
  97. package/dist/{cli-BC67QHD5.js → cli-O47D5BFN.js} +2 -2
  98. package/dist/{cli-MDVC5ZNM.js → cli-OBRZ36VP.js} +14 -14
  99. package/dist/{cli-267QJ2DS.js → cli-OMG4E53H.js} +20 -20
  100. package/dist/{cli-C32Q5E5I.js → cli-P6V3NSU4.js} +1 -1
  101. package/dist/{cli-PBSLPO6G.js → cli-PAMQMTHK.js} +21 -21
  102. package/dist/{cli-RUEPTOWG.js → cli-PKTHOCT3.js} +26 -26
  103. package/dist/{cli-PTXOKO2Y.js → cli-QK7QAP5H.js} +18 -18
  104. package/dist/cli-QQ432JEN.js +36 -0
  105. package/dist/{cli-YFLQ7XOO.js → cli-QVNDPTBU.js} +20 -20
  106. package/dist/{cli-KJA6GLZI.js → cli-R2DFD6ZZ.js} +15 -15
  107. package/dist/{cli-6BLVI2JM.js → cli-RMVJMOWU.js} +111 -7
  108. package/dist/{cli-M6AZFIMV.js → cli-RQISHMJF.js} +88 -23
  109. package/dist/{cli-X64BNBQH.js → cli-RVZH462G.js} +585 -8
  110. package/dist/{cli-LLJQI2QP.js → cli-SEEOQVUL.js} +12 -12
  111. package/dist/{cli-QTCTWYCM.js → cli-SO354HPI.js} +3 -3
  112. package/dist/{cli-URCHZDTS.js → cli-T76HDH7F.js} +90 -5
  113. package/dist/{cli-ZJW6HQ6N.js → cli-TIS7DWRR.js} +7 -7
  114. package/dist/{cli-WOFYI7HZ.js → cli-TY3B6XS7.js} +21 -21
  115. package/dist/{cli-4FJL3KQZ.js → cli-UKEZJFIT.js} +2 -2
  116. package/dist/cli-VQAMW4RF.js +95 -0
  117. package/dist/{cli-4A7RWFNO.js → cli-W4LMRVZT.js} +78 -47
  118. package/dist/cli-W7I5KGIB.js +84 -0
  119. package/dist/{cli-B3EFE7ZF.js → cli-WXGJFA4F.js} +1 -1
  120. package/dist/{cli-IPTHJT3J.js → cli-XCG33I77.js} +28 -25
  121. package/dist/{cli-WLSACMYA.js → cli-YHLSG5HB.js} +30 -28
  122. package/dist/cli-YNH5DTHY.js +36 -0
  123. package/dist/cli-YPMJWPDA.js +69 -0
  124. package/dist/{cli-PXQYY6KM.js → cli-YSXIR7EM.js} +0 -0
  125. package/dist/cli-ZPFWO4VW.js +85 -0
  126. package/dist/cli.js +53 -53
  127. package/dist/client/index.d.ts +1 -1
  128. package/dist/client/test-session.d.ts +44 -6
  129. package/dist/client.js +1934 -286
  130. package/dist/core/assessment-moves.d.ts +32 -0
  131. package/dist/core/assessment-reports.d.ts +38 -0
  132. package/dist/core/assessment-settings.d.ts +15 -0
  133. package/dist/core/benchmark-samples.d.ts +28 -0
  134. package/dist/core/session-host.d.ts +4 -0
  135. package/dist/core/session-roster.d.ts +6 -0
  136. package/dist/core/session-timers.d.ts +40 -0
  137. package/dist/core/session.d.ts +14 -1
  138. package/dist/core/tick-timer.d.ts +18 -0
  139. package/dist/dev/console/assets/{index-Ch6HHb2T.js → index-zd--5H1f.js} +26 -26
  140. package/dist/dev/console/index.html +1 -1
  141. package/dist/dev/shell.d.ts +8 -0
  142. package/dist/dev/view/commands.d.ts +3 -1
  143. package/dist/docs/api/index.md +4 -2
  144. package/dist/docs/api/sdk-commands.md +29 -0
  145. package/dist/docs/api/sdk-e2e.md +30 -0
  146. package/dist/docs/api/sdk-projection.md +5 -0
  147. package/dist/docs/api/sdk-tools-client.md +68 -6
  148. package/dist/docs/api/sdk-tools-vite.md +21 -0
  149. package/dist/docs/api/sdk-ui.md +7 -0
  150. package/dist/docs/api/sdk.md +834 -19
  151. package/dist/docs/changelog.md +67 -0
  152. package/dist/docs/cli-error-codes.md +5 -1
  153. package/dist/docs/cli-reference.md +76 -2
  154. package/dist/docs/concepts/index.md +2 -0
  155. package/dist/docs/concepts/terminology.md +12 -0
  156. package/dist/docs/guides/assessments.md +248 -0
  157. package/dist/docs/guides/benchmarks.md +241 -0
  158. package/dist/docs/guides/endpoints.md +1 -1
  159. package/dist/docs/guides/engine-testing.md +49 -14
  160. package/dist/docs/guides/engine.md +10 -2
  161. package/dist/docs/guides/index.md +2 -0
  162. package/dist/docs/guides/presentation.md +11 -9
  163. package/dist/docs/guides/session-hooks.md +24 -22
  164. package/dist/docs/guides/testing.md +3 -8
  165. package/dist/docs/guides/tick-controller.md +22 -1
  166. package/dist/docs/guides/ui.md +24 -0
  167. package/dist/docs/guides/upgrading.md +36 -0
  168. package/dist/docs/page-index.md +18 -13
  169. package/dist/docs/recipes/create-assessment.md +124 -0
  170. package/dist/docs/recipes/create-benchmark.md +115 -0
  171. package/dist/docs/recipes/create-game.md +1 -1
  172. package/dist/docs/recipes/fix-duplicate-packages.md +8 -19
  173. package/dist/docs/recipes/index.md +2 -0
  174. package/dist/execution/context-composition.d.ts +39 -4
  175. package/dist/execution/engine-state.d.ts +13 -0
  176. package/dist/execution/executor.d.ts +16 -0
  177. package/dist/execution/logic-result.d.ts +13 -2
  178. package/dist/help-examples.d.ts +12 -0
  179. package/dist/host/adapter.d.ts +24 -1
  180. package/dist/host/protocol.d.ts +115 -1
  181. package/dist/host.js +29 -1
  182. package/dist/oxlint/logic.json +184 -0
  183. package/dist/playwright.js +1928 -280
  184. package/dist/runtime/index.d.ts +3 -1
  185. package/dist/runtime/manifest-version.d.ts +1 -1
  186. package/dist/runtime.js +298 -16
  187. package/dist/schema.json +189 -0
  188. package/dist/templates/package/README.md.liquid +1 -0
  189. package/dist/templates/package/claude/rules/workflow-create-engine.md +1 -1
  190. package/dist/templates/package/claude/rules/workflow-create-user-interface.md +1 -1
  191. package/dist/templates/package/claude/rules/workflow-test-engine-or-ui.md +1 -1
  192. package/dist/templates/package/claude/rules/workflow-update-sdk-version.md +2 -2
  193. package/dist/templates/package/claude/settings.json.template +1 -0
  194. package/dist/templates/package/oxfmtrc.json.template +8 -1
  195. package/dist/templates/package/oxlintrc.json.template +1 -180
  196. package/dist/templates/package/package.json.liquid +1 -0
  197. package/dist/templates/package/vite.config.ts.liquid +2 -8
  198. package/dist/templates/package/vitest.config.ts.liquid +2 -8
  199. package/dist/templates/starter-game/package.json +2 -1
  200. package/dist/templates/starter-game/testing/engine/game.engine.test.ts +62 -37
  201. package/dist/templates/starter-game/vite.config.ts +2 -8
  202. package/dist/templates/starter-game/vitest.config.ts +4 -3
  203. package/dist/templating/resource-metadata.d.ts +1 -1
  204. package/dist/utils/error-codes.d.ts +9 -1
  205. package/dist/utils/resource-scan.d.ts +5 -0
  206. package/dist/validation/assessment-validation.d.ts +34 -0
  207. package/dist/validation/benchmark-validation.d.ts +20 -0
  208. package/dist/validation/schema-validation.d.ts +4 -0
  209. package/dist/vite/index.d.ts +30 -0
  210. package/dist/vite.js +12 -0
  211. package/package.json +12 -4
  212. package/dist/cli-27Z5T52R.js +0 -30
  213. package/dist/cli-5XE4OMFL.js +0 -36
  214. package/dist/cli-BB6CU4ZC.js +0 -36
  215. package/dist/cli-FGP6YYM7.js +0 -36
  216. package/dist/cli-I3ZAZYWP.js +0 -36
  217. package/dist/cli-RFAPPYXK.js +0 -36
  218. package/dist/cli-WZNIW6ZO.js +0 -16
  219. 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 | Description |
422
- | -------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
423
- | `send(command)` | `Promise<MutationResult>` or `Promise<QueryResult>` | Run a command as the dev server would. A refusal is an answer, not a throw |
424
- | `state()` | `TestSessionState<Context, Shared>` | The whole session now, each team's context typed |
425
- | `team(index)` | `TestSessionTeam<Context>` | One team by stable index: `context`, `participants`, `completedTicks` and the rest. Throws for an unknown one |
426
- | `shared` | `{ context: Shared }` | The shared store now, under `context` as a session surface's `sessionData.shared` holds it |
427
- | `tick(options?)` | `Promise<MutationResult>` | A facilitator's tick. `{ team }` ticks one team in independent mode |
428
- | `requestTick(team, options?)` | `Promise<MutationResult>` | A participant's request, which `RequestTick` gates judge. `{ participantId }` to choose who asks |
429
- | `setData(team, patch, options?)` | `Promise<MutationResult>` | A participant's write through `ui`, or `{ as: 'system' }` for a trusted one. Also `deletes`, `participantId`, `ui` |
430
- | `setSharedData(patch, options?)` | `Promise<MutationResult>` | A write to the shared store. `{ ui }` holds it to that session surface's `writes`; also `deletes` |
431
- | `settled()` | `Promise<void>` | Resolves once everything queued has run, including a timer's tick |
432
- | `close()` | `Promise<void>` | Stop the session's timers. Call it in `afterEach` |
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 leave out keeps its value, so a fold can never take an entry out of a map keyed by something arbitrary, such as an order or team id. Name the entry in `deletes` instead:
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 | 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
- | `getAssetUrl` | Turns an `asset:`, `shared:` or `blob:` reference into a URL |
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 | 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
- | `extendTick` | `(byMs, teamId?) => Promise<void>` | Move the currently scheduled tick's deadline by `byMs` milliseconds; negative pulls it in |
179
- | `openHostOverlay` | `(overlay, target?) => Promise<void>` | Ask the host to open the guide or a print sheet |
180
- | `uploadBlob` | `(file: File) => Promise<string>` | Upload a file, returns a `blob:<id>` reference |
181
- | `getAssetUrl` | `(reference: string) => string` | Resolve an `asset:`, `shared:`, or `blob:` reference to a URL |
182
- | `readAsset` | `(reference: string) => Promise<{ data, mimeType, name }>` | Read bytes for an `asset:`, `shared:`, or `blob:` reference |
183
- | `endpoints` | `Record<string, (request) => Promise<Response>>` | Call a declared endpoint by identifier |
184
- | `setWaitingRoom` | `(open: boolean) => Promise<void>` | Open or close the session's waiting room; no `teamId` |
185
- | `resetWalkthrough` | `() => Promise<void>` | Throw the walkthrough away and restart it at tick 0; rejects while the session has no walkthrough |
186
- | `createTeam` | `(name?: string) => Promise<void>` | Add a team; the host assigns the index |
187
- | `renameTeam` | `(teamId, name) => Promise<void>` | Rename a team |
188
- | `renameParticipant` | `(participantId, name) => Promise<void>` | Rename a participant; the host resolves their team |
189
- | `moveParticipant` | `(participantId, teamId) => Promise<void>` | Reassign a participant to another team |
190
- | `deleteTeam` | `(teamId) => Promise<void>` | Delete an empty team; independent mode only, and never the last team |
191
- | `setThemePreference` | `(preference: ThemePreference) => void` | Set the host's theme preference |
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:
@@ -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.