@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
@@ -27,10 +27,77 @@ Entries are grouped into: **Breaking Changes**, **Added**, **Changed**,
27
27
  **Deprecated**, **Removed**, **Fixed** and **Security**. Releases before 1.0
28
28
  are in the [0.x changelog](changelog-0.x.md).
29
29
 
30
+ From 1.11, a release that changed what `sdk new package` writes, a shipped
31
+ `.claude/rules/` file or the agent guidance also has a **Scaffold changes**
32
+ section: one line per file, saying what changed, why, and after `Adopt:`
33
+ whether an existing package should copy the change. Nothing updates a package's
34
+ own copies, so read those lines for every release you cross.
35
+
30
36
  ---
31
37
 
32
38
  ## [Unreleased]
33
39
 
40
+ ## [1.12.0] — 2026-11-16
41
+
42
+ ### Added
43
+
44
+ - A host may now suspend automatic ticking on a session nobody has used for at least 24 hours and 100 automatic ticks, and wakes it on its own the next time somebody uses it. `TimerState` gains optional `dormant` and `dormantAt` so a UI can show it, and the dev drawer's **Make dormant** control (or the `makeDormant` command) shows you the dormant state without waiting a day. See [Unattended sessions](guides/tick-controller.md#unattended-sessions)
45
+ - **Benchmarks: compare a team with everyone who has played.** A new resource, `benchmarks/<name>/benchmark.sdk.json`, declares a few numeric or option fields the engine records for each team (or for the session). The platform pools the records anonymously across sessions of the game, and a debrief reads back counts, medians and percentiles. A game that declares one lists `"benchmarks"` in `requires`. See [Benchmarks](guides/benchmarks.md) and [Create a benchmark](recipes/create-benchmark.md)
46
+ - **`sdk new benchmark`, `sdk update benchmark` and `sdk delete benchmark`.** `new` takes JSON only, and also writes a `sample.json` of placeholder figures beside the bundle
47
+ - **The engine writes benchmarks.** An engine that lists benchmarks in its bundle's new `benchmarks` receives each team's records as `benchmarks`, and returns writes under `benchmarks` beside `capabilities`: a team's in `Init`, `Run` or an aggregate `teams` entry, the session's under an aggregate result's `shared`. The engine's `types.ts` exports `Benchmarks` and `SessionBenchmarks`, which `RunFunction` and `InitializationFunction` take as their fifth type parameter, and the aggregate functions after their two state parameters. A write that does not match its benchmark is dropped with a warning, and the round carries on
48
+ - **`getBenchmark(identifier, query?)` on the game UI, the waiting room UI, the session UI and the presentation**, which reads a benchmark's pooled statistics, filtered by tag values tried narrowest first. It answers `null` when there is nothing to show, and any figure but `count` may be missing. The dev server answers it from `sample.json`
49
+ - **`BENCHMARK_UNWRITTEN`**, a build warning for a benchmark the engine does not list, which could never hold a value
50
+ - **Assessments: score each participant or team, in bands.** A new resource, `assessments/<name>/assessment.sdk.json`, declares one measure the engine scores for every participant or every team, within a range, and the bands that say what a score means, such as 'developing' and 'expert', and which of them are a pass. The shape follows the learning-record standards (xAPI, cmi5, SCORM and LTI), so a platform can report results to a learning management system. A game that declares one lists `"assessments"` in `requires`. See [Assessments](guides/assessments.md) and [Create an assessment](recipes/create-assessment.md)
51
+ - **`sdk new assessment`, `sdk update assessment` and `sdk delete assessment`**, which take JSON
52
+ - **The engine scores assessments.** An engine that lists assessments in its bundle's new `assessments` receives each team's results as `assessments`, and returns writes under `assessments` beside `capabilities`, typed by the generated `Assessments`, which `RunFunction` and `InitializationFunction` take as their sixth type parameter. A write that does not match its assessment, such as a score out of range or a participant not on the team, is dropped with a warning, and the round carries on
53
+ - **Bands are settings.** When an assessment declares bands, the game gains a built-in `assessments` settings resource holding each band's threshold and pass, so a scenario or a session can move a pass mark without a new release. A setup UI that lists `"assessments"` in `configures` moves them for one session; a change that would put the bands out of order is refused, there, in a scenario draft and by `sdk configure`
54
+ - **A participant's own scores follow them to a new team.** Their participant-level results move with them, so the new team's engine carries on from what they had
55
+ - **`getAssessment(identifier)` on the game UI, the waiting room UI, the session UI and the presentation**, which reads an assessment's results, each with its score, scaled score, band, pass and whether it is final. A participant's screen receives only their own result and their team's
56
+ - **`ASSESSMENT_UNWRITTEN`**, a build warning for an assessment the engine does not list, which could never hold a result
57
+ - **Benchmark records and assessment results in the session state.** `sdk view --full --json` and a test session's `state()` show each team's `benchmarks` and the session's `sharedBenchmarks`, and each team's `assessments`, and a tick that dropped a benchmark or assessment write returns it in `warnings`, which `sdk tick` prints
58
+
59
+ ### Changed
60
+
61
+ - **`UserInterfaceCallbacks`, `SessionUserInterfaceCallbacks` and the presentation's `usePresentation()` value gain `getBenchmark` and `getAssessment` as required members.** These are outside semantic versioning, so a game reading them through the hooks needs nothing, and `renderUserInterface` and `renderSessionUserInterface` supply a `getBenchmark` that answers `null` and a `getAssessment` that answers with no results. A test that builds a callbacks object or a `PresentationValue` by hand adds both. See [1.12: add `getBenchmark` and `getAssessment` to a hand-built callbacks object](guides/upgrading.md#112-add-getbenchmark-and-getassessment-to-a-hand-built-callbacks-object)
62
+
63
+ ### Scaffold changes
64
+
65
+ - `guidance.md`: says what benchmarks are, that only the engine writes them, and that a game lists `"benchmarks"` in `requires`, and points at `guides/benchmarks.md`. Adopt: no, it updates with the installed version
66
+ - `guidance.md`: says what assessments are, that only the engine scores them, that a game lists `"assessments"` in `requires`, and that bands are settings, and points at `guides/assessments.md`. Adopt: no, it updates with the installed version
67
+
68
+ ## [1.11.0] — 2026-11-11
69
+
70
+ ### Added
71
+
72
+ - **`pnpm check` in a new package**: one script that validates the package, typechecks, lints, and runs the unit and engine tests, stopping at the first that fails. It is the package's own script, so add steps to it. The guidance now tells an agent to run it after every change. To add it to an existing package, see [Catch an older package's scaffold up](guides/upgrading.md#111-catch-an-older-packages-scaffold-up)
73
+ - **The lint rules for logic files ship in the SDK.** A package's `.oxlintrc.json` extends `./node_modules/@seriousgaming/sdk-tools/dist/oxlint/logic.json` (also exported as `@seriousgaming/sdk-tools/oxlint/logic.json`), which refuses the globals the production runtime lacks in engine, hook, validator, endpoint and tick controller logic, and exempts tests. A package no longer keeps its own copy of the list, so the list keeps up with the SDK
74
+ - **`REACT_CONTEXT_PACKAGES` from `@seriousgaming/sdk-tools/vite`**: the packages that hold React context, for `resolve.dedupe` in `vite.config.ts` and `vitest.config.ts`. `sdk build` dedupes the same list itself, which now includes `@seriousgaming/sdk` and `@seriousgaming/deck`
75
+ - **An engine test sees where logic threw.** A `createTestSession` result that was refused because logic threw carries `logicError`: the resource, the message, the tick and team, and the `file`, `line` and `column` of the source, as `sdk tick` reports them. It was already there at run time; it is now typed, as `TestMutationResult` and `LogicErrorLocation` from `@seriousgaming/sdk-tools/client`, and documented in [Engine testing](guides/engine-testing.md#ticking-and-asserting)
76
+ - **A hint on three more failures.** `RESOURCE_NOT_FOUND` from `update` names the resources of that type the package holds, `MANIFEST_NOT_FOUND` says where to run the command, and `PORT_IN_USE` points at `sdk dev status` and `--port auto`
77
+ - **The conformance suite carries the specification and the manifest schema it was built from**, in the installed package's `dist/`, so a runtime that pins the suite gets all three at one revision. The specification's changelog now maps each SDK release to the revision it implements. See the suite's README
78
+
79
+ ### Changed
80
+
81
+ - **`sdk new package --empty` writes `teams.mode` into the manifest**, as `"independent"`, which is what an absent mode already meant. A game that needs shared state now has the field in front of it to change
82
+ - **The starter game's engine test is typed and plays every scenario.** It passes the engine's generated `Context` to `createTestSession`, so it reads `team.context.results.Day` without a cast, and ends with a test that starts each scenario on disk and plays a day
83
+
84
+ ### Fixed
85
+
86
+ - **The guides agree on what leaving a key out does.** A variable logic returns replaces the old one whole, so an entry of a map is gone if the returned map leaves it out. The engine guide and the agent guidance both said it never was. `deletes` is still the way to remove one: it works however the map was built
87
+ - **Every documented `--json` command uses `pnpm run --silent`**, so no pnpm banner precedes the JSON. Two examples did not
88
+
89
+ ### Scaffold changes
90
+
91
+ - `package.json`: gains a `check` script that runs `sdk build --validate-only`, `typecheck`, `lint`, `test:run` and `test:engine` in order. It gives an agent one command to run after every change. Adopt: yes, copy the script, and drop its last step if the package has no engine tests
92
+ - `.oxlintrc.json` (`oxlintrc.json.template`): extends `./node_modules/@seriousgaming/sdk-tools/dist/oxlint/logic.json` in place of its own `no-restricted-globals` override and the override that turned it off for tests. The list of globals the production runtime lacks now comes from the installed SDK. Adopt: yes, add the `extends` line and delete the two overrides
93
+ - `vite.config.ts` and `vitest.config.ts`: `resolve.dedupe` is `[...REACT_CONTEXT_PACKAGES]`, imported from `@seriousgaming/sdk-tools/vite`, in place of a written-out list. Adopt: optional, and keep any package of your own after the spread
94
+ - `.oxfmtrc.json` (`oxfmtrc.json.template`): `ignorePatterns` gains `lib/`, `test-results/` and `playwright-report/`, so the formatter stops rewriting build output and test reports. Adopt: yes
95
+ - `.claude/settings.json` (`settings.json.template`): allows `pnpm check` without a prompt, beside the steps it runs. Adopt: yes, add the line
96
+ - `README.md`: lists `pnpm check` under 'Running the tests'. Adopt: no
97
+ - `guidance.md`: the loop is `pnpm check`; `tick --no-server` is a smoke test, since engine tests run in the same restricted runtime; session examples pass `--summary`; `cli-reference.md`, `changelog.md` and `guides/upgrading.md` are never to be read whole; and removing a key is described as it behaves. Adopt: no, it updates with the installed version
98
+ - `.claude/rules/workflow-update-sdk-version.md`: step 7 reads this section of every release crossed, oldest first, and step 6 runs `pnpm check`. Adopt: yes, replace the file, so later upgrades find these lines
99
+ - `.claude/rules/workflow-create-engine.md`, `workflow-create-user-interface.md` and `workflow-test-engine-or-ui.md`: the verify step is `pnpm check`. Adopt: optional
100
+
34
101
  ## [1.10.0] — 2026-11-07
35
102
 
36
103
  ### Added
@@ -12,7 +12,7 @@ The codes are the contract: branch on the code, never on the message. A code is
12
12
  | --------- | ------------- | ------------------- | ----- |
13
13
  | 1 | `internal` | Internal error | 1 |
14
14
  | 2 | `usage` | Usage error | 16 |
15
- | 3 | `package` | Invalid package | 36 |
15
+ | 3 | `package` | Invalid package | 38 |
16
16
  | 4 | `refused` | Refused by the game | 12 |
17
17
  | 5 | `environment` | Environment | 19 |
18
18
 
@@ -64,6 +64,8 @@ A code marked as a diagnostic also appears in a failure's `diagnostics`, one fin
64
64
  | `LAYOUT_OUTDATED` | A directory or bundle file sits where an earlier version of the SDK kept it. The hint says where it goes now. | Yes |
65
65
  | `FEATURE_UNSUPPORTED` | The manifest's `requires` names an optional feature this version of the SDK does not support. | Yes |
66
66
  | `FEATURE_UNDECLARED` | The package uses an optional feature its manifest's `requires` does not list, so a runtime without the feature would run it with part of it missing. | Yes |
67
+ | `BENCHMARK_UNWRITTEN` | A benchmark is not in the engine's `benchmarks`, so nothing writes it and it never holds a value. A warning. | Yes |
68
+ | `ASSESSMENT_UNWRITTEN` | An assessment is not in the engine's `assessments`, so nothing scores it and it never holds a result. A warning. | Yes |
67
69
  | `REFERENCE_UNKNOWN` | A `reads`, `writes`, `settings`, `configures` or `endpoints` entry names something the package does not declare. | Yes |
68
70
  | `SETTINGS_UNKNOWN` | A scenario overrides a settings resource the package does not declare. | Yes |
69
71
  | `SETTINGS_UNKNOWN_KEY` | A scenario overrides a key that its settings resource does not declare. | Yes |
@@ -143,6 +145,8 @@ The codes a diagnostic carries. `LOGIC_ERROR` is only ever a diagnostic: it sits
143
145
  | `LAYOUT_OUTDATED` | A directory or bundle file sits where an earlier version of the SDK kept it. The hint says where it goes now. |
144
146
  | `FEATURE_UNSUPPORTED` | The manifest's `requires` names an optional feature this version of the SDK does not support. |
145
147
  | `FEATURE_UNDECLARED` | The package uses an optional feature its manifest's `requires` does not list, so a runtime without the feature would run it with part of it missing. |
148
+ | `BENCHMARK_UNWRITTEN` | A benchmark is not in the engine's `benchmarks`, so nothing writes it and it never holds a value. A warning. |
149
+ | `ASSESSMENT_UNWRITTEN` | An assessment is not in the engine's `assessments`, so nothing scores it and it never holds a result. A warning. |
146
150
  | `REFERENCE_UNKNOWN` | A `reads`, `writes`, `settings`, `configures` or `endpoints` entry names something the package does not declare. |
147
151
  | `SETTINGS_UNKNOWN` | A scenario overrides a settings resource the package does not declare. |
148
152
  | `SETTINGS_UNKNOWN_KEY` | A scenario overrides a key that its settings resource does not declare. |
@@ -220,6 +220,8 @@ Without `--json`, each diagnostic that names a file is printed under the error a
220
220
  | `LAYOUT_OUTDATED` | A directory or bundle file sits where an earlier version of the SDK kept it. The hint says where it goes now. |
221
221
  | `FEATURE_UNSUPPORTED` | The manifest's `requires` names an optional feature this version of the SDK does not support. |
222
222
  | `FEATURE_UNDECLARED` | The package uses an optional feature its manifest's `requires` does not list, so a runtime without the feature would run it with part of it missing. |
223
+ | `BENCHMARK_UNWRITTEN` | A benchmark is not in the engine's `benchmarks`, so nothing writes it and it never holds a value. A warning. |
224
+ | `ASSESSMENT_UNWRITTEN` | An assessment is not in the engine's `assessments`, so nothing scores it and it never holds a result. A warning. |
223
225
  | `REFERENCE_UNKNOWN` | A `reads`, `writes`, `settings`, `configures` or `endpoints` entry names something the package does not declare. |
224
226
  | `SETTINGS_UNKNOWN` | A scenario overrides a settings resource the package does not declare. |
225
227
  | `SETTINGS_UNKNOWN_KEY` | A scenario overrides a key that its settings resource does not declare. |
@@ -864,14 +866,82 @@ Declare the endpoint on every UI that may call it by adding the identifier to th
864
866
  }
865
867
  ```
866
868
 
869
+ #### Create a benchmark
870
+
871
+ ```text
872
+ pnpm run sdk new benchmark [definition] [options]
873
+ ```
874
+
875
+ Create a new benchmark.
876
+
877
+ | Option | Default | Description |
878
+ | -------------------------- | --------------------- | -------------------------------------------------------- |
879
+ | `-w, --working-dir [PATH]` | the current directory | The working directory to create the benchmark in. |
880
+ | `-f, --file [PATH]` | | Path to a JSON file containing the benchmark definition. |
881
+
882
+ Example:
883
+
884
+ ```bash
885
+ pnpm run sdk new benchmark '{
886
+ "definition": {
887
+ "identifier": "outcome",
888
+ "revision": 1,
889
+ "tags": ["difficulty"],
890
+ "fields": {
891
+ "NetProfit": { "type": "number", "description": "Profit over the whole game" },
892
+ "Round1Pricing": { "enum": ["premium", "match", "discount"] }
893
+ }
894
+ }
895
+ }'
896
+ ```
897
+
898
+ Creates `benchmarks/<identifier>/benchmark.sdk.json`, and a `sample.json` beside it with placeholder figures for every field, which the dev server answers `getBenchmark` from. A benchmark is created from JSON only: with no JSON the command fails with `USAGE_MISSING_INPUT` and prints the expected shape. Like a capability, its bundle carries `definition` alone, and `definition.identifier` names the directory.
899
+
900
+ The benchmark does nothing until the engine lists it in `benchmarks`, and the game lists `"benchmarks"` in `requires`. `delete benchmark` removes it from the engine's `benchmarks` too. See the [benchmarks guide](./guides/benchmarks.md) and [Create a benchmark](./recipes/create-benchmark.md).
901
+
902
+ #### Create an assessment
903
+
904
+ ```text
905
+ pnpm run sdk new assessment [definition] [options]
906
+ ```
907
+
908
+ Create a new assessment.
909
+
910
+ | Option | Default | Description |
911
+ | -------------------------- | --------------------- | --------------------------------------------------------- |
912
+ | `-w, --working-dir [PATH]` | the current directory | The working directory to create the assessment in. |
913
+ | `-f, --file [PATH]` | | Path to a JSON file containing the assessment definition. |
914
+
915
+ Example:
916
+
917
+ ```bash
918
+ pnpm run sdk new assessment '{
919
+ "definition": {
920
+ "identifier": "teamwork",
921
+ "level": "participant",
922
+ "min": 0,
923
+ "max": 100,
924
+ "bands": [
925
+ { "id": "developing", "from": 0 },
926
+ { "id": "competent", "from": 50, "passing": true },
927
+ { "id": "expert", "from": 80, "passing": true }
928
+ ]
929
+ }
930
+ }'
931
+ ```
932
+
933
+ Creates `assessments/<identifier>/assessment.sdk.json`. An assessment is created from JSON only: with no JSON the command fails with `USAGE_MISSING_INPUT` and prints the expected shape. Like a capability, its bundle carries `definition` alone, and `definition.identifier` names the directory.
934
+
935
+ The assessment does nothing until the engine lists it in `assessments`, and the game lists `"assessments"` in `requires`. `delete assessment` removes it from the engine's `assessments` too. See the [assessments guide](./guides/assessments.md) and [Create an assessment](./recipes/create-assessment.md).
936
+
867
937
  ### Notes on resource creation
868
938
 
869
- **The `rootDirectory` field.** Most `new` commands require `rootDirectory` in the root object, not inside `definition`, and it is usually `"."`. `new capability` and `new settings` are the exceptions: their bundles carry `definition` alone, and a `rootDirectory` is rejected.
939
+ **The `rootDirectory` field.** Most `new` commands require `rootDirectory` in the root object, not inside `definition`, and it is usually `"."`. `new capability`, `new settings`, `new benchmark` and `new assessment` are the exceptions: their bundles carry `definition` alone, and a `rootDirectory` is rejected.
870
940
 
871
941
  - **Engine and tick controller**: `{ "definition": {...}, "logic": {...}, "rootDirectory": "." }`
872
942
  - **User interfaces, including setup and the scenario editor**: `{ "definition": {...}, "rootDirectory": ".", "ui": { "entrypoint": "index.html" } }`
873
943
 
874
- **Identifiers.** For the nine slot kinds (`engine`, `ui`, `session`, `waiting_room`, `presentation`, `setup`, `scenario_editor`, `tick_controller`, and `guide`) any authored identifier is ignored, since the slot names the resource. For the plural kinds (`capability`, `settings`, `endpoint`, `hook`, `validator`, and `scenario`) `definition.identifier` is required: it names the directory to create, and is stripped from the bundle that is written.
944
+ **Identifiers.** For the nine slot kinds (`engine`, `ui`, `session`, `waiting_room`, `presentation`, `setup`, `scenario_editor`, `tick_controller`, and `guide`) any authored identifier is ignored, since the slot names the resource. For the plural kinds (`capability`, `settings`, `benchmark`, `assessment`, `endpoint`, `hook`, `validator`, and `scenario`) `definition.identifier` is required: it names the directory to create, and is stripped from the bundle that is written.
875
945
 
876
946
  **Nothing to wire.** A package declares whatever sits under the conventional directories, and a game uses whatever its package declares, so the directory `new` creates is the whole of the wiring.
877
947
 
@@ -883,6 +953,8 @@ Every resource type has an `update` command, and so does the package:
883
953
  | ------------------------------------------------------- | ------------------------------------- | --------------------------------------------- |
884
954
  | `update package [definition] [options]` | Update a package. | `--working-dir`, `--file`, `--patch`, `--yes` |
885
955
  | `update capability <identifier> [definition] [options]` | Update a capability. | `--working-dir`, `--file`, `--patch`, `--yes` |
956
+ | `update benchmark <identifier> [definition] [options]` | Update a benchmark. | `--working-dir`, `--file`, `--patch`, `--yes` |
957
+ | `update assessment <identifier> [definition] [options]` | Update an assessment. | `--working-dir`, `--file`, `--patch`, `--yes` |
886
958
  | `update settings <identifier> [definition] [options]` | Update a settings resource. | `--working-dir`, `--file`, `--patch`, `--yes` |
887
959
  | `update engine [definition] [options]` | Update an engine. | `--working-dir`, `--file`, `--patch`, `--yes` |
888
960
  | `update ui [definition] [options]` | Update a user interface. | `--working-dir`, `--file`, `--patch`, `--yes` |
@@ -1052,6 +1124,8 @@ pnpm run sdk update package '{
1052
1124
  | Command | What it does | Options |
1053
1125
  | ------------------------------------------ | ------------------------------------- | ------------------------ |
1054
1126
  | `delete capability <identifier> [options]` | Delete a capability. | `--working-dir`, `--yes` |
1127
+ | `delete benchmark <identifier> [options]` | Delete a benchmark. | `--working-dir`, `--yes` |
1128
+ | `delete assessment <identifier> [options]` | Delete an assessment. | `--working-dir`, `--yes` |
1055
1129
  | `delete settings <identifier> [options]` | Delete a settings resource. | `--working-dir`, `--yes` |
1056
1130
  | `delete engine [options]` | Delete an engine. | `--working-dir`, `--yes` |
1057
1131
  | `delete ui [options]` | Delete a user interface. | `--working-dir`, `--yes` |
@@ -28,6 +28,8 @@ A game holds exactly one of some kinds, each in a fixed **slot** named for it, a
28
28
  | [Presentation](../guides/presentation.md) | `presentation/` | The facilitator's slide deck |
29
29
  | [Facilitator guide](../guides/guide.md) | `guide/` | Markdown chapters for whoever runs the session |
30
30
  | [Scenario](../guides/scenarios.md) | `scenarios/<name>/` | A variant of the game: settings overrides and static assets |
31
+ | [Benchmark](../guides/benchmarks.md) | `benchmarks/<name>/` | Outcomes the engine records, pooled across sessions for comparison |
32
+ | [Assessment](../guides/assessments.md) | `assessments/<name>/` | A score the engine gives each participant or team, in bands |
31
33
 
32
34
  ## How a session runs
33
35
 
@@ -121,6 +121,14 @@ A read-only check on every mutation a UI submits, run before the mutation is app
121
121
 
122
122
  A server-side handler, exported as `Handle` (or as `Plan` and `Respond`, for one that answers in two phases), that a UI calls by identifier with `callEndpoint`. It validates its request and response against schemas. An endpoint is **team**-scoped (the default: it acts on the calling team's context) or **session**-scoped (it acts on the session as a whole), and one that declares `writes` can change state. An endpoint is also how a UI reaches callbacks such as `generateText`, and one whose `visibility` is `external` can be called from outside the game, for example by a facilitator's AI agent or a platform API. See [Endpoints](../guides/endpoints.md).
123
123
 
124
+ ### Assessment
125
+
126
+ One measure the engine scores for each participant or each team, declared under `assessments/<name>/`: a score within a declared range, placed in bands such as 'developing' or 'expert' that say whether it is a pass. A scenario or a session may move the bands, and a screen reads results with `getAssessment`. See [Assessments](../guides/assessments.md).
127
+
128
+ ### Benchmark
129
+
130
+ A small, named record of outcomes and decisions that the engine writes for each team (or for the session), declared under `benchmarks/<name>/`. The platform pools records anonymously across sessions of the same game, and a screen reads back statistics with `getBenchmark`, never another team's record. See [Benchmarks](../guides/benchmarks.md).
131
+
124
132
  ### Context
125
133
 
126
134
  The whole game state at a point in time, as an object keyed by capability identifier:
@@ -202,6 +210,10 @@ Any state-changing request a UI sends: a context write (`setData`), a tick, an u
202
210
 
203
211
  Logic in the `tick_controller` slot that decides automatic tick timing and when the game is over. It exports `GetTickController`, which returns `{ enabled, intervalMs, complete }`: with `enabled` true, the runtime ticks every `intervalMs` milliseconds, and `complete: true` ends the game for good. See [Tick controllers](../guides/tick-controller.md).
204
212
 
213
+ ### Dormant session
214
+
215
+ A session whose automatic ticking the host has suspended because nothing used it for at least 24 hours and 100 automatic ticks. It wakes on its own the next time somebody or something uses it: a surface opening, a write, a facilitator action or an endpoint call. See [Unattended sessions](../guides/tick-controller.md#unattended-sessions).
216
+
205
217
  ## User interfaces
206
218
 
207
219
  A game has up to six UIs, each in its own slot: the game UI, the waiting room UI, the session UI, setup, the scenario editor, and the presentation. Each is a React app the host mounts in a sandboxed iframe and talks to over a message channel. **Surface** is the umbrella word for any of them as mounted by the host; name a particular one by its UI name below.
@@ -0,0 +1,248 @@
1
+ # Assessments
2
+
3
+ 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. A debrief can show it, and a platform can one day send it to a learning management system.
4
+
5
+ This guide explains what an assessment holds and who sees it, then covers declaring one, scoring it from the engine, moving its bands for a scenario or a session, and reading results on a screen.
6
+
7
+ **Keywords:** assessment, assessments, score, scores, grade, grades, band, bands, pass mark, passing, learning outcomes, LMS, xAPI, Tin Can, cmi5, SCORM, LTI, learning record store, getAssessment, requires assessments, ASSESSMENT_UNWRITTEN
8
+
9
+ ## The model
10
+
11
+ A game already keeps every team's results in its capabilities, in whatever shape suits it. Nothing outside the game can tell a good result from a poor one, and nothing records how each person did. An assessment adds both, in a shape every runtime understands.
12
+
13
+ - **The game owns the score.** The engine works it out and writes it, as a number between the assessment's `min` and `max`. The runtime never invents or changes one
14
+ - **The bands say what a score means.** The assessment declares them, lowest first, and marks the ones that count as a pass. The runtime places each score in a band and decides pass or fail from it, so a screen never works that out for itself
15
+ - **The bands are settings.** Their thresholds and passes are defaults that a scenario or a session can change, as they change any setting, without a new release of the game
16
+ - **One score per participant, or one per team.** A team-level score belongs to every participant on the team
17
+ - **The engine is the only writer.** A facilitator's judgement, such as a mark for teamwork, reaches the engine as any other input does, and the engine scores it
18
+ - **Results are keyed by participant id.** The id carries nothing personal. Only the platform links it to a person, and only for a learner who arrived from a learning management system
19
+ - **Each surface sees only what it should.** A participant's screen sees their own result and their team's; the session UI and the presentation see everyone's
20
+
21
+ The shape follows what the learning-record standards (xAPI, cmi5, SCORM and LTI) agree on: a score with its range, a scaled score worked out from it, a pass that is separate from whether the result is final, and a line of feedback.
22
+
23
+ ## Declaring an assessment
24
+
25
+ An assessment lives at `assessments/<name>/assessment.sdk.json`, named by its directory, and is created from JSON:
26
+
27
+ ```bash
28
+ pnpm run sdk new assessment '{
29
+ "definition": {
30
+ "identifier": "teamwork",
31
+ "description": "How well each participant worked with their team",
32
+ "level": "participant",
33
+ "min": 0,
34
+ "max": 100,
35
+ "bands": [
36
+ { "id": "developing", "from": 0 },
37
+ { "id": "competent", "from": 50, "passing": true },
38
+ { "id": "expert", "from": 80, "passing": true }
39
+ ]
40
+ }
41
+ }'
42
+ ```
43
+
44
+ | Field | What it holds |
45
+ | ------------- | ----------------------------------------------------------------------------------------------------------------------------- |
46
+ | `level` | `'participant'`: a score for each participant. `'team'`: one score for the team, which every member receives |
47
+ | `min`, `max` | The range a score must fall in. `max` is above `min` |
48
+ | `bands` | Up to 10, lowest first. The first starts at `min`, each starts above the one before it, and none starts above `max`. Optional |
49
+ | `description` | What the assessment measures, for whoever reads the results |
50
+
51
+ Each band has an `id` (lower case letters, digits and underscores), a `from` (the lowest score in it), and optionally `passing: true` and a `description`. A score falls in the last band whose `from` is at or below it. Without bands, a result has no band and no pass or fail, only a score.
52
+
53
+ Then wire it in, in two places:
54
+
55
+ 1. **List it in the engine's `assessments`:**
56
+
57
+ ```bash
58
+ pnpm run sdk update engine --patch '[
59
+ { "op": "add", "path": "/definition/assessments", "value": ["teamwork"] }
60
+ ]'
61
+ ```
62
+
63
+ The engine's generated `types.ts` then exports `Assessments`, with one entry per assessment the engine declares
64
+
65
+ 2. **List the `assessments` feature in `requires`** in `seriousgaming.sdk.json`, so a runtime that cannot hold results refuses the package rather than the first round that scores one:
66
+
67
+ ```json
68
+ {
69
+ "requires": ["assessments"]
70
+ }
71
+ ```
72
+
73
+ ### Choosing what to assess
74
+
75
+ Assess the few things a facilitator or a learning team would want to report: an overall result, and perhaps one or two named skills. Each assessment is one measure, and a game may declare up to 20. An assessment is not a record of everything a participant did.
76
+
77
+ Choose a range that reads naturally, such as 0 to 100, and put the meaning in the bands. A screen labels each band in its own words, so the band ids are names, not text for the learner.
78
+
79
+ ## Scoring from the engine
80
+
81
+ `Init` and `Run` receive `assessments` beside `context`: this team's results, as the engine last wrote them. They return writes under `assessments`, beside `capabilities`. Type them with the generated `Assessments`, the sixth type parameter of `RunFunction` and `InitializationFunction` (after the engine's state and benchmarks, either of which may be `never`):
82
+
83
+ ```typescript
84
+ import type { RunFunction } from '@seriousgaming/sdk';
85
+
86
+ import type { Assessments, Callbacks, Context, Settings } from './types';
87
+
88
+ export const Run: RunFunction<Context, Settings, Callbacks, never, never, Assessments> = async ({
89
+ context,
90
+ participants,
91
+ assessments,
92
+ }) => ({
93
+ capabilities: context,
94
+ assessments: {
95
+ // A team-level assessment: one result.
96
+ profit: { score: Math.min(100, context.finance.ProfitShare) },
97
+ // A participant-level assessment: a result per participant id.
98
+ teamwork: Object.fromEntries(
99
+ participants.map((p) => [p.id, { score: context.peerMarks.ByParticipant[p.id] ?? 0 }])
100
+ ),
101
+ },
102
+ });
103
+ ```
104
+
105
+ A result has a `score`, and may have a `feedback` line for the learner (at most 500 characters) and `final: true`. A write is a patch over what the engine wrote before:
106
+
107
+ - Each field it carries replaces that field. A result's first write must carry a `score`, and no write can remove one
108
+ - `feedback: null` or `final: null` removes that field
109
+ - `null` in place of a result removes it, and `null` in place of a participant-level assessment's whole write removes every result in it
110
+
111
+ A participant-level write may score only the participants the call was given in `participants`, which are the team's. It may remove a result for anybody the team holds.
112
+
113
+ An aggregate engine writes each team's results under that team's entry in `teams`. There are no session-level assessments, so a write under `shared` is dropped.
114
+
115
+ ### Tracking what a participant did
116
+
117
+ The engine sees a team's context, and context belongs to the team, not to any one person. To score people individually, keep what each one did in a capability keyed by participant id. A UI knows its own participant through `useUserInterfaceParticipant()`, so it can write its own entry:
118
+
119
+ ```typescript
120
+ const me = useUserInterfaceParticipant();
121
+ await updateData({ contributions: { ByParticipant: { [me.id]: { Proposals: 3 } } } });
122
+ ```
123
+
124
+ The engine then reads `context.contributions.ByParticipant` and scores each participant from it.
125
+
126
+ ### A facilitator's judgement
127
+
128
+ There is no built-in place for a facilitator to enter a mark. When a game wants one, such as a mark for leadership, the session UI writes it to a capability, directly or through an endpoint, and the engine turns it into a score on the next round. The engine stays the only writer, and the mark goes through the same checks as any other score.
129
+
130
+ ### A bad write is dropped, not fatal
131
+
132
+ The runtime checks each write: the assessment is declared by the engine, the score is a finite number within the range, `feedback` and `final` are the right types, there is no other field, and every participant scored is on the team. A write that fails is dropped whole, with a warning, and the round carries on: a round that fails in front of the room costs far more than one missing score. `sdk tick` prints the warning, and a test session returns it in `warnings`.
133
+
134
+ ### Marking a result final
135
+
136
+ A result is final when the engine marks it `final: true`, or when its team's play is over: the game is complete or has reached its tick limit. A game that scores only at the end needs to do nothing, because the last round's results become final when play ends. Mark a result final earlier when you know it will not change, such as when one team's factory closes.
137
+
138
+ Finality is part of the result, so undo takes it back: a facilitator who undoes the round that made a result final makes it provisional again.
139
+
140
+ ## Moving the bands for a scenario or a session
141
+
142
+ When any assessment declares bands, the build adds a built-in settings resource named `assessments`, beside the built-in `game` settings. It holds each band's `from` and `passing`, with the bundle's values as defaults. A scenario overrides them as it overrides any setting:
143
+
144
+ ```json
145
+ {
146
+ "definition": {
147
+ "settings": {
148
+ "assessments": {
149
+ "teamwork": {
150
+ "competent": { "from": 60 },
151
+ "expert": { "passing": false }
152
+ }
153
+ }
154
+ }
155
+ }
156
+ }
157
+ ```
158
+
159
+ A setup UI can do the same for one session, through `updateSettings`. The runtime then places scores in bands with the thresholds in force for that session, so the engine never needs to know.
160
+
161
+ To let the setup UI change them, list `"assessments"` in its `configures`. It spreads the values it was given, as for any setting, and the runtime keeps only what changed:
162
+
163
+ ```typescript
164
+ const { assessments } = settings;
165
+ await updateSettings({
166
+ assessments: {
167
+ ...assessments,
168
+ profitability: {
169
+ ...assessments.profitability,
170
+ steady: { ...assessments.profitability.steady, from: 60 },
171
+ },
172
+ },
173
+ });
174
+ ```
175
+
176
+ You cannot add or remove bands this way, only move them, and the bands must still ascend: each starts above the one before it, the first at the minimum score. The build refuses a scenario whose thresholds break that order, and the runtime refuses a session's change or a scenario draft's edit that would, so the write rejects and the settings stay as they were. Show the rejection's message, as for any refused setting. The build also refuses a package that declares an assessment and authors its own `settings/assessments/`.
177
+
178
+ ## Reading results on a screen
179
+
180
+ `useUserInterfaceCallbacks()` exposes `getAssessment(identifier)` on the game UI and the waiting room UI, and `useSessionUserInterfaceCallbacks()` and `usePresentation()` expose it on the session UI and the presentation. It is not gated by `uses`.
181
+
182
+ ```typescript
183
+ const { getAssessment } = useUserInterfaceCallbacks();
184
+ const report = await getAssessment('teamwork');
185
+ const mine = report.results[0];
186
+ if (mine) showBand(mine.band, mine.passed, mine.final);
187
+ ```
188
+
189
+ The answer carries the assessment's `level`, `min` and `max`, the `bands` in force, and `results`. Each result has its `teamId`, its `participantId` for a participant-level assessment, the `score`, a `scaled` score from 0 to 1, the `band` (or `null`), `passed` (or `null` without a band), any `feedback`, and whether it is `final`.
190
+
191
+ The host decides which results a screen receives, from who it is shown to:
192
+
193
+ | Screen | Receives |
194
+ | ------------------------------------- | ------------------------------------------------------------------------------------ |
195
+ | Game UI or waiting room, participant | Their own result of a participant-level assessment, their team's of a team-level one |
196
+ | Game UI or waiting room, observer | The results of the team being watched |
197
+ | Session UI, presentation in a session | Every result |
198
+
199
+ A team or participant the engine has not scored is simply absent. A presentation shown without a session has no results to read, and the call rejects. Read again after each round, for example in an effect that depends on `completedTicks`: the answer is a snapshot, not a subscription.
200
+
201
+ ## Participants who move team
202
+
203
+ A participant's results come from the team they are on. Once play is over, that is the team they finished on, which is a rule a facilitator can explain: you are graded with the team you finished with.
204
+
205
+ - **A team-level score stays with the team.** A participant who moves takes their new team's score
206
+ - **A participant-level score goes with the participant.** The runtime moves it to their new team, so its engine is handed the score built up so far, and a running average such as engagement carries on rather than starting again. An undo that puts the score back on the old team moves it across again
207
+
208
+ A participant who joins partway through has no score yet. A running share of rounds then counts the rounds before they joined as absences; to count only the rounds since they joined, keep each participant's first round in a capability keyed by participant id.
209
+
210
+ ## Reporting to a learning management system
211
+
212
+ The SDK does not send results anywhere. A platform may report them to a learning management system or learning record store, through xAPI, cmi5, SCORM, LTI or anything else, and the fields map onto those standards directly:
213
+
214
+ | Assessment | xAPI and cmi5 | SCORM 2004 | LTI grades |
215
+ | --------------------- | -------------------------------- | ----------------------------- | ---------------------------- |
216
+ | `score`, `min`, `max` | `result.score.raw`, `min`, `max` | `cmi.score.raw`, `min`, `max` | `scoreGiven`, `scoreMaximum` |
217
+ | `scaled` | `result.score.scaled` | `cmi.score.scaled` | |
218
+ | `passed` | `result.success` | `cmi.success_status` | |
219
+ | `final` | `result.completion` | `cmi.completion_status` | `gradingProgress` |
220
+ | `feedback` | `result.response` | | `comment` |
221
+ | `band` | An extension | | |
222
+
223
+ A platform that reports results reports a grade only once it is final, reports a team-level result for every participant on the team, and never reports a walkthrough. The game never learns who a learner is: it sees participant ids, and the platform holds the link to the learner.
224
+
225
+ ## Testing
226
+
227
+ - **The engine's writes.** In a unit test, assert on `result.assessments` from `Run`. To test a write that builds on the last, pass `assessments` beside the arguments `logicArgs.run` builds: `Run({ ...logicArgs.run({ context, settings }), assessments: { profit: { score: 40 } } })`
228
+ - **A whole game.** In an engine test, `session.state().teams[0].assessments` holds each team's results as the engine wrote them, and `session.send({ type: 'getAssessment', identifier: 'teamwork' })` answers as the session UI's read does, with bands and finality. Check `warnings` on what `tick()` returns, so a dropped write fails the test rather than going unnoticed
229
+ - **From the CLI.** `pnpm run --silent sdk view --full --json` shows each team's `assessments`, and `sdk tick` prints a warning for each dropped write
230
+ - **A screen.** The render helpers in `@seriousgaming/sdk/ui/testing` supply a `getAssessment` that answers with no results. Pass your own in `callbacks` to render a result: `renderUserInterface(<App />, { callbacks: { getAssessment: async () => report } })`
231
+
232
+ See [Engine testing](./engine-testing.md) and [Testing](./testing.md).
233
+
234
+ ## Rules the build checks
235
+
236
+ - A game that declares an assessment lists `"assessments"` in `requires` (`FEATURE_UNDECLARED`)
237
+ - `max` is above `min`; bands start at `min`, ascend and stay at or below `max`; there are at most 10, each with its own `id`
238
+ - A scenario's band overrides keep the bands in that order
239
+ - At most 20 assessments in a game
240
+ - Every name in the engine's `assessments` is an assessment the package has (`REFERENCE_UNKNOWN`)
241
+ - An assessment the engine does not list is a warning, `ASSESSMENT_UNWRITTEN`: nothing can score it
242
+ - A package with an assessment cannot author `settings/assessments/` (`SETTINGS_RESERVED`)
243
+
244
+ ## Next steps
245
+
246
+ - [Create an assessment](../recipes/create-assessment.md): the steps, in order
247
+ - [Benchmarks](./benchmarks.md): compare a team with everyone who has played, rather than score it
248
+ - [Settings](./settings.md): how scenarios and sessions override settings