@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
@@ -700,6 +700,42 @@ A host may now offer one join link for the whole session and put each person who
700
700
 
701
701
  A game whose teams are interchangeable needs nothing. A test that builds the `game` settings by hand, rather than spreading the generated `defaultSettings`, adds `sessionJoin` to `teams`.
702
702
 
703
+ ### 1.11: catch an older package's scaffold up
704
+
705
+ Nothing here is required. A package made by `sdk new package` at 1.11 has all of it, and from 1.11 each release's changelog lists what changed in the scaffold under **Scaffold changes**, one line per file, so a later upgrade only has to read those lines. An older package copies from `node_modules/@seriousgaming/sdk-tools/dist/templates/package/`, in this order:
706
+
707
+ 1. **Replace `playwright.config.ts` first**, if it still names a port. Copy `global-setup.ts.template` to `testing/e2e/global-setup.ts` and replace `playwright.config.ts` from `playwright.config.ts.liquid`: and import `test` and `expect` from `@seriousgaming/sdk-tools/playwright` in each spec. Every worker then starts an isolated dev server on free ports, so two packages, or two checkouts of one, can run their browser tests at once
708
+ 2. **Add the `check` script** to `package.json`, from `package.json.liquid`. It validates the package, typechecks, lints, and runs the unit and engine tests, stopping at the first that fails. Drop the `test:engine` step from it if the package has no engine tests
709
+ 3. **Add an engine test that plays every scenario**, as [Playing every scenario](./engine-testing.md#playing-every-scenario) shows. Engine tests run logic in the restricted runtime, so this is what catches a scenario the engine cannot play
710
+ 4. **Extend the SDK's lint rules for logic** in place of your copy. In `.oxlintrc.json`, add `"extends": ["./node_modules/@seriousgaming/sdk-tools/dist/oxlint/logic.json"]` and delete the override that lists `no-restricted-globals`, and the one that turns it off for tests. The list of globals the production runtime lacks then comes from the installed SDK
711
+ 5. **Read the dedupe list from the SDK** in `vite.config.ts` and `vitest.config.ts`: `import { REACT_CONTEXT_PACKAGES } from '@seriousgaming/sdk-tools/vite'` and set `resolve.dedupe` to `[...REACT_CONTEXT_PACKAGES]`, followed by any package of your own that holds React context
712
+ 6. **Keep build output out of the formatter.** Add `lib/`, `test-results/` and `playwright-report/` to `ignorePatterns` in `.oxfmtrc.json`
713
+ 7. **Write the team mode down.** If `seriousgaming.sdk.json` has no `teams.mode`, add `"teams": { "mode": "independent" }`, which is what it has been running as, or `"shared-state"` if that is what the game needs
714
+ 8. **Refresh the upgrade rule itself.** Replace `.claude/rules/workflow-update-sdk-version.md` from `claude/rules/`: the new one reads the **Scaffold changes** sections on every later upgrade
715
+
716
+ A workspace of several games applies each step to every game. The copies stay the game's own, so keep any local edit a template does not have.
717
+
718
+ ### 1.12: add `getBenchmark` and `getAssessment` to a hand-built callbacks object
719
+
720
+ `UserInterfaceCallbacks`, `SessionUserInterfaceCallbacks` and the value `usePresentation()` returns gain `getBenchmark`, which reads a [benchmark](./benchmarks.md), and `getAssessment`, which reads an [assessment](./assessments.md). A game reading them through `useUserInterfaceCallbacks()`, `useSessionUserInterfaceCallbacks()` or `usePresentation()` needs nothing, and so does a test that renders through `renderUserInterface` or `renderSessionUserInterface`, whose `getBenchmark` answers `null` and whose `getAssessment` answers with no results. A callbacks object built by hand, or a `PresentationValue` passed to `PresentationContext.Provider`, stops compiling until it has both:
721
+
722
+ ```tsx
723
+ const callbacks = {
724
+ ...yourCallbacks,
725
+ getBenchmark: async () => null,
726
+ getAssessment: async (identifier: string) => ({
727
+ identifier,
728
+ level: 'participant' as const,
729
+ min: 0,
730
+ max: 100,
731
+ bands: [],
732
+ results: [],
733
+ }),
734
+ };
735
+ ```
736
+
737
+ Better still, render through the helpers, as [1.3](#13-let-the-render-helpers-build-your-callbacks) describes, so the next addition needs nothing either.
738
+
703
739
  ### Optional: import the SDK's agent guidance in `CLAUDE.md`
704
740
 
705
741
  A new package's `CLAUDE.md` no longer holds a copy of the SDK's guidance. Its first line imports the copy that ships with `@seriousgaming/sdk-tools`, so the guidance always matches the installed version, and the rest of the file is the package's own. An older package keeps the copy it was scaffolded with, which goes stale with every upgrade and, in a package that began as the starter game, describes the lemonade stand after a reskin.
@@ -25,8 +25,8 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
25
25
  - [`changelog-0.x.md`](changelog-0.x.md): Every release before 1.0, from 0.0.1 to 0.6.0, kept as history.
26
26
  - [`changelog.md`](changelog.md): All notable changes to the Serious Gaming SDK are recorded here.
27
27
  - [`cli-and-dev-server.md`](cli-and-dev-server.md), about 15k characters: The dev server runs your game on your own machine, with every screen in the browser, and the CLI plays and inspects the same session from the terminal.
28
- - [`cli-error-codes.md`](cli-error-codes.md), about 33k characters: Every code a failed `seriousgaming-sdk` command can report.
29
- - [`cli-reference.md`](cli-reference.md), about 163k characters: Every `seriousgaming-sdk` command and flag, in one place.
28
+ - [`cli-error-codes.md`](cli-error-codes.md), about 34k characters: Every code a failed `seriousgaming-sdk` command can report.
29
+ - [`cli-reference.md`](cli-reference.md), about 168k characters: Every `seriousgaming-sdk` command and flag, in one place.
30
30
  - [`cli-simulation-testing.md`](cli-simulation-testing.md), about 11k characters: Play a game from the terminal: configure it, start a session, make decisions, advance ticks, and read the state back as JSON.
31
31
  - [`environment-variables.md`](environment-variables.md), about 10k characters: A single reference for every environment variable the dev server and CLI read.
32
32
  - [`getting-started.md`](getting-started.md), about 11k characters: Scaffold the starter game, play it in the dev server, change one thing, and see the change.
@@ -35,18 +35,20 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
35
35
  ## Concepts
36
36
 
37
37
  - [`concepts/index.md`](concepts/index.md), about 9k characters: The model behind the SDK on one page, and how its parts fit together.
38
- - [`concepts/terminology.md`](concepts/terminology.md), about 26k characters: Definitions of the terms used across the SDK, the CLI, the dev server, and these docs.
38
+ - [`concepts/terminology.md`](concepts/terminology.md), about 27k characters: Definitions of the terms used across the SDK, the CLI, the dev server, and these docs.
39
39
 
40
40
  ## Guides
41
41
 
42
42
  - [`guides/index.md`](guides/index.md), about 5k characters: Each guide is the one page for a resource kind or a topic: it explains the model, then serves as the reference, with every field, every option, and the rules behind them.
43
43
  - [`guides/ai-facilitation.md`](guides/ai-facilitation.md), about 14k characters: A facilitator running your game may have an AI agent beside them: something they can ask 'how is Team B doing', 'why has their profit fallen', or 'set their unit price to 3.53'.
44
+ - [`guides/assessments.md`](guides/assessments.md), about 17k characters: An assessment is a score the engine gives each participant, or each team, placed in a band such as 'developing' or 'expert' and judged a pass or not.
45
+ - [`guides/benchmarks.md`](guides/benchmarks.md), about 15k characters: A benchmark lets a debrief compare a team with everyone who has played the game, not just the other teams in the room.
44
46
  - [`guides/capabilities.md`](guides/capabilities.md), about 20k characters: Capabilities hold your game's state: named groups of variables that the engine and screens read and write.
45
47
  - [`guides/designing-a-game.md`](guides/designing-a-game.md), about 13k characters: A serious game teaches by letting people act and then see what their actions caused.
46
48
  - [`guides/designing-screens.md`](guides/designing-screens.md), about 12k characters: What a good simulation screen looks like, whatever the brand: how to decide what a screen should be before you build it, and how to check it afterwards.
47
49
  - [`guides/endpoints.md`](guides/endpoints.md), about 29k characters: An endpoint is a named, server-side handler that a caller invokes by identifier: one of the game's own user interfaces, or a caller outside the game, such as a facilitator's AI agent or a platform API, when the endpoint allows it.
48
- - [`guides/engine-testing.md`](guides/engine-testing.md), about 28k characters: Test your whole game in-process: no dev server, no browser, and no LLM API key required, because service callbacks are stubbed by default.
49
- - [`guides/engine.md`](guides/engine.md), about 33k characters: The engine is the logic that moves your game forward: it sets up the board, then plays one round each tick.
50
+ - [`guides/engine-testing.md`](guides/engine-testing.md), about 30k characters: Test your whole game in-process: no dev server, no browser, and no LLM API key required, because service callbacks are stubbed by default.
51
+ - [`guides/engine.md`](guides/engine.md), about 34k characters: The engine is the logic that moves your game forward: it sets up the board, then plays one round each tick.
50
52
  - [`guides/file-handling.md`](guides/file-handling.md), about 28k characters: Ship files with your game or let participants upload them, then show them in any UI and read them in logic, all through one reference scheme.
51
53
  - [`guides/games.md`](guides/games.md), about 7k characters: Shape the game as a whole: how many rounds it runs, how teams form, which languages it speaks, and where participants wait.
52
54
  - [`guides/global-settings.md`](guides/global-settings.md), about 4k characters: The global settings file lets you store API keys and defaults once, in a single user-owned file, so every project picks them up.
@@ -61,7 +63,7 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
61
63
  - [`guides/scenario-editor.md`](guides/scenario-editor.md), about 10k characters: The `scenario_editor` slot holds the screen people use to build new scenarios for a released game, without rebuilding it.
62
64
  - [`guides/scenarios.md`](guides/scenarios.md), about 31k characters: A scenario is a named set of settings overrides and static assets that makes a distinct flavour of a game: a different storyline, difficulty preset, or themed variant.
63
65
  - [`guides/session-game-flow.md`](guides/session-game-flow.md), about 20k characters: How a session UI drives the session: ticks, the timer, host overlays, undo and reset, the waiting room, the language, the roster, and the participant list.
64
- - [`guides/session-hooks.md`](guides/session-hooks.md), about 15k characters: Every hook a session UI reads its data and callbacks from, and the messages the host sends it.
66
+ - [`guides/session-hooks.md`](guides/session-hooks.md), about 16k characters: Every hook a session UI reads its data and callbacks from, and the messages the host sends it.
65
67
  - [`guides/session.md`](guides/session.md), about 23k characters: The session UI is the facilitator's view of the whole room: every team's position side by side, with the controls to run the session.
66
68
  - [`guides/settings.md`](guides/settings.md), about 34k characters: Settings are a game's read-only parameters: a price, a difficulty, a round length, a menu, an answer key.
67
69
  - [`guides/setup.md`](guides/setup.md), about 16k characters: The `setup` slot holds the small form a facilitator fills in when they create a session.
@@ -69,25 +71,27 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
69
71
  - [`guides/starter-game.md`](guides/starter-game.md), about 18k characters: `new package` hands you Lemonade Stand, a complete game rather than an empty shell.
70
72
  - [`guides/testing.md`](guides/testing.md), about 34k characters: Test your engine's logic and your user interfaces, so a broken rule or a broken screen fails on your machine rather than in front of a room.
71
73
  - [`guides/theming-and-branding.md`](guides/theming-and-branding.md), about 11k characters: Dress every surface of your game in the host's colours, logo and fonts, so a game run by a white-label host looks like that host's product.
72
- - [`guides/tick-controller.md`](guides/tick-controller.md), about 30k characters: A tick controller makes ticks happen on their own, on a schedule your logic decides, and can say when the game is finished.
74
+ - [`guides/tick-controller.md`](guides/tick-controller.md), about 33k characters: A tick controller makes ticks happen on their own, on a schedule your logic decides, and can say when the game is finished.
73
75
  - [`guides/type-safety.md`](guides/type-safety.md), about 16k characters: The SDK generates TypeScript types from your schemas, so a misspelt variable fails when you build rather than in front of a room.
74
76
  - [`guides/ui-files-and-llms.md`](guides/ui-files-and-llms.md), about 13k characters: How a game UI links to static assets, uploads and shows files, reads an asset's contents, and reaches an LLM through an endpoint to build a chat.
75
77
  - [`guides/ui-participants.md`](guides/ui-participants.md), about 15k characters: How a game UI reads who is playing: the current participant, their team, observers and walkthroughs, and the controls that let a team join, name itself, and fix a participant's name.
76
78
  - [`guides/ui-styling.md`](guides/ui-styling.md), about 11k characters: How a game UI handles language, theme, and screen size, and how to customise the Vite build that serves and bundles it.
77
79
  - [`guides/ui-ticks.md`](guides/ui-ticks.md), about 15k characters: How a game UI ends a round and shows the time left: requesting a tick, awaiting a write or tick and handling a `MutationError`, and driving a countdown from the tick timer.
78
- - [`guides/ui.md`](guides/ui.md), about 17k characters: The game UI is what each participant sees and plays: where they read the situation, make decisions, and see what those decisions caused.
79
- - [`guides/upgrading.md`](guides/upgrading.md), about 68k characters: This guide takes a game package on 0.6 to 1.0, in 13 steps.
80
+ - [`guides/ui.md`](guides/ui.md), about 18k characters: The game UI is what each participant sees and plays: where they read the situation, make decisions, and see what those decisions caused.
81
+ - [`guides/upgrading.md`](guides/upgrading.md), about 72k characters: This guide takes a game package on 0.6 to 1.0, in 13 steps.
80
82
  - [`guides/validators.md`](guides/validators.md), about 25k characters: A validator is a read-only gate on what a participant does: a context write before it is applied, and a request for the next tick before it runs.
81
83
  - [`guides/waiting-room.md`](guides/waiting-room.md), about 14k characters: The waiting room is the holding screen participants see while a session is parked, and you can replace the host's stock panel with your own.
82
84
 
83
85
  ## Recipes
84
86
 
85
- - [`recipes/index.md`](recipes/index.md), about 7k characters: Each recipe is one task, start to finish: prerequisites, numbered steps, a way to check it worked, and fixes for what usually goes wrong.
87
+ - [`recipes/index.md`](recipes/index.md), about 8k characters: Each recipe is one task, start to finish: prerequisites, numbered steps, a way to check it worked, and fixes for what usually goes wrong.
86
88
  - [`recipes/act-on-the-session-from-an-endpoint.md`](recipes/act-on-the-session-from-an-endpoint.md), about 4k characters: Let one endpoint call do what a facilitator would otherwise do in several steps, such as posting a notice, closing the waiting room and starting the next round, under your game's own rules.
87
89
  - [`recipes/adapt-a-game-for-walkthroughs.md`](recipes/adapt-a-game-for-walkthroughs.md), about 6k characters: A walkthrough is a disposable second run of your game beside the session, for demonstrating it: one team, one participant, always from tick 0, and isolated from the session in both directions.
88
90
  - [`recipes/adapt-ui-for-observers.md`](recipes/adapt-ui-for-observers.md), about 4k characters: An observer is a facilitator watching one team's live game UI without joining as a team member.
89
91
  - [`recipes/call-endpoint-from-ui.md`](recipes/call-endpoint-from-ui.md), about 6k characters: Call a server-side endpoint from any of your game's screens and handle its response or its failure.
90
92
  - [`recipes/check-a-package-from-a-script.md`](recipes/check-a-package-from-a-script.md), about 5k characters: Validate a package and play a few ticks from CI or an AI agent, and turn each failure into the file and line to fix.
93
+ - [`recipes/create-assessment.md`](recipes/create-assessment.md), about 6k characters: Score each participant or each team from the engine, place the score in bands such as 'developing' and 'expert', and show the result on a screen.
94
+ - [`recipes/create-benchmark.md`](recipes/create-benchmark.md), about 6k characters: Record a team's outcomes from the engine, and show a debrief how they compare with everyone who has played the game.
91
95
  - [`recipes/create-capability.md`](recipes/create-capability.md), about 3k characters: Define a named slice of the game's state that the engine and screens read and write.
92
96
  - [`recipes/create-endpoint.md`](recipes/create-endpoint.md), about 7k characters: Add a server-side handler your screens, or callers outside the game, can invoke by name with a validated request and response.
93
97
  - [`recipes/create-engine.md`](recipes/create-engine.md), about 4k characters: Write the engine that moves the game on each tick: here, one that reads a price and writes the day's revenue.
@@ -139,11 +143,12 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
139
143
  - [`api/index.md`](api/index.md), about 8k characters: Every type, function, hook and component your game imports, one page per entry point.
140
144
  - [`api/deck.md`](api/deck.md), about 8k characters: Every export of `@seriousgaming/deck`, with the declaration it is published with.
141
145
  - [`api/sdk-commands.md`](api/sdk-commands.md), about 7k characters: What a client may ask a session to do.
142
- - [`api/sdk-e2e.md`](api/sdk-e2e.md), about 11k characters: End-to-end testing helpers for Serious Gaming SDK consumers.
146
+ - [`api/sdk-e2e.md`](api/sdk-e2e.md), about 12k characters: End-to-end testing helpers for Serious Gaming SDK consumers.
143
147
  - [`api/sdk-projection.md`](api/sdk-projection.md), about 5k characters: The one documented shape of a session's observable state.
144
148
  - [`api/sdk-testing.md`](api/sdk-testing.md), about 7k characters: Helpers for unit-testing a game's logic without a runtime.
145
- - [`api/sdk-tools-client.md`](api/sdk-tools-client.md), about 14k characters: Programmatic API for testing a game in-process.
149
+ - [`api/sdk-tools-client.md`](api/sdk-tools-client.md), about 16k characters: Programmatic API for testing a game in-process.
146
150
  - [`api/sdk-tools-playwright.md`](api/sdk-tools-playwright.md), about 3k characters: Playwright for a game's browser tests: a dev server for each worker.
151
+ - [`api/sdk-tools-vite.md`](api/sdk-tools-vite.md), under 1k characters: What a game's Vite and Vitest configs need from the SDK.
147
152
  - [`api/sdk-ui-testing.md`](api/sdk-ui-testing.md), about 8k characters: Every export of `@seriousgaming/sdk/ui/testing`, with the declaration it is published with.
148
153
  - [`api/sdk-ui.md`](api/sdk-ui.md), about 36k characters: Every export of `@seriousgaming/sdk/ui`, with the declaration it is published with.
149
- - [`api/sdk.md`](api/sdk.md), about 59k characters: Every export of `@seriousgaming/sdk`, with the declaration it is published with.
154
+ - [`api/sdk.md`](api/sdk.md), about 79k characters: Every export of `@seriousgaming/sdk`, with the declaration it is published with.
@@ -0,0 +1,124 @@
1
+ # Create an assessment
2
+
3
+ Score each participant or each team from the engine, place the score in bands such as 'developing' and 'expert', and show the result on a screen.
4
+
5
+ **Keywords:** create assessment, new assessment, score participants, grade, bands, pass mark, learning outcomes, LMS, xAPI, getAssessment, requires assessments
6
+
7
+ ## Prerequisites
8
+
9
+ - A package with an engine, and a screen to show the result on (the game UI, the session UI or the presentation)
10
+ - What the score is made from already held in capabilities, such as a team's profit or, for a per-participant score, a capability keyed by participant id
11
+
12
+ ## Steps
13
+
14
+ 1. Create the assessment from JSON. Its identifier is its directory name:
15
+
16
+ ```bash
17
+ pnpm run sdk new assessment '{
18
+ "definition": {
19
+ "identifier": "teamwork",
20
+ "level": "participant",
21
+ "min": 0,
22
+ "max": 100,
23
+ "bands": [
24
+ { "id": "developing", "from": 0 },
25
+ { "id": "competent", "from": 50, "passing": true },
26
+ { "id": "expert", "from": 80, "passing": true }
27
+ ]
28
+ }
29
+ }'
30
+ ```
31
+
32
+ Use `"level": "team"` for one score per team, which every member receives.
33
+
34
+ 2. List it in the engine's `assessments`:
35
+
36
+ ```bash
37
+ pnpm run sdk update engine --patch '[
38
+ { "op": "add", "path": "/definition/assessments", "value": ["teamwork"] }
39
+ ]'
40
+ ```
41
+
42
+ The engine's `types.ts` now exports `Assessments`.
43
+
44
+ 3. List the feature in `seriousgaming.sdk.json`:
45
+
46
+ ```bash
47
+ pnpm run sdk update package --patch '[
48
+ { "op": "add", "path": "/requires/-", "value": "assessments" }
49
+ ]'
50
+ ```
51
+
52
+ If the manifest has no `requires` yet, use `{ "op": "add", "path": "/requires", "value": ["assessments"] }`.
53
+
54
+ 4. Score it from `Run`, typing it with `Assessments` as the sixth type parameter (after the engine's state and benchmarks, or `never` for each):
55
+
56
+ ```typescript
57
+ import type { RunFunction } from '@seriousgaming/sdk';
58
+
59
+ import type { Assessments, Callbacks, Context, Settings } from './types';
60
+
61
+ export const Run: RunFunction<
62
+ Context,
63
+ Settings,
64
+ Callbacks,
65
+ never,
66
+ never,
67
+ Assessments
68
+ > = async ({ context, participants }) => ({
69
+ capabilities: context,
70
+ assessments: {
71
+ teamwork: Object.fromEntries(
72
+ participants.map((p) => [
73
+ p.id,
74
+ { score: context.peerMarks.ByParticipant[p.id] ?? 0 },
75
+ ])
76
+ ),
77
+ },
78
+ });
79
+ ```
80
+
81
+ A team-level assessment takes one result instead: `{ score: 72, feedback: 'Strong finish' }`. Add `final: true` once a result will not change; every result becomes final when play ends anyway.
82
+
83
+ 5. Read the result on a screen. A participant's screen receives only their own result and their team's:
84
+
85
+ ```typescript
86
+ const { getAssessment } = useUserInterfaceCallbacks();
87
+ const report = await getAssessment('teamwork');
88
+ const mine = report.results[0];
89
+ ```
90
+
91
+ Show `mine.band` in your own words, and `mine.passed`. Both are `null` for an assessment without bands, and `mine` is absent until the engine scores this participant.
92
+
93
+ 6. Optionally, let a scenario move the bands, under the built-in `assessments` settings:
94
+
95
+ ```json
96
+ { "settings": { "assessments": { "teamwork": { "competent": { "from": 60 } } } } }
97
+ ```
98
+
99
+ To let the facilitator move them for one session, add `"assessments"` to the setup UI's `configures`.
100
+
101
+ ## Verify
102
+
103
+ - `pnpm run sdk build --validate-only` passes, with no `ASSESSMENT_UNWRITTEN` warning
104
+ - `pnpm run sdk init`, then `pnpm run sdk tick` prints no warning, and `pnpm run --silent sdk view --full --json` shows the scores under the team's `assessments`
105
+ - The screen shows the band once a round has been played
106
+
107
+ ## Troubleshooting
108
+
109
+ | Problem | Solution |
110
+ | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
111
+ | `FEATURE_UNDECLARED` at `/requires` | Add `"assessments"` to `requires` in `seriousgaming.sdk.json` |
112
+ | `ASSESSMENT_UNWRITTEN` | Add the identifier to the engine's `assessments`, or delete the assessment |
113
+ | `REFERENCE_UNKNOWN` on the engine's `assessments` | The engine names an assessment the package does not have: create it, or remove the name |
114
+ | The build says the bands are out of order | List bands lowest first, the first at `min`, each above the last and none above `max`. A scenario's overrides must keep that order too |
115
+ | A setup UI's change to a band is refused | It would leave the bands out of order: keep each band starting above the one below it and below the one above |
116
+ | `sdk tick` prints 'The write was dropped' | The write did not match: a score out of range or missing, an unknown field, or a participant not on the team. The round still ran |
117
+ | `getAssessment` rejects | The identifier is not a declared assessment, or the screen is a presentation shown without a session |
118
+ | `getAssessment` answers with no results | The engine has not scored the participant or team yet, or (on a participant's screen) it scored somebody else |
119
+
120
+ ## Related
121
+
122
+ - [Assessments guide](../guides/assessments.md): the model, scoring rules, bands as settings, who sees what, and reporting to a learning management system
123
+ - [Create a benchmark](create-benchmark.md)
124
+ - [Create an engine](create-engine.md)
@@ -0,0 +1,115 @@
1
+ # Create a benchmark
2
+
3
+ Record a team's outcomes from the engine, and show a debrief how they compare with everyone who has played the game.
4
+
5
+ **Keywords:** create benchmark, new benchmark, compare with other sessions, how you compare, debrief comparison, getBenchmark, sample.json, requires benchmarks
6
+
7
+ ## Prerequisites
8
+
9
+ - A package with an engine, and a screen to show the comparison on (the game UI, the session UI or the presentation)
10
+ - The figures you want to compare already held in capabilities, such as a team's profit
11
+
12
+ ## Steps
13
+
14
+ 1. Create the benchmark from JSON. Its identifier is its directory name:
15
+
16
+ ```bash
17
+ pnpm run sdk new benchmark '{
18
+ "definition": {
19
+ "identifier": "outcome",
20
+ "revision": 1,
21
+ "tags": ["difficulty"],
22
+ "fields": {
23
+ "NetProfit": { "type": "number", "description": "Profit over the whole game" },
24
+ "Round1Pricing": { "enum": ["premium", "match", "discount"] }
25
+ }
26
+ }
27
+ }'
28
+ ```
29
+
30
+ This writes `benchmarks/outcome/benchmark.sdk.json` and a `sample.json` beside it for the dev server.
31
+
32
+ 2. List it in the engine's `benchmarks`:
33
+
34
+ ```bash
35
+ pnpm run sdk update engine --patch '[
36
+ { "op": "add", "path": "/definition/benchmarks", "value": ["outcome"] }
37
+ ]'
38
+ ```
39
+
40
+ The engine's `types.ts` now exports `Benchmarks`.
41
+
42
+ 3. List the feature in `seriousgaming.sdk.json`:
43
+
44
+ ```bash
45
+ pnpm run sdk update package --patch '[
46
+ { "op": "add", "path": "/requires/-", "value": "benchmarks" }
47
+ ]'
48
+ ```
49
+
50
+ If the manifest has no `requires` yet, use `{ "op": "add", "path": "/requires", "value": ["benchmarks"] }`.
51
+
52
+ 4. Write the record from `Run`, typing it with `Benchmarks` as the fifth type parameter (after the engine's `state`, or `never`):
53
+
54
+ ```typescript
55
+ import type { RunFunction } from '@seriousgaming/sdk';
56
+
57
+ import type { Benchmarks, Callbacks, Context, Settings } from './types';
58
+
59
+ export const Run: RunFunction<Context, Settings, Callbacks, never, Benchmarks> = async ({
60
+ context,
61
+ settings,
62
+ }) => {
63
+ const next = await playRound(context, settings);
64
+ return {
65
+ capabilities: next,
66
+ benchmarks: {
67
+ outcome: {
68
+ NetProfit: next.finance.TotalProfit,
69
+ tags: { difficulty: settings.setup.Difficulty },
70
+ },
71
+ },
72
+ };
73
+ };
74
+ ```
75
+
76
+ To count only finished teams, write on the last round, or hold `excluded: true` until then. See [Deciding when values count](../guides/benchmarks.md#deciding-when-values-count).
77
+
78
+ 5. Read the pooled figures on a screen, trying the narrowest filter first and falling back to everyone. Build the filter from settings the screen reads:
79
+
80
+ ```typescript
81
+ const { getBenchmark } = useUserInterfaceCallbacks();
82
+ const stats = await getBenchmark('outcome', {
83
+ where: [{ difficulty: settings.setup.Difficulty }, {}],
84
+ });
85
+ const profit = stats?.fields.NetProfit;
86
+ const median = profit?.kind === 'number' ? profit.p50 : undefined;
87
+ ```
88
+
89
+ Show the comparison only when `median` is defined, and label it from `stats.matched`. The answer may be `null`, and any figure but `count` may be missing.
90
+
91
+ 6. Edit `benchmarks/outcome/sample.json` so its figures look like your game.
92
+
93
+ ## Verify
94
+
95
+ - `pnpm run sdk build --validate-only` passes, with no `BENCHMARK_UNWRITTEN` warning
96
+ - `pnpm run sdk init`, then `pnpm run sdk tick` prints no warning, and `pnpm run --silent sdk view --full --json` shows the record under the team's `benchmarks`
97
+ - The screen shows the figures from `sample.json`; delete a figure, or the file, and it still renders
98
+
99
+ ## Troubleshooting
100
+
101
+ | Problem | Solution |
102
+ | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
103
+ | `FEATURE_UNDECLARED` at `/requires` | Add `"benchmarks"` to `requires` in `seriousgaming.sdk.json` |
104
+ | `BENCHMARK_UNWRITTEN` | Add the identifier to the engine's `benchmarks`, or delete the benchmark |
105
+ | `REFERENCE_UNKNOWN` on the engine's `benchmarks` | The engine names a benchmark the package does not have: create it, or remove the name |
106
+ | `sdk tick` prints 'The write was dropped' | The write did not match the benchmark: an undeclared field, option or tag, or a number that is not finite. The round still ran |
107
+ | A session-level benchmark fails the build | Only an aggregate engine can write one, under `shared`. Remove `level` to make it per team |
108
+ | `getBenchmark` rejects | The identifier is not a declared benchmark, or `sample.json` is not valid JSON in the right shape; the message names which |
109
+ | `getBenchmark` answers `null` in the dev server | The benchmark has no `sample.json`. Recreate it from the shape in the guide |
110
+
111
+ ## Related
112
+
113
+ - [Benchmarks guide](../guides/benchmarks.md): the model, writing and reading rules, tags and filters, and testing
114
+ - [Create an engine](create-engine.md)
115
+ - [Create a presentation](create-presentation.md)
@@ -60,7 +60,7 @@ pnpm run sdk view
60
60
  | The build reports no engine | Check `engine/engine.sdk.json` exists |
61
61
  | The build warns that only the engine can end the game | There is no `maxTicks`; expected for a goal-based game |
62
62
  | A patch fails on a missing path | Use `add` for a field the manifest does not have yet, `replace` for one it has |
63
- | Detailed errors | Run `pnpm run sdk build --validate-only --json` |
63
+ | Detailed errors | Run `pnpm run --silent sdk build --validate-only --json` |
64
64
 
65
65
  ## Related
66
66
 
@@ -21,24 +21,20 @@ Two copies of React in one page (a library that bundles its own, such as `@react
21
21
  Create `vite.config.ts` alongside your `seriousgaming.sdk.json`:
22
22
 
23
23
  ```typescript
24
+ import { REACT_CONTEXT_PACKAGES } from '@seriousgaming/sdk-tools/vite';
24
25
  import { defineConfig } from 'vite';
25
26
 
26
27
  export default defineConfig({
27
28
  resolve: {
28
- dedupe: [
29
- 'react',
30
- 'react-dom',
31
- '@emotion/react',
32
- '@emotion/styled',
33
- '@seriousgaming/sdk',
34
- '@seriousgaming/deck',
35
- ],
29
+ dedupe: [...REACT_CONTEXT_PACKAGES],
36
30
  },
37
31
  });
38
32
  ```
39
33
 
40
34
  `resolve.dedupe` tells Vite to resolve these packages to the single copy at the project root,
41
- however many paths in the dependency tree lead to them.
35
+ however many paths in the dependency tree lead to them. `REACT_CONTEXT_PACKAGES` is the SDK's
36
+ list of every package that holds React context a surface reads: React, Emotion, the SDK and the
37
+ deck. Read it from the SDK rather than writing it out, so it keeps up when the SDK gains one.
42
38
 
43
39
  If your package was created with `sdk new package` and already has a `vite.config.ts`, add
44
40
  entries to its `dedupe` list rather than creating a second file.
@@ -59,24 +55,17 @@ Add a package to `dedupe` whenever you install a library that:
59
55
  - Lists React (or Emotion) as a **peer dependency**, and
60
56
  - Also `require()`s that peer internally in its own bundled code
61
57
 
62
- Or any package that holds React context and that more than one path leads to, as the SDK does. A package created with `sdk new package` lists React, Emotion, the SDK and the deck already, in both `vite.config.ts` and `vitest.config.ts`.
58
+ Or any package that holds React context and that more than one path leads to, as the SDK does. A package created with `sdk new package` spreads `REACT_CONTEXT_PACKAGES` already, in both `vite.config.ts` and `vitest.config.ts`.
63
59
 
64
60
  Example with additional libraries:
65
61
 
66
62
  ```typescript
63
+ import { REACT_CONTEXT_PACKAGES } from '@seriousgaming/sdk-tools/vite';
67
64
  import { defineConfig } from 'vite';
68
65
 
69
66
  export default defineConfig({
70
67
  resolve: {
71
- dedupe: [
72
- 'react',
73
- 'react-dom',
74
- '@emotion/react',
75
- '@emotion/styled',
76
- '@seriousgaming/sdk',
77
- '@seriousgaming/deck',
78
- '@react-three/fiber',
79
- ],
68
+ dedupe: [...REACT_CONTEXT_PACKAGES, '@react-three/fiber'],
80
69
  },
81
70
  });
82
71
  ```
@@ -24,6 +24,8 @@ New to the SDK? Start with [Getting started](../getting-started.md), which plays
24
24
  - [Create a facilitator guide](create-guide.md): markdown facilitation content shown on the facilitator's page
25
25
  - [Make a guide follow the scenario](make-a-guide-follow-the-scenario.md): show settings values in the guide, and content only some scenarios need
26
26
  - [Create a presentation](create-presentation.md): the facilitator's slide deck, live with the session's results and exportable to PDF and PowerPoint
27
+ - [Create a benchmark](create-benchmark.md): record a team's outcomes and show a debrief how they compare with everyone who has played
28
+ - [Create an assessment](create-assessment.md): score each participant or team from the engine, in bands, and show the result on a screen
27
29
 
28
30
  ## User interfaces
29
31
 
@@ -12,7 +12,7 @@
12
12
  * owns the state and this module owns the rules, and each can be read without
13
13
  * the other's bookkeeping in the way.
14
14
  */
15
- import type { ResolvedPackageManifest, ContextDeletePath, Participant } from '@seriousgaming/sdk';
15
+ import { type AssessmentDefinition, type BenchmarkDefinition, type ResolvedPackageManifest, type ContextDeletePath, type Participant } from '@seriousgaming/sdk';
16
16
  import { type EngineResultRead } from './logic-result';
17
17
  import type { GameContext } from './types';
18
18
  /** A resource's capability declaration, which projection and write checks read. */
@@ -20,6 +20,8 @@ export interface Declaration {
20
20
  reads?: string[];
21
21
  writes?: string[];
22
22
  }
23
+ /** Benchmark records by identifier, as a context holds them under its reserved key. */
24
+ export type BenchmarkRecords = Record<string, Record<string, unknown>>;
23
25
  /** What folding a result needs to know about the game it lands in. */
24
26
  export interface CompositionScope {
25
27
  /** Each capability's schema defaults, the base a returned capability merges over. */
@@ -28,7 +30,37 @@ export interface CompositionScope {
28
30
  sharedIds: ReadonlySet<string>;
29
31
  /** The engine's declaration, which an engine result's `deletes` are held to. */
30
32
  engine: Declaration;
33
+ /** The benchmarks the engine declares, by identifier: the only ones it may write. */
34
+ benchmarks: ReadonlyMap<string, BenchmarkDefinition>;
35
+ /** Where a dropped benchmark or assessment write is reported; the call carries on (§6.16, §6.17). */
36
+ warn: (message: string) => void;
37
+ /** The assessments the engine declares, by identifier: the only ones it may write. */
38
+ assessments?: ReadonlyMap<string, AssessmentDefinition>;
39
+ /** The participants of a team as the call saw them: the only ones it may score (§6.17.1). */
40
+ participantIdsOf?: (teamId: string) => ReadonlySet<string>;
31
41
  }
42
+ /**
43
+ * Fold a result's assessment writes over the team's results it was called
44
+ * with (§6.17.1), and return the results to keep, or `undefined` when the
45
+ * result wrote none.
46
+ *
47
+ * Checked and dropped as benchmark writes are, and for the same reason: a
48
+ * result leaves the session, and a round failed in front of the room costs
49
+ * more than one missing score.
50
+ */
51
+ export declare function foldAssessmentWrites(label: string, raw: unknown, current: unknown, participantIds: ReadonlySet<string>, scope: Pick<CompositionScope, 'assessments' | 'warn'>): Record<string, unknown> | undefined;
52
+ /**
53
+ * Fold a result's benchmark writes over the records it was called with
54
+ * (§6.16), and return the records to keep, or `undefined` when the result
55
+ * wrote none.
56
+ *
57
+ * Unlike a capability, every write is checked against its benchmark, because
58
+ * a record leaves the session. Unlike every other check on a result, a write
59
+ * that fails it is dropped, whole, with a warning, and the call carries on: a
60
+ * round failed in front of the room over a figure for the pool costs far more
61
+ * than the figure is worth.
62
+ */
63
+ export declare function foldBenchmarkWrites(label: string, raw: unknown, current: unknown, level: 'team' | 'session', scope: Pick<CompositionScope, 'benchmarks' | 'warn'>): Record<string, Record<string, unknown>> | undefined;
32
64
  /**
33
65
  * Whether a proposed mutation changes the value of any capability in
34
66
  * `reads`.
@@ -112,16 +144,19 @@ export declare function foldLogicResult(capabilities: GameContext, deletes: read
112
144
  export declare function aggregateArgs(contexts: GameContext[], identities: {
113
145
  teamId: string;
114
146
  index: number;
115
- }[], declaration: Declaration, store: GameContext, sharedIds: ReadonlySet<string>, participants: Participant[]): {
147
+ }[], declaration: Declaration, store: GameContext, sharedIds: ReadonlySet<string>, participants: Participant[], writesBenchmarks?: boolean, writesAssessments?: boolean): {
116
148
  shared: {
117
149
  context: GameContext;
118
150
  state: unknown;
151
+ benchmarks?: BenchmarkRecords;
119
152
  };
120
153
  teams: {
121
154
  teamId: string;
122
155
  index: number;
123
156
  context: GameContext;
124
157
  state: unknown;
158
+ benchmarks?: BenchmarkRecords;
159
+ assessments?: Record<string, unknown>;
125
160
  }[];
126
161
  participants: Participant[];
127
162
  };
@@ -130,7 +165,7 @@ export declare function aggregateArgs(contexts: GameContext[], identities: {
130
165
  * capabilities as a patch, and its `state`, when it returned one, as the
131
166
  * team's new engine state whole.
132
167
  */
133
- export declare function applyEngineResult(label: string, result: EngineResultRead, contextBefore: GameContext, scope: CompositionScope): GameContext;
168
+ export declare function applyEngineResult(label: string, result: EngineResultRead, contextBefore: GameContext, scope: CompositionScope, teamId?: string): GameContext;
134
169
  /**
135
170
  * Fold an aggregate result into the team contexts it was called with, write
136
171
  * its shared slice to the canonical store, and mirror the store into every
@@ -150,7 +185,7 @@ export declare function applyEngineResult(label: string, result: EngineResultRea
150
185
  export declare function applyAggregateResult(read: {
151
186
  shared: EngineResultRead;
152
187
  teams: EngineResultRead[];
153
- }, contextsBefore: GameContext[], engineIdentifier: string, phase: 'InitAggregate' | 'RunAggregate', scope: CompositionScope, store: GameContext): {
188
+ }, contextsBefore: GameContext[], engineIdentifier: string, phase: 'InitAggregate' | 'RunAggregate', scope: CompositionScope, store: GameContext, teamIds?: readonly string[]): {
154
189
  contexts: GameContext[];
155
190
  store: GameContext;
156
191
  };
@@ -20,6 +20,19 @@ import type { GameContext } from './types';
20
20
  export declare const ENGINE_STATE_KEY = "$engineState";
21
21
  /** The session-wide engine state, inside the shared store and every view. */
22
22
  export declare const SHARED_ENGINE_STATE_KEY = "$sharedEngineState";
23
+ /**
24
+ * A team's benchmark records (§6.16), inside that team's stored context, kept
25
+ * beside the engine's state for the same reasons: snapshotted and rewound with
26
+ * the tick, and dropped by every projection to anything but the engine.
27
+ */
28
+ export declare const BENCHMARKS_KEY = "$benchmarks";
29
+ /** The session's own benchmark records, inside the shared store and every view. */
30
+ export declare const SHARED_BENCHMARKS_KEY = "$sharedBenchmarks";
31
+ /**
32
+ * A team's assessment results (§6.17), inside that team's stored context, kept
33
+ * beside the engine's state for the same reasons as benchmark records.
34
+ */
35
+ export declare const ASSESSMENTS_KEY = "$assessments";
23
36
  /** Whether a context key is engine state rather than a capability. */
24
37
  export declare function isReservedKey(key: string): boolean;
25
38
  /** A context with the engine's state removed, for anything that is not the engine. */
@@ -34,6 +34,7 @@ export declare class GameExecutor {
34
34
  * contexts it was handed (§11). Read by the session straight after a tick.
35
35
  */
36
36
  private lastTickCompletion;
37
+ private warnings;
37
38
  private waitingRoomOpen;
38
39
  private deps;
39
40
  /** `meta`, the roster, callbacks and bounds: what every logic call shares. */
@@ -116,6 +117,21 @@ export declare class GameExecutor {
116
117
  operationNow(): number;
117
118
  /** How a result folds into a board, for the game as it is loaded now. */
118
119
  private composition;
120
+ /** Whether the engine declares assessments, and so is handed and may return them (§6.17). */
121
+ private writesAssessments;
122
+ /** Whether the engine declares benchmarks, and so is handed and may return them (§6.16). */
123
+ private writesBenchmarks;
124
+ /**
125
+ * The `benchmarks` and `assessments` arguments of an `Init` or `Run` on
126
+ * `context`: its team's records and results, each passed only to an engine
127
+ * that declares some.
128
+ */
129
+ private recordArgs;
130
+ /**
131
+ * What went wrong without failing anything since the last call, such as a
132
+ * benchmark write that was dropped (§6.16), for the operation to report.
133
+ */
134
+ takeWarnings(): string[];
119
135
  /**
120
136
  * Fold an aggregate result into the team contexts and the canonical store.
121
137
  * See {@link applyAggregateResult}.