@seriousgaming/sdk-tools 1.11.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 (192) hide show
  1. package/dist/agent/guidance.md +4 -0
  2. package/dist/{cli-F2D4GGUA.js → cli-2BKEIIA3.js} +66 -0
  3. package/dist/{cli-ZGCG6C22.js → cli-2QGTDHRX.js} +21 -21
  4. package/dist/{cli-SRXDLMXY.js → cli-2SDG3SZ7.js} +21 -21
  5. package/dist/{cli-DH35TZ2Q.js → cli-2VXP34R5.js} +2 -2
  6. package/dist/{cli-P3NUTOPK.js → cli-2W4B6PD5.js} +1 -1
  7. package/dist/{cli-WJVPSVF2.js → cli-2X7DKSXN.js} +24 -24
  8. package/dist/{cli-ATAJSIXH.js → cli-2ZP4N7HK.js} +19 -19
  9. package/dist/{cli-5O7XENQY.js → cli-3GJYZH4C.js} +5 -5
  10. package/dist/{cli-H6PP2MZT.js → cli-3GO3M2MX.js} +17 -13
  11. package/dist/{cli-HMDYG6PS.js → cli-3LDLUNME.js} +17 -17
  12. package/dist/{cli-BZOKZ7LP.js → cli-3WY6L2WP.js} +27 -27
  13. package/dist/{cli-REAM7LSC.js → cli-44MBABRD.js} +25 -25
  14. package/dist/{cli-5TTJWM2R.js → cli-4IO7MKLR.js} +20 -20
  15. package/dist/{cli-HNDFANQG.js → cli-4U2PY7W3.js} +1 -1
  16. package/dist/{cli-WQ7JBZNW.js → cli-4WI4LTBI.js} +2 -2
  17. package/dist/{cli-OTBCA54D.js → cli-55EIGGZK.js} +1 -1
  18. package/dist/{cli-FYPW25VD.js → cli-5AQV6FTL.js} +18 -18
  19. package/dist/{cli-RKPQLB7J.js → cli-5CW7BEU7.js} +3 -3
  20. package/dist/{cli-27TQVLVF.js → cli-5JUVHNZF.js} +12 -12
  21. package/dist/{cli-F3YJKP6D.js → cli-5KERL6HV.js} +9 -4
  22. package/dist/{cli-MSNSXVGF.js → cli-5KSA24NQ.js} +24 -24
  23. package/dist/{cli-5VZBFMCK.js → cli-5PIFO3EN.js} +8 -0
  24. package/dist/{cli-FT3X3D4P.js → cli-5QN2Z43X.js} +20 -20
  25. package/dist/cli-5XSPAA5X.js +69 -0
  26. package/dist/{cli-B2QAJ5RQ.js → cli-62KAYGXO.js} +20 -20
  27. package/dist/{cli-QPV3TYOM.js → cli-6IMV5ZZU.js} +26 -26
  28. package/dist/{cli-UULZSQBV.js → cli-6KWCIAN2.js} +764 -66
  29. package/dist/{cli-DQE7ITIR.js → cli-6NWETIX5.js} +20 -20
  30. package/dist/{cli-L7F4XKCB.js → cli-774W3MN5.js} +26 -26
  31. package/dist/cli-7BUD3VAD.js +16 -0
  32. package/dist/{cli-XNOAO6DY.js → cli-7KEP57S7.js} +12 -12
  33. package/dist/{cli-5UKWX3IU.js → cli-7OYFJMA6.js} +18 -18
  34. package/dist/{cli-WNHMJM3Z.js → cli-7ZNEDQ3G.js} +20 -20
  35. package/dist/{cli-5RRPUL6V.js → cli-AFK6OUID.js} +12 -12
  36. package/dist/{cli-6P6V2EHY.js → cli-AIYQFWXN.js} +25 -25
  37. package/dist/{cli-ERJNDBDH.js → cli-ARAAEWIQ.js} +2 -2
  38. package/dist/cli-AVQYV3N4.js +36 -0
  39. package/dist/{cli-TI2FOFPA.js → cli-B54Z6CXH.js} +16 -16
  40. package/dist/{cli-EEO5ZPAZ.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-4F24FUW6.js → cli-BPS2JG74.js} +20 -20
  44. package/dist/{cli-W3RG2MRI.js → cli-BVO55SR2.js} +2 -2
  45. package/dist/{cli-R5SNTPND.js → cli-CFH3JZP5.js} +21 -21
  46. package/dist/{cli-Q7QSWNY2.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-QEFYDXMH.js → cli-DZCLRZXJ.js} +1 -1
  54. package/dist/{cli-77T4LJQF.js → cli-EJ47IE45.js} +24 -24
  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-D3S7NJZ3.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-XOYUTNER.js → cli-HCXS5EXU.js} +25 -25
  65. package/dist/cli-HEUNNHDH.js +36 -0
  66. package/dist/{cli-G3TU6CP6.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-TLSTSZAC.js → cli-IO32YA5N.js} +26 -26
  70. package/dist/cli-IPTGZDBB.js +36 -0
  71. package/dist/{cli-OBLEROSC.js → cli-J25TYFKB.js} +19 -19
  72. package/dist/{cli-5ATO27Z4.js → cli-J7XYMEMX.js} +20 -20
  73. package/dist/{cli-X3TSTTYI.js → cli-JC5OJRID.js} +2 -2
  74. package/dist/{cli-25SJZI7N.js → cli-JD563OF4.js} +126 -27
  75. package/dist/{cli-VXLHOZSO.js → cli-JRJF2WHU.js} +20 -20
  76. package/dist/{cli-UQC46YSV.js → cli-JTFLIMIG.js} +3 -3
  77. package/dist/{cli-K4HSQWXC.js → cli-K2BSJ2PK.js} +2 -2
  78. package/dist/{cli-OM32UURE.js → cli-K4QTYMN2.js} +25 -25
  79. package/dist/{cli-BJFYGVJV.js → cli-KFJDD4C4.js} +20 -20
  80. package/dist/{cli-WW54THXN.js → cli-KVQ2JPVD.js} +1 -1
  81. package/dist/{cli-LHMRUJVN.js → cli-L6AHMW2Z.js} +1 -1
  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-XJ7JESC2.js → cli-LI6G7GND.js} +27 -27
  85. package/dist/{cli-OMTHTWYJ.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-NKKCDO6K.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-LPFSJ625.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-X52TXCNF.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-UVIURDZC.js → cli-OMG4E53H.js} +20 -20
  100. package/dist/{cli-C32Q5E5I.js → cli-P6V3NSU4.js} +1 -1
  101. package/dist/{cli-RMD5WSUQ.js → cli-PAMQMTHK.js} +21 -21
  102. package/dist/{cli-WNBP3LOD.js → cli-PKTHOCT3.js} +26 -26
  103. package/dist/{cli-S3NHXAJM.js → cli-QK7QAP5H.js} +18 -18
  104. package/dist/cli-QQ432JEN.js +36 -0
  105. package/dist/{cli-YYXAGJQR.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-TEBV2OIW.js → cli-RQISHMJF.js} +83 -21
  109. package/dist/{cli-X64BNBQH.js → cli-RVZH462G.js} +585 -8
  110. package/dist/{cli-6AMK3DYS.js → cli-SEEOQVUL.js} +12 -12
  111. package/dist/{cli-QTCTWYCM.js → cli-SO354HPI.js} +3 -3
  112. package/dist/{cli-RHL4B4H7.js → cli-T76HDH7F.js} +88 -4
  113. package/dist/{cli-ZJW6HQ6N.js → cli-TIS7DWRR.js} +7 -7
  114. package/dist/{cli-6JWDFCUV.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-ATHATKI5.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-PNS4KWWC.js → cli-XCG33I77.js} +24 -24
  121. package/dist/{cli-DBMEH4Y5.js → cli-YHLSG5HB.js} +26 -26
  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.js +1918 -283
  128. package/dist/core/assessment-moves.d.ts +32 -0
  129. package/dist/core/assessment-reports.d.ts +38 -0
  130. package/dist/core/assessment-settings.d.ts +15 -0
  131. package/dist/core/benchmark-samples.d.ts +28 -0
  132. package/dist/core/session-host.d.ts +4 -0
  133. package/dist/core/session-roster.d.ts +6 -0
  134. package/dist/core/session-timers.d.ts +40 -0
  135. package/dist/core/session.d.ts +14 -1
  136. package/dist/core/tick-timer.d.ts +18 -0
  137. package/dist/dev/console/assets/{index-Ch6HHb2T.js → index-zd--5H1f.js} +26 -26
  138. package/dist/dev/console/index.html +1 -1
  139. package/dist/dev/shell.d.ts +8 -0
  140. package/dist/dev/view/commands.d.ts +3 -1
  141. package/dist/docs/api/index.md +1 -1
  142. package/dist/docs/api/sdk-commands.md +29 -0
  143. package/dist/docs/api/sdk-e2e.md +30 -0
  144. package/dist/docs/api/sdk-projection.md +5 -0
  145. package/dist/docs/api/sdk-tools-client.md +30 -0
  146. package/dist/docs/api/sdk-ui.md +7 -0
  147. package/dist/docs/api/sdk.md +834 -19
  148. package/dist/docs/changelog.md +28 -0
  149. package/dist/docs/cli-error-codes.md +5 -1
  150. package/dist/docs/cli-reference.md +76 -2
  151. package/dist/docs/concepts/index.md +2 -0
  152. package/dist/docs/concepts/terminology.md +12 -0
  153. package/dist/docs/guides/assessments.md +248 -0
  154. package/dist/docs/guides/benchmarks.md +241 -0
  155. package/dist/docs/guides/engine.md +8 -0
  156. package/dist/docs/guides/index.md +2 -0
  157. package/dist/docs/guides/presentation.md +11 -9
  158. package/dist/docs/guides/session-hooks.md +24 -22
  159. package/dist/docs/guides/tick-controller.md +22 -1
  160. package/dist/docs/guides/ui.md +24 -0
  161. package/dist/docs/guides/upgrading.md +21 -0
  162. package/dist/docs/page-index.md +16 -12
  163. package/dist/docs/recipes/create-assessment.md +124 -0
  164. package/dist/docs/recipes/create-benchmark.md +115 -0
  165. package/dist/docs/recipes/index.md +2 -0
  166. package/dist/execution/context-composition.d.ts +39 -4
  167. package/dist/execution/engine-state.d.ts +13 -0
  168. package/dist/execution/executor.d.ts +16 -0
  169. package/dist/execution/logic-result.d.ts +13 -2
  170. package/dist/help-examples.d.ts +12 -0
  171. package/dist/host/adapter.d.ts +24 -1
  172. package/dist/host/protocol.d.ts +115 -1
  173. package/dist/host.js +29 -1
  174. package/dist/playwright.js +1912 -277
  175. package/dist/runtime/index.d.ts +3 -1
  176. package/dist/runtime/manifest-version.d.ts +1 -1
  177. package/dist/runtime.js +298 -16
  178. package/dist/schema.json +189 -0
  179. package/dist/templating/resource-metadata.d.ts +1 -1
  180. package/dist/utils/error-codes.d.ts +9 -1
  181. package/dist/validation/assessment-validation.d.ts +34 -0
  182. package/dist/validation/benchmark-validation.d.ts +20 -0
  183. package/dist/validation/schema-validation.d.ts +4 -0
  184. package/package.json +3 -3
  185. package/dist/cli-27Z5T52R.js +0 -30
  186. package/dist/cli-3VLBFWHN.js +0 -36
  187. package/dist/cli-BINVO5R7.js +0 -36
  188. package/dist/cli-HLI5UEKX.js +0 -36
  189. package/dist/cli-OF36EA62.js +0 -36
  190. package/dist/cli-OVIJRBFI.js +0 -36
  191. package/dist/cli-UIYKPSIY.js +0 -36
  192. package/dist/cli-WZNIW6ZO.js +0 -16
@@ -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)
@@ -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}.
@@ -52,18 +52,29 @@ export interface EngineResultRead {
52
52
  state: unknown;
53
53
  /** Whether a tick's result reported the game complete (§11). */
54
54
  complete: boolean;
55
+ /**
56
+ * The result's `benchmarks`, unchecked: each write is held to its
57
+ * benchmark, and dropped if it does not match, as it is folded (§6.16).
58
+ * `undefined` when the result carried none.
59
+ */
60
+ benchmarks?: unknown;
61
+ /**
62
+ * The result's `assessments`, unchecked, as `benchmarks` is (§6.17).
63
+ * `undefined` when the result carried none.
64
+ */
65
+ assessments?: unknown;
55
66
  }
56
67
  /**
57
68
  * Read an engine result (`{ capabilities, deletes?, state? }`, and `complete?` from a
58
69
  * tick's `Run` or `RunAggregate`). `Init` closes no round, so it has nothing to
59
70
  * complete and `complete` there is an unknown key like any other.
60
71
  */
61
- export declare function readEngineResult(label: string, result: unknown, phase?: 'init' | 'tick'): EngineResultRead;
72
+ export declare function readEngineResult(label: string, result: unknown, phase?: 'init' | 'tick', writesBenchmarks?: boolean, writesAssessments?: boolean): EngineResultRead;
62
73
  /**
63
74
  * Read an aggregate result (`{ shared: { capabilities }, teams: [{ capabilities }] }`)
64
75
  * into the shared patch and one patch per team.
65
76
  */
66
- export declare function readAggregateResult(label: string, result: unknown, teamCount: number, phase?: 'init' | 'tick'): {
77
+ export declare function readAggregateResult(label: string, result: unknown, teamCount: number, phase?: 'init' | 'tick', writesBenchmarks?: boolean, writesAssessments?: boolean): {
67
78
  shared: EngineResultRead;
68
79
  teams: EngineResultRead[];
69
80
  };
@@ -7,6 +7,10 @@ export declare function compact(example: string): string;
7
7
  export declare function indent(block: string): string;
8
8
  export declare const packageExample: string;
9
9
  export declare const capabilityExample: string;
10
+ export declare const benchmarkExample: string;
11
+ export declare const benchmarkUpdateExample: string;
12
+ export declare const assessmentExample: string;
13
+ export declare const assessmentUpdateExample: string;
10
14
  export declare const settingsExample: string;
11
15
  export declare const settingsUpdateExample: string;
12
16
  export declare const engineExample: string;
@@ -57,6 +61,14 @@ export declare const RESOURCE_EXAMPLES: {
57
61
  readonly new: string;
58
62
  readonly update: string;
59
63
  };
64
+ readonly benchmark: {
65
+ readonly new: string;
66
+ readonly update: string;
67
+ };
68
+ readonly assessment: {
69
+ readonly new: string;
70
+ readonly update: string;
71
+ };
60
72
  readonly settings: {
61
73
  readonly new: string;
62
74
  readonly update: string;
@@ -12,7 +12,7 @@
12
12
  * protocol's `ok: false` response for that request, and keeps the port open: a
13
13
  * failing endpoint must not take the surface down with it.
14
14
  */
15
- import type { PastStateEntry, PastStateQuery, Participant } from '@seriousgaming/sdk';
15
+ import type { AssessmentReport, BenchmarkFilter, BenchmarkStatistics, PastStateEntry, PastStateQuery, Participant } from '@seriousgaming/sdk';
16
16
  /** Who is asking. Supplied to every adapter call so it can authorise. */
17
17
  export interface RequestOrigin {
18
18
  /** Identifier of the UI bundle mounted in this frame. */
@@ -64,4 +64,27 @@ export interface HostAdapter {
64
64
  * rather than an error.
65
65
  */
66
66
  getAllTeamsParticipants?(origin: RequestOrigin): Promise<Participant[]>;
67
+ /**
68
+ * Pooled statistics for one of the game's benchmarks (§6.16).
69
+ *
70
+ * `where` is never empty: try each filter in order and answer with the
71
+ * first that has enough results, naming it as `matched`. Resolve `null`
72
+ * when there is nothing to show. Pooling, scope and thresholds are the
73
+ * adapter's. A host with no implementation answers `null`, since a
74
+ * missing benchmark is something a surface already shows without.
75
+ */
76
+ getBenchmark?(identifier: string, where: BenchmarkFilter[], origin: RequestOrigin): Promise<BenchmarkStatistics | null>;
77
+ /**
78
+ * One assessment's results, placed in bands with the thresholds in force
79
+ * for the session (§6.17.3).
80
+ *
81
+ * The adapter decides which results the caller sees, from `origin` and from
82
+ * which surface it mounted this channel for: a player surface sees its own
83
+ * participant's and its own team's, an observer the team it watches, and a
84
+ * session UI or presentation everyone's. `buildAssessmentReport` from
85
+ * `@seriousgaming/sdk` assembles the answer. Throw for an identifier the
86
+ * package does not declare. A host with no implementation answers with an
87
+ * error.
88
+ */
89
+ getAssessment?(identifier: string, origin: RequestOrigin): Promise<AssessmentReport>;
67
90
  }
@@ -10,7 +10,7 @@
10
10
  * the two disagree, so extending a union here without extending the guest's
11
11
  * (or the reverse) is caught before either ships.
12
12
  */
13
- import type { ContextDeletePath, EndpointFailure, HostOverlay, Participant, PastStateEntry, PastStateQuery, ThemePreference, TimerState, ValidationRejection } from '@seriousgaming/sdk';
13
+ import type { AssessmentReport, BenchmarkFilter, BenchmarkStatistics, ContextDeletePath, EndpointFailure, HostOverlay, Participant, PastStateEntry, PastStateQuery, ThemePreference, TimerState, ValidationRejection } from '@seriousgaming/sdk';
14
14
  import type { CrossTeamData, MutationOutcome, OwnTeamJoinLink, PresentationGame, PresentationSession, RunKind, SessionData, SessionHookFailure, SessionMeta, SharedState, TeamConfiguration, TeamInfo, SessionJoinLink, TeamLinks, TeamState, UserInterfaceLocale, UserInterfaceTheme, ViewerRole, WalkthroughLink } from '@seriousgaming/sdk/ui';
15
15
  /**
16
16
  * Version of the host↔iframe handshake protocol. Both ends stamp it on the
@@ -243,6 +243,26 @@ export type HostPortMessage = {
243
243
  requestId: string;
244
244
  ok: false;
245
245
  error: string;
246
+ } | {
247
+ type: 'getBenchmark:response';
248
+ requestId: string;
249
+ ok: true;
250
+ statistics: BenchmarkStatistics | null;
251
+ } | {
252
+ type: 'getBenchmark:response';
253
+ requestId: string;
254
+ ok: false;
255
+ error: string;
256
+ } | {
257
+ type: 'getAssessment:response';
258
+ requestId: string;
259
+ ok: true;
260
+ report: AssessmentReport;
261
+ } | {
262
+ type: 'getAssessment:response';
263
+ requestId: string;
264
+ ok: false;
265
+ error: string;
246
266
  } | {
247
267
  type: 'getAllTeamsParticipants:response';
248
268
  requestId: string;
@@ -310,6 +330,25 @@ export type IFramePortMessage = {
310
330
  type: 'getPastState';
311
331
  requestId: string;
312
332
  query: PastStateQuery;
333
+ }
334
+ /**
335
+ * Read a benchmark (§6.16). `where` is never empty: the wrapper turns an
336
+ * omitted filter into `[{}]` before it sends.
337
+ */
338
+ | {
339
+ type: 'getBenchmark';
340
+ requestId: string;
341
+ identifier: string;
342
+ where: BenchmarkFilter[];
343
+ }
344
+ /**
345
+ * Read an assessment's results (§6.17). The host decides which results the
346
+ * surface sees, from who it holds the surface as, never from the message.
347
+ */
348
+ | {
349
+ type: 'getAssessment';
350
+ requestId: string;
351
+ identifier: string;
313
352
  } | {
314
353
  type: 'getAllTeamsParticipants';
315
354
  requestId: string;
@@ -502,6 +541,26 @@ export type HostSessionPortMessage = {
502
541
  requestId: string;
503
542
  ok: false;
504
543
  error: string;
544
+ } | {
545
+ type: 'getBenchmark:response';
546
+ requestId: string;
547
+ ok: true;
548
+ statistics: BenchmarkStatistics | null;
549
+ } | {
550
+ type: 'getBenchmark:response';
551
+ requestId: string;
552
+ ok: false;
553
+ error: string;
554
+ } | {
555
+ type: 'getAssessment:response';
556
+ requestId: string;
557
+ ok: true;
558
+ report: AssessmentReport;
559
+ } | {
560
+ type: 'getAssessment:response';
561
+ requestId: string;
562
+ ok: false;
563
+ error: string;
505
564
  } | {
506
565
  type: 'themePreferenceChanged';
507
566
  preference: ThemePreference;
@@ -585,6 +644,25 @@ export type IFrameSessionPortMessage = {
585
644
  type: 'getPastState';
586
645
  requestId: string;
587
646
  query: PastStateQuery;
647
+ }
648
+ /**
649
+ * Read a benchmark (§6.16). `where` is never empty: the wrapper turns an
650
+ * omitted filter into `[{}]` before it sends.
651
+ */
652
+ | {
653
+ type: 'getBenchmark';
654
+ requestId: string;
655
+ identifier: string;
656
+ where: BenchmarkFilter[];
657
+ }
658
+ /**
659
+ * Read an assessment's results (§6.17). The host decides which results the
660
+ * surface sees, from who it holds the surface as, never from the message.
661
+ */
662
+ | {
663
+ type: 'getAssessment';
664
+ requestId: string;
665
+ identifier: string;
588
666
  } | {
589
667
  type: 'requestTick';
590
668
  requestId?: string;
@@ -837,6 +915,26 @@ export type HostPresentationPortMessage = {
837
915
  requestId: string;
838
916
  ok: false;
839
917
  error: string;
918
+ } | {
919
+ type: 'getBenchmark:response';
920
+ requestId: string;
921
+ ok: true;
922
+ statistics: BenchmarkStatistics | null;
923
+ } | {
924
+ type: 'getBenchmark:response';
925
+ requestId: string;
926
+ ok: false;
927
+ error: string;
928
+ } | {
929
+ type: 'getAssessment:response';
930
+ requestId: string;
931
+ ok: true;
932
+ report: AssessmentReport;
933
+ } | {
934
+ type: 'getAssessment:response';
935
+ requestId: string;
936
+ ok: false;
937
+ error: string;
840
938
  } | {
841
939
  type: 'themePreferenceChanged';
842
940
  preference: ThemePreference;
@@ -861,4 +959,20 @@ export type IFramePresentationPortMessage = {
861
959
  type: 'getPastState';
862
960
  requestId: string;
863
961
  query: PastStateQuery;
962
+ }
963
+ /**
964
+ * Read a benchmark (§6.16). `where` is never empty: the wrapper turns an
965
+ * omitted filter into `[{}]` before it sends.
966
+ */
967
+ | {
968
+ type: 'getBenchmark';
969
+ requestId: string;
970
+ identifier: string;
971
+ where: BenchmarkFilter[];
972
+ }
973
+ /** Read an assessment's results (§6.17): every one, for a deck with a session. */
974
+ | {
975
+ type: 'getAssessment';
976
+ requestId: string;
977
+ identifier: string;
864
978
  };