@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.
- package/dist/agent/guidance.md +4 -0
- package/dist/{cli-F2D4GGUA.js → cli-2BKEIIA3.js} +66 -0
- package/dist/{cli-ZGCG6C22.js → cli-2QGTDHRX.js} +21 -21
- package/dist/{cli-SRXDLMXY.js → cli-2SDG3SZ7.js} +21 -21
- package/dist/{cli-DH35TZ2Q.js → cli-2VXP34R5.js} +2 -2
- package/dist/{cli-P3NUTOPK.js → cli-2W4B6PD5.js} +1 -1
- package/dist/{cli-WJVPSVF2.js → cli-2X7DKSXN.js} +24 -24
- package/dist/{cli-ATAJSIXH.js → cli-2ZP4N7HK.js} +19 -19
- package/dist/{cli-5O7XENQY.js → cli-3GJYZH4C.js} +5 -5
- package/dist/{cli-H6PP2MZT.js → cli-3GO3M2MX.js} +17 -13
- package/dist/{cli-HMDYG6PS.js → cli-3LDLUNME.js} +17 -17
- package/dist/{cli-BZOKZ7LP.js → cli-3WY6L2WP.js} +27 -27
- package/dist/{cli-REAM7LSC.js → cli-44MBABRD.js} +25 -25
- package/dist/{cli-5TTJWM2R.js → cli-4IO7MKLR.js} +20 -20
- package/dist/{cli-HNDFANQG.js → cli-4U2PY7W3.js} +1 -1
- package/dist/{cli-WQ7JBZNW.js → cli-4WI4LTBI.js} +2 -2
- package/dist/{cli-OTBCA54D.js → cli-55EIGGZK.js} +1 -1
- package/dist/{cli-FYPW25VD.js → cli-5AQV6FTL.js} +18 -18
- package/dist/{cli-RKPQLB7J.js → cli-5CW7BEU7.js} +3 -3
- package/dist/{cli-27TQVLVF.js → cli-5JUVHNZF.js} +12 -12
- package/dist/{cli-F3YJKP6D.js → cli-5KERL6HV.js} +9 -4
- package/dist/{cli-MSNSXVGF.js → cli-5KSA24NQ.js} +24 -24
- package/dist/{cli-5VZBFMCK.js → cli-5PIFO3EN.js} +8 -0
- package/dist/{cli-FT3X3D4P.js → cli-5QN2Z43X.js} +20 -20
- package/dist/cli-5XSPAA5X.js +69 -0
- package/dist/{cli-B2QAJ5RQ.js → cli-62KAYGXO.js} +20 -20
- package/dist/{cli-QPV3TYOM.js → cli-6IMV5ZZU.js} +26 -26
- package/dist/{cli-UULZSQBV.js → cli-6KWCIAN2.js} +764 -66
- package/dist/{cli-DQE7ITIR.js → cli-6NWETIX5.js} +20 -20
- package/dist/{cli-L7F4XKCB.js → cli-774W3MN5.js} +26 -26
- package/dist/cli-7BUD3VAD.js +16 -0
- package/dist/{cli-XNOAO6DY.js → cli-7KEP57S7.js} +12 -12
- package/dist/{cli-5UKWX3IU.js → cli-7OYFJMA6.js} +18 -18
- package/dist/{cli-WNHMJM3Z.js → cli-7ZNEDQ3G.js} +20 -20
- package/dist/{cli-5RRPUL6V.js → cli-AFK6OUID.js} +12 -12
- package/dist/{cli-6P6V2EHY.js → cli-AIYQFWXN.js} +25 -25
- package/dist/{cli-ERJNDBDH.js → cli-ARAAEWIQ.js} +2 -2
- package/dist/cli-AVQYV3N4.js +36 -0
- package/dist/{cli-TI2FOFPA.js → cli-B54Z6CXH.js} +16 -16
- package/dist/{cli-EEO5ZPAZ.js → cli-B5TC4MEL.js} +5 -5
- package/dist/{cli-5Z4D3F6Y.js → cli-BCXGOLU3.js} +3 -3
- package/dist/{cli-G2GLW5Z4.js → cli-BHAODVTZ.js} +1 -1
- package/dist/{cli-4F24FUW6.js → cli-BPS2JG74.js} +20 -20
- package/dist/{cli-W3RG2MRI.js → cli-BVO55SR2.js} +2 -2
- package/dist/{cli-R5SNTPND.js → cli-CFH3JZP5.js} +21 -21
- package/dist/{cli-Q7QSWNY2.js → cli-CTK2OIK6.js} +20 -20
- package/dist/{cli-ATWJCB2G.js → cli-CW5MV4VX.js} +4 -4
- package/dist/{cli-TCQJL2GY.js → cli-D5VOSJZ7.js} +1 -1
- package/dist/{cli-KIZTASLL.js → cli-DAEPMK7A.js} +5 -5
- package/dist/{cli-44CM2AH2.js → cli-DAHR7PKB.js} +1 -1
- package/dist/{cli-XW3JLRSA.js → cli-DWDSBTYL.js} +1 -1
- package/dist/cli-DYSDPGXW.js +95 -0
- package/dist/{cli-QEFYDXMH.js → cli-DZCLRZXJ.js} +1 -1
- package/dist/{cli-77T4LJQF.js → cli-EJ47IE45.js} +24 -24
- package/dist/{cli-QDBYFITU.js → cli-EK4OSJHA.js} +2 -2
- package/dist/{cli-GO64NABP.js → cli-FCJHNXDA.js} +1 -1
- package/dist/{cli-ZNQBF4Z3.js → cli-FNESSE3L.js} +1 -1
- package/dist/{cli-D3S7NJZ3.js → cli-FTLH4WCE.js} +17 -17
- package/dist/{cli-JHLWBRXB.js → cli-FYV77YS2.js} +18 -18
- package/dist/cli-GMJX6Q4Q.js +36 -0
- package/dist/{cli-7JUNA74L.js → cli-GRBVNGDW.js} +1 -1
- package/dist/{cli-XKAIDYIE.js → cli-HAFCFY77.js} +33 -19
- package/dist/{cli-OXLOGXT3.js → cli-HCJLYI24.js} +3 -3
- package/dist/{cli-XOYUTNER.js → cli-HCXS5EXU.js} +25 -25
- package/dist/cli-HEUNNHDH.js +36 -0
- package/dist/{cli-G3TU6CP6.js → cli-HNUTIWDZ.js} +19 -19
- package/dist/{cli-JXQLHJO2.js → cli-HXT25ETJ.js} +244 -243
- package/dist/{cli-5EH4WTH4.js → cli-IGEL7UJQ.js} +5 -5
- package/dist/{cli-TLSTSZAC.js → cli-IO32YA5N.js} +26 -26
- package/dist/cli-IPTGZDBB.js +36 -0
- package/dist/{cli-OBLEROSC.js → cli-J25TYFKB.js} +19 -19
- package/dist/{cli-5ATO27Z4.js → cli-J7XYMEMX.js} +20 -20
- package/dist/{cli-X3TSTTYI.js → cli-JC5OJRID.js} +2 -2
- package/dist/{cli-25SJZI7N.js → cli-JD563OF4.js} +126 -27
- package/dist/{cli-VXLHOZSO.js → cli-JRJF2WHU.js} +20 -20
- package/dist/{cli-UQC46YSV.js → cli-JTFLIMIG.js} +3 -3
- package/dist/{cli-K4HSQWXC.js → cli-K2BSJ2PK.js} +2 -2
- package/dist/{cli-OM32UURE.js → cli-K4QTYMN2.js} +25 -25
- package/dist/{cli-BJFYGVJV.js → cli-KFJDD4C4.js} +20 -20
- package/dist/{cli-WW54THXN.js → cli-KVQ2JPVD.js} +1 -1
- package/dist/{cli-LHMRUJVN.js → cli-L6AHMW2Z.js} +1 -1
- package/dist/{cli-IKSLPAZN.js → cli-LCYUBCVY.js} +4 -4
- package/dist/{cli-HGCOEL5T.js → cli-LEWSCDH5.js} +4 -4
- package/dist/{cli-XJ7JESC2.js → cli-LI6G7GND.js} +27 -27
- package/dist/{cli-OMTHTWYJ.js → cli-LU2GCWIU.js} +21 -21
- package/dist/{cli-UEQMK4WX.js → cli-M3Z2KOEB.js} +1 -1
- package/dist/{cli-226ZJ72R.js → cli-M6E3E3I2.js} +170 -3
- package/dist/{cli-NKKCDO6K.js → cli-MCRPA4Z6.js} +20 -20
- package/dist/{cli-BQ36DV5C.js → cli-MI2DEDMA.js} +3 -3
- package/dist/{cli-6O7YCK2M.js → cli-MITZ6SE7.js} +3 -3
- package/dist/{cli-LPFSJ625.js → cli-MTIYD3BX.js} +26 -26
- package/dist/{cli-5M6KDNVX.js → cli-MTZUJGBK.js} +2 -2
- package/dist/{cli-GSOV26O5.js → cli-NCLMUXLC.js} +14 -14
- package/dist/{cli-X52TXCNF.js → cli-NLS3DKWH.js} +26 -26
- package/dist/{cli-AH6AMAIB.js → cli-NMDGS7IE.js} +1 -1
- package/dist/cli-O3DJO2CS.js +30 -0
- package/dist/{cli-BC67QHD5.js → cli-O47D5BFN.js} +2 -2
- package/dist/{cli-MDVC5ZNM.js → cli-OBRZ36VP.js} +14 -14
- package/dist/{cli-UVIURDZC.js → cli-OMG4E53H.js} +20 -20
- package/dist/{cli-C32Q5E5I.js → cli-P6V3NSU4.js} +1 -1
- package/dist/{cli-RMD5WSUQ.js → cli-PAMQMTHK.js} +21 -21
- package/dist/{cli-WNBP3LOD.js → cli-PKTHOCT3.js} +26 -26
- package/dist/{cli-S3NHXAJM.js → cli-QK7QAP5H.js} +18 -18
- package/dist/cli-QQ432JEN.js +36 -0
- package/dist/{cli-YYXAGJQR.js → cli-QVNDPTBU.js} +20 -20
- package/dist/{cli-KJA6GLZI.js → cli-R2DFD6ZZ.js} +15 -15
- package/dist/{cli-6BLVI2JM.js → cli-RMVJMOWU.js} +111 -7
- package/dist/{cli-TEBV2OIW.js → cli-RQISHMJF.js} +83 -21
- package/dist/{cli-X64BNBQH.js → cli-RVZH462G.js} +585 -8
- package/dist/{cli-6AMK3DYS.js → cli-SEEOQVUL.js} +12 -12
- package/dist/{cli-QTCTWYCM.js → cli-SO354HPI.js} +3 -3
- package/dist/{cli-RHL4B4H7.js → cli-T76HDH7F.js} +88 -4
- package/dist/{cli-ZJW6HQ6N.js → cli-TIS7DWRR.js} +7 -7
- package/dist/{cli-6JWDFCUV.js → cli-TY3B6XS7.js} +21 -21
- package/dist/{cli-4FJL3KQZ.js → cli-UKEZJFIT.js} +2 -2
- package/dist/cli-VQAMW4RF.js +95 -0
- package/dist/{cli-ATHATKI5.js → cli-W4LMRVZT.js} +78 -47
- package/dist/cli-W7I5KGIB.js +84 -0
- package/dist/{cli-B3EFE7ZF.js → cli-WXGJFA4F.js} +1 -1
- package/dist/{cli-PNS4KWWC.js → cli-XCG33I77.js} +24 -24
- package/dist/{cli-DBMEH4Y5.js → cli-YHLSG5HB.js} +26 -26
- package/dist/cli-YNH5DTHY.js +36 -0
- package/dist/cli-YPMJWPDA.js +69 -0
- package/dist/{cli-PXQYY6KM.js → cli-YSXIR7EM.js} +0 -0
- package/dist/cli-ZPFWO4VW.js +85 -0
- package/dist/cli.js +53 -53
- package/dist/client.js +1918 -283
- package/dist/core/assessment-moves.d.ts +32 -0
- package/dist/core/assessment-reports.d.ts +38 -0
- package/dist/core/assessment-settings.d.ts +15 -0
- package/dist/core/benchmark-samples.d.ts +28 -0
- package/dist/core/session-host.d.ts +4 -0
- package/dist/core/session-roster.d.ts +6 -0
- package/dist/core/session-timers.d.ts +40 -0
- package/dist/core/session.d.ts +14 -1
- package/dist/core/tick-timer.d.ts +18 -0
- package/dist/dev/console/assets/{index-Ch6HHb2T.js → index-zd--5H1f.js} +26 -26
- package/dist/dev/console/index.html +1 -1
- package/dist/dev/shell.d.ts +8 -0
- package/dist/dev/view/commands.d.ts +3 -1
- package/dist/docs/api/index.md +1 -1
- package/dist/docs/api/sdk-commands.md +29 -0
- package/dist/docs/api/sdk-e2e.md +30 -0
- package/dist/docs/api/sdk-projection.md +5 -0
- package/dist/docs/api/sdk-tools-client.md +30 -0
- package/dist/docs/api/sdk-ui.md +7 -0
- package/dist/docs/api/sdk.md +834 -19
- package/dist/docs/changelog.md +28 -0
- package/dist/docs/cli-error-codes.md +5 -1
- package/dist/docs/cli-reference.md +76 -2
- package/dist/docs/concepts/index.md +2 -0
- package/dist/docs/concepts/terminology.md +12 -0
- package/dist/docs/guides/assessments.md +248 -0
- package/dist/docs/guides/benchmarks.md +241 -0
- package/dist/docs/guides/engine.md +8 -0
- package/dist/docs/guides/index.md +2 -0
- package/dist/docs/guides/presentation.md +11 -9
- package/dist/docs/guides/session-hooks.md +24 -22
- package/dist/docs/guides/tick-controller.md +22 -1
- package/dist/docs/guides/ui.md +24 -0
- package/dist/docs/guides/upgrading.md +21 -0
- package/dist/docs/page-index.md +16 -12
- package/dist/docs/recipes/create-assessment.md +124 -0
- package/dist/docs/recipes/create-benchmark.md +115 -0
- package/dist/docs/recipes/index.md +2 -0
- package/dist/execution/context-composition.d.ts +39 -4
- package/dist/execution/engine-state.d.ts +13 -0
- package/dist/execution/executor.d.ts +16 -0
- package/dist/execution/logic-result.d.ts +13 -2
- package/dist/help-examples.d.ts +12 -0
- package/dist/host/adapter.d.ts +24 -1
- package/dist/host/protocol.d.ts +115 -1
- package/dist/host.js +29 -1
- package/dist/playwright.js +1912 -277
- package/dist/runtime/index.d.ts +3 -1
- package/dist/runtime/manifest-version.d.ts +1 -1
- package/dist/runtime.js +298 -16
- package/dist/schema.json +189 -0
- package/dist/templating/resource-metadata.d.ts +1 -1
- package/dist/utils/error-codes.d.ts +9 -1
- package/dist/validation/assessment-validation.d.ts +34 -0
- package/dist/validation/benchmark-validation.d.ts +20 -0
- package/dist/validation/schema-validation.d.ts +4 -0
- package/package.json +3 -3
- package/dist/cli-27Z5T52R.js +0 -30
- package/dist/cli-3VLBFWHN.js +0 -36
- package/dist/cli-BINVO5R7.js +0 -36
- package/dist/cli-HLI5UEKX.js +0 -36
- package/dist/cli-OF36EA62.js +0 -36
- package/dist/cli-OVIJRBFI.js +0 -36
- package/dist/cli-UIYKPSIY.js +0 -36
- package/dist/cli-WZNIW6ZO.js +0 -16
package/dist/docs/api/sdk.md
CHANGED
|
@@ -6,6 +6,64 @@ Every export of `@seriousgaming/sdk`, with the declaration it is published with.
|
|
|
6
6
|
|
|
7
7
|
## Functions
|
|
8
8
|
|
|
9
|
+
### applyBenchmarkWrite
|
|
10
|
+
|
|
11
|
+
Fold a valid write over the current record: one level deep, `null` removing a field, `tags` replaced whole. Returns `undefined` when the write removes the record, or leaves it with nothing in it.
|
|
12
|
+
|
|
13
|
+
```ts
|
|
14
|
+
function applyBenchmarkWrite(
|
|
15
|
+
current: Record<string, unknown> | undefined,
|
|
16
|
+
write: Record<string, unknown> | null
|
|
17
|
+
): Record<string, unknown> | undefined;
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
### assessmentBandOf
|
|
21
|
+
|
|
22
|
+
The band a score falls in: the last band, in declared order, whose `from` is at or below it. Null for a score below every band, or with no bands. Read in declared order rather than sorted, so a session's overrides that leave the thresholds out of order still give one answer everywhere.
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
function assessmentBandOf(
|
|
26
|
+
score: number,
|
|
27
|
+
bands: readonly ResolvedAssessmentBand[]
|
|
28
|
+
): ResolvedAssessmentBand | null;
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
### benchmarkFilters
|
|
32
|
+
|
|
33
|
+
The filters a query tries, in order: `where` as a list, a single filter as a list of one, and `[{}]` when omitted. Throws on a malformed filter, so a surface finds out from its own call rather than from an empty answer.
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
function benchmarkFilters(query: BenchmarkQuery | undefined): BenchmarkFilter[];
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
### benchmarkWriteProblem
|
|
40
|
+
|
|
41
|
+
Check one benchmark write against its definition.
|
|
42
|
+
|
|
43
|
+
```ts
|
|
44
|
+
function benchmarkWriteProblem(
|
|
45
|
+
definition: Pick<BenchmarkDefinition, 'fields' | 'tags'>,
|
|
46
|
+
write: unknown
|
|
47
|
+
): string | null;
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### buildAssessmentReport
|
|
51
|
+
|
|
52
|
+
Build one assessment's report.
|
|
53
|
+
|
|
54
|
+
```ts
|
|
55
|
+
function buildAssessmentReport(input: {
|
|
56
|
+
definition: AssessmentDefinition;
|
|
57
|
+
bands: readonly ResolvedAssessmentBand[];
|
|
58
|
+
teams: readonly AssessmentReportTeam[];
|
|
59
|
+
participants: readonly {
|
|
60
|
+
id: string;
|
|
61
|
+
teamId: string;
|
|
62
|
+
}[];
|
|
63
|
+
audience: AssessmentAudience;
|
|
64
|
+
}): AssessmentReport;
|
|
65
|
+
```
|
|
66
|
+
|
|
9
67
|
### decodeUtf8
|
|
10
68
|
|
|
11
69
|
Decode a UTF-8 byte sequence to a string.
|
|
@@ -30,6 +88,25 @@ Encode a string to its UTF-8 byte sequence.
|
|
|
30
88
|
function encodeUtf8(input: string): Uint8Array;
|
|
31
89
|
```
|
|
32
90
|
|
|
91
|
+
### foldAssessmentWrite
|
|
92
|
+
|
|
93
|
+
Fold one assessment's write over its current records, or say what is wrong with it.
|
|
94
|
+
|
|
95
|
+
```ts
|
|
96
|
+
function foldAssessmentWrite(
|
|
97
|
+
definition: Pick<AssessmentDefinition, 'level' | 'min' | 'max'>,
|
|
98
|
+
current: unknown,
|
|
99
|
+
write: unknown,
|
|
100
|
+
participantIds: ReadonlySet<string>
|
|
101
|
+
):
|
|
102
|
+
| {
|
|
103
|
+
next: unknown;
|
|
104
|
+
}
|
|
105
|
+
| {
|
|
106
|
+
problem: string;
|
|
107
|
+
};
|
|
108
|
+
```
|
|
109
|
+
|
|
33
110
|
### getText
|
|
34
111
|
|
|
35
112
|
Helper for the common case where a caller just wants the assistant's text. Returns the concatenation of every `text` block in the response; `toolUse` blocks are skipped.
|
|
@@ -94,6 +171,25 @@ Read a setting path back into its settings identifier and keys, or `undefined` w
|
|
|
94
171
|
function parseSettingPath(path: string): ParsedSettingPath | undefined;
|
|
95
172
|
```
|
|
96
173
|
|
|
174
|
+
### resolveAssessmentBands
|
|
175
|
+
|
|
176
|
+
An assessment's bands in the order it declares them, with the thresholds and passes in force: the bundle's, under whatever the resolved `assessments` settings say for it.
|
|
177
|
+
|
|
178
|
+
```ts
|
|
179
|
+
function resolveAssessmentBands(
|
|
180
|
+
definition: Pick<AssessmentDefinition, 'bands'>,
|
|
181
|
+
settings?: Record<string, AssessmentBandSetting>
|
|
182
|
+
): ResolvedAssessmentBand[];
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
### resolveBenchmarkLevel
|
|
186
|
+
|
|
187
|
+
A benchmark's level, defaulted.
|
|
188
|
+
|
|
189
|
+
```ts
|
|
190
|
+
function resolveBenchmarkLevel(definition: Pick<BenchmarkDefinition, 'level'>): 'team' | 'session';
|
|
191
|
+
```
|
|
192
|
+
|
|
97
193
|
### scheduledTick
|
|
98
194
|
|
|
99
195
|
Convenience builder that creates a `TickControllerResult` for scheduled (absolute-time) ticking.
|
|
@@ -167,6 +263,73 @@ class UndeclaredApiUseError extends Error {
|
|
|
167
263
|
|
|
168
264
|
## Constants
|
|
169
265
|
|
|
266
|
+
### ASSESSMENT_FEEDBACK_MAX_LENGTH
|
|
267
|
+
|
|
268
|
+
The longest feedback line a result may carry.
|
|
269
|
+
|
|
270
|
+
```ts
|
|
271
|
+
const ASSESSMENT_FEEDBACK_MAX_LENGTH = 500;
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
### ASSESSMENTS_FEATURE
|
|
275
|
+
|
|
276
|
+
The feature name a game lists in `requires` when it declares an assessment, so a runtime that cannot hold results refuses the package rather than failing the first tick that returns them.
|
|
277
|
+
|
|
278
|
+
```ts
|
|
279
|
+
const ASSESSMENTS_FEATURE = 'assessments';
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
### ASSESSMENTS_SETTINGS
|
|
283
|
+
|
|
284
|
+
The identifier of the built-in settings resource that holds every assessment's band thresholds, so a scenario or a session can move them as it overrides any other setting.
|
|
285
|
+
|
|
286
|
+
```ts
|
|
287
|
+
const ASSESSMENTS_SETTINGS = 'assessments';
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
### BENCHMARK_RESERVED_FIELDS
|
|
291
|
+
|
|
292
|
+
Field names the SDK owns on every benchmark record. A bundle may not declare them, so an author's field can never be mistaken for one.
|
|
293
|
+
|
|
294
|
+
```ts
|
|
295
|
+
const BENCHMARK_RESERVED_FIELDS: readonly [
|
|
296
|
+
"tags",
|
|
297
|
+
"excluded"
|
|
298
|
+
];
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
### BENCHMARK_TAG_VALUE_PATTERN
|
|
302
|
+
|
|
303
|
+
What a tag's value may contain. Short and restricted, so a value can name a difficulty or a team count but never carry a team name, a participant's email or a sentence out of the session.
|
|
304
|
+
|
|
305
|
+
```ts
|
|
306
|
+
const BENCHMARK_TAG_VALUE_PATTERN: RegExp;
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
### BENCHMARKS_FEATURE
|
|
310
|
+
|
|
311
|
+
The feature name a game lists in `requires` when it declares a benchmark, so a runtime that cannot record benchmarks refuses the package rather than failing the first tick that returns them.
|
|
312
|
+
|
|
313
|
+
```ts
|
|
314
|
+
const BENCHMARKS_FEATURE = 'benchmarks';
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
### MAX_ASSESSMENTS_PER_GAME
|
|
318
|
+
|
|
319
|
+
The most assessments a game may declare.
|
|
320
|
+
|
|
321
|
+
```ts
|
|
322
|
+
const MAX_ASSESSMENTS_PER_GAME = 20;
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
### MAX_BENCHMARKS_PER_GAME
|
|
326
|
+
|
|
327
|
+
The most benchmarks a game may declare.
|
|
328
|
+
|
|
329
|
+
```ts
|
|
330
|
+
const MAX_BENCHMARKS_PER_GAME = 20;
|
|
331
|
+
```
|
|
332
|
+
|
|
170
333
|
### SCENARIO_GATE_READ_LIMIT_BYTES
|
|
171
334
|
|
|
172
335
|
The largest file, in bytes, a `Scenario` gate's `readAsset` reads: 10 MB (10,485,760 bytes), the same in every runtime, so a gate gives the same answer at build and on save. A read of a larger file rejects with `ScenarioAssetTooLargeError` before any of it is read.
|
|
@@ -182,20 +345,127 @@ const SCENARIO_GATE_READ_LIMIT_BYTES: number;
|
|
|
182
345
|
The session's shared store, as an aggregate function sees it: one value per shared-scope capability the engine declared, whatever the number of teams.
|
|
183
346
|
|
|
184
347
|
```ts
|
|
185
|
-
interface AggregateFunctionShared<
|
|
348
|
+
interface AggregateFunctionShared<
|
|
349
|
+
TSharedContext,
|
|
350
|
+
TSharedState = never,
|
|
351
|
+
TSessionBenchmarks = never,
|
|
352
|
+
> {
|
|
186
353
|
context: TSharedContext;
|
|
187
354
|
state?: TSharedState;
|
|
355
|
+
benchmarks?: Partial<TSessionBenchmarks>;
|
|
188
356
|
}
|
|
189
357
|
```
|
|
190
358
|
|
|
191
359
|
### AggregateFunctionTeam
|
|
192
360
|
|
|
193
361
|
```ts
|
|
194
|
-
interface AggregateFunctionTeam<
|
|
362
|
+
interface AggregateFunctionTeam<
|
|
363
|
+
TTeamContext,
|
|
364
|
+
TTeamState = never,
|
|
365
|
+
TTeamBenchmarks = never,
|
|
366
|
+
TTeamAssessments = never,
|
|
367
|
+
> {
|
|
195
368
|
teamId: string;
|
|
196
369
|
index: number;
|
|
197
370
|
context: TTeamContext;
|
|
198
371
|
state?: TTeamState;
|
|
372
|
+
benchmarks?: Partial<TTeamBenchmarks>;
|
|
373
|
+
assessments?: Partial<TTeamAssessments>;
|
|
374
|
+
}
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
### AssessmentBand
|
|
378
|
+
|
|
379
|
+
One band of an assessment's scores, such as 'developing' or 'expert': every score from `from` up to the next band's `from`
|
|
380
|
+
|
|
381
|
+
```ts
|
|
382
|
+
interface AssessmentBand {
|
|
383
|
+
id: string;
|
|
384
|
+
from: number;
|
|
385
|
+
passing?: boolean;
|
|
386
|
+
description?: string;
|
|
387
|
+
}
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
### AssessmentBandSetting
|
|
391
|
+
|
|
392
|
+
One band's override, as the built-in `assessments` settings hold it: the values a scenario or a session set, over the bundle's.
|
|
393
|
+
|
|
394
|
+
```ts
|
|
395
|
+
interface AssessmentBandSetting {
|
|
396
|
+
from?: number;
|
|
397
|
+
passing?: boolean;
|
|
398
|
+
}
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
### AssessmentDefinition
|
|
402
|
+
|
|
403
|
+
Definition of an assessment: one measure the engine scores for each participant, or for each team, which a runtime may report to a learning management system. The score is the game's; the runtime places it in a band and decides pass or fail from the band
|
|
404
|
+
|
|
405
|
+
```ts
|
|
406
|
+
interface AssessmentDefinition {
|
|
407
|
+
identifier: string;
|
|
408
|
+
description?: string;
|
|
409
|
+
level: 'participant' | 'team';
|
|
410
|
+
min: number;
|
|
411
|
+
max: number;
|
|
412
|
+
bands?: AssessmentBand[];
|
|
413
|
+
}
|
|
414
|
+
```
|
|
415
|
+
|
|
416
|
+
### AssessmentRecord
|
|
417
|
+
|
|
418
|
+
One result as the engine reads and writes it: the score, an optional line of feedback for the learner, and whether the game has marked it final.
|
|
419
|
+
|
|
420
|
+
```ts
|
|
421
|
+
interface AssessmentRecord {
|
|
422
|
+
score: number;
|
|
423
|
+
feedback?: string;
|
|
424
|
+
final?: boolean;
|
|
425
|
+
}
|
|
426
|
+
```
|
|
427
|
+
|
|
428
|
+
### AssessmentReport
|
|
429
|
+
|
|
430
|
+
What `getAssessment` resolves to: one assessment's results the caller may see.
|
|
431
|
+
|
|
432
|
+
```ts
|
|
433
|
+
interface AssessmentReport {
|
|
434
|
+
identifier: string;
|
|
435
|
+
level: AssessmentLevel;
|
|
436
|
+
min: number;
|
|
437
|
+
max: number;
|
|
438
|
+
bands: ResolvedAssessmentBand[];
|
|
439
|
+
results: AssessmentResult[];
|
|
440
|
+
}
|
|
441
|
+
```
|
|
442
|
+
|
|
443
|
+
### AssessmentReportTeam
|
|
444
|
+
|
|
445
|
+
One team, as a report is built from it.
|
|
446
|
+
|
|
447
|
+
```ts
|
|
448
|
+
interface AssessmentReportTeam {
|
|
449
|
+
teamId: string;
|
|
450
|
+
records: unknown;
|
|
451
|
+
complete: boolean;
|
|
452
|
+
}
|
|
453
|
+
```
|
|
454
|
+
|
|
455
|
+
### AssessmentResult
|
|
456
|
+
|
|
457
|
+
One result, as a surface reads it and a runtime reports it.
|
|
458
|
+
|
|
459
|
+
```ts
|
|
460
|
+
interface AssessmentResult {
|
|
461
|
+
teamId: string;
|
|
462
|
+
participantId?: string;
|
|
463
|
+
score: number;
|
|
464
|
+
scaled: number;
|
|
465
|
+
band: string | null;
|
|
466
|
+
passed: boolean | null;
|
|
467
|
+
feedback?: string;
|
|
468
|
+
final: boolean;
|
|
199
469
|
}
|
|
200
470
|
```
|
|
201
471
|
|
|
@@ -210,6 +480,50 @@ interface AssetDescription {
|
|
|
210
480
|
}
|
|
211
481
|
```
|
|
212
482
|
|
|
483
|
+
### BenchmarkDefinition
|
|
484
|
+
|
|
485
|
+
Definition of a benchmark: outcomes and decisions the engine records for each team (or the session), which a runtime pools anonymously across sessions so a user interface can compare a team with everyone who has played
|
|
486
|
+
|
|
487
|
+
```ts
|
|
488
|
+
interface BenchmarkDefinition {
|
|
489
|
+
identifier: string;
|
|
490
|
+
revision: number;
|
|
491
|
+
level?: 'team' | 'session';
|
|
492
|
+
tags?:
|
|
493
|
+
| []
|
|
494
|
+
| [string]
|
|
495
|
+
| [string, string]
|
|
496
|
+
| [string, string, string]
|
|
497
|
+
| [string, string, string, string]
|
|
498
|
+
| [string, string, string, string, string];
|
|
499
|
+
fields: {
|
|
500
|
+
[k: string]: BenchmarkField;
|
|
501
|
+
};
|
|
502
|
+
}
|
|
503
|
+
```
|
|
504
|
+
|
|
505
|
+
### BenchmarkQuery
|
|
506
|
+
|
|
507
|
+
Which records to pool.
|
|
508
|
+
|
|
509
|
+
```ts
|
|
510
|
+
interface BenchmarkQuery {
|
|
511
|
+
where?: BenchmarkFilter | BenchmarkFilter[];
|
|
512
|
+
}
|
|
513
|
+
```
|
|
514
|
+
|
|
515
|
+
### BenchmarkStatistics
|
|
516
|
+
|
|
517
|
+
What `getBenchmark` resolves to when there are statistics to show.
|
|
518
|
+
|
|
519
|
+
```ts
|
|
520
|
+
interface BenchmarkStatistics {
|
|
521
|
+
scope: BenchmarkScope;
|
|
522
|
+
matched: BenchmarkFilter;
|
|
523
|
+
fields: Record<string, BenchmarkFieldStatistics>;
|
|
524
|
+
}
|
|
525
|
+
```
|
|
526
|
+
|
|
213
527
|
### CapabilityDefinition
|
|
214
528
|
|
|
215
529
|
Definition of a capability
|
|
@@ -225,6 +539,18 @@ interface CapabilityDefinition {
|
|
|
225
539
|
}
|
|
226
540
|
```
|
|
227
541
|
|
|
542
|
+
### ChoiceBenchmarkStatistics
|
|
543
|
+
|
|
544
|
+
Statistics for a field with declared options.
|
|
545
|
+
|
|
546
|
+
```ts
|
|
547
|
+
interface ChoiceBenchmarkStatistics {
|
|
548
|
+
kind: 'choice';
|
|
549
|
+
count: number;
|
|
550
|
+
options: Record<string, number>;
|
|
551
|
+
}
|
|
552
|
+
```
|
|
553
|
+
|
|
228
554
|
### EndpointBaseArgs
|
|
229
555
|
|
|
230
556
|
The arguments every team- or session-scoped endpoint receives.
|
|
@@ -404,6 +730,8 @@ interface EngineDefinition {
|
|
|
404
730
|
writes?: string[];
|
|
405
731
|
uses?: ApiUse[];
|
|
406
732
|
settings?: string[];
|
|
733
|
+
benchmarks?: string[];
|
|
734
|
+
assessments?: string[];
|
|
407
735
|
aggregate?: boolean;
|
|
408
736
|
}
|
|
409
737
|
```
|
|
@@ -418,8 +746,12 @@ interface EngineFunctionArgs<
|
|
|
418
746
|
TSettings = unknown,
|
|
419
747
|
TCallbacks = SignatureCallbacks,
|
|
420
748
|
TState = never,
|
|
749
|
+
TBenchmarks = never,
|
|
750
|
+
TAssessments = never,
|
|
421
751
|
> extends LogicFunctionArgs<TContext, TSettings, TCallbacks> {
|
|
422
752
|
state?: TState;
|
|
753
|
+
benchmarks?: Partial<TBenchmarks>;
|
|
754
|
+
assessments?: Partial<TAssessments>;
|
|
423
755
|
}
|
|
424
756
|
```
|
|
425
757
|
|
|
@@ -428,8 +760,15 @@ interface EngineFunctionArgs<
|
|
|
428
760
|
What the engine's `Init` and `Run` return: the capabilities they write and, optionally, the engine's private memory.
|
|
429
761
|
|
|
430
762
|
```ts
|
|
431
|
-
interface EngineResult<
|
|
763
|
+
interface EngineResult<
|
|
764
|
+
TContext,
|
|
765
|
+
TState = never,
|
|
766
|
+
TBenchmarks = never,
|
|
767
|
+
TAssessments = never,
|
|
768
|
+
> extends LogicResult<TContext> {
|
|
432
769
|
state?: TState;
|
|
770
|
+
benchmarks?: BenchmarkWritesOf<TBenchmarks>;
|
|
771
|
+
assessments?: AssessmentWritesOf<TAssessments>;
|
|
433
772
|
}
|
|
434
773
|
```
|
|
435
774
|
|
|
@@ -747,6 +1086,25 @@ interface LogicResult<TContext> {
|
|
|
747
1086
|
}
|
|
748
1087
|
```
|
|
749
1088
|
|
|
1089
|
+
### NumericBenchmarkStatistics
|
|
1090
|
+
|
|
1091
|
+
Statistics for a numeric field. Only `count` is always present: a runtime may hold back any other figure until enough results back it, `min` and `max` most of all, since each is one team's real result.
|
|
1092
|
+
|
|
1093
|
+
```ts
|
|
1094
|
+
interface NumericBenchmarkStatistics {
|
|
1095
|
+
kind: 'number';
|
|
1096
|
+
count: number;
|
|
1097
|
+
mean?: number;
|
|
1098
|
+
min?: number;
|
|
1099
|
+
max?: number;
|
|
1100
|
+
p10?: number;
|
|
1101
|
+
p25?: number;
|
|
1102
|
+
p50?: number;
|
|
1103
|
+
p75?: number;
|
|
1104
|
+
p90?: number;
|
|
1105
|
+
}
|
|
1106
|
+
```
|
|
1107
|
+
|
|
750
1108
|
### PackageDefinition
|
|
751
1109
|
|
|
752
1110
|
Definition of a package
|
|
@@ -870,6 +1228,18 @@ interface RequestTickFunctionArgs<TContext, TSettings> {
|
|
|
870
1228
|
}
|
|
871
1229
|
```
|
|
872
1230
|
|
|
1231
|
+
### ResolvedAssessmentBand
|
|
1232
|
+
|
|
1233
|
+
One band, with the threshold and pass in force for a session.
|
|
1234
|
+
|
|
1235
|
+
```ts
|
|
1236
|
+
interface ResolvedAssessmentBand {
|
|
1237
|
+
id: string;
|
|
1238
|
+
from: number;
|
|
1239
|
+
passing: boolean;
|
|
1240
|
+
}
|
|
1241
|
+
```
|
|
1242
|
+
|
|
873
1243
|
### ResolvedPackageManifest
|
|
874
1244
|
|
|
875
1245
|
Every resource a package holds: the shape the loader builds from disk and the shape the build writes to seriousgaming.json. A game holds one of nine kinds, each in its own field; everything a package may hold more than one of is an array.
|
|
@@ -892,6 +1262,8 @@ interface ResolvedPackageManifest {
|
|
|
892
1262
|
tick_controller?: SDKTickController;
|
|
893
1263
|
guide?: SDKFacilitatorGuide;
|
|
894
1264
|
capabilities?: SDKCapability[];
|
|
1265
|
+
benchmarks?: SDKBenchmark[];
|
|
1266
|
+
assessments?: SDKAssessment[];
|
|
895
1267
|
settings?: SDKSettings[];
|
|
896
1268
|
scenarios?: SDKScenario[];
|
|
897
1269
|
hooks?: SDKHook[];
|
|
@@ -910,9 +1282,12 @@ interface RunAggregateFunctionArgs<
|
|
|
910
1282
|
TCallbacks = SignatureCallbacks,
|
|
911
1283
|
TTeamState = never,
|
|
912
1284
|
TSharedState = never,
|
|
1285
|
+
TTeamBenchmarks = never,
|
|
1286
|
+
TSessionBenchmarks = never,
|
|
1287
|
+
TTeamAssessments = never,
|
|
913
1288
|
> {
|
|
914
|
-
shared: AggregateFunctionShared<TSharedContext, TSharedState>;
|
|
915
|
-
teams: AggregateFunctionTeam<TTeamContext, TTeamState>[];
|
|
1289
|
+
shared: AggregateFunctionShared<TSharedContext, TSharedState, TSessionBenchmarks>;
|
|
1290
|
+
teams: AggregateFunctionTeam<TTeamContext, TTeamState, TTeamBenchmarks, TTeamAssessments>[];
|
|
916
1291
|
settings: TSettings;
|
|
917
1292
|
meta: RunMeta;
|
|
918
1293
|
participants: readonly Readonly<Participant>[];
|
|
@@ -930,9 +1305,12 @@ interface RunAggregateResult<
|
|
|
930
1305
|
TSharedContext,
|
|
931
1306
|
TTeamState = never,
|
|
932
1307
|
TSharedState = never,
|
|
1308
|
+
TTeamBenchmarks = never,
|
|
1309
|
+
TSessionBenchmarks = never,
|
|
1310
|
+
TTeamAssessments = never,
|
|
933
1311
|
> {
|
|
934
|
-
shared: EngineResult<Partial<TSharedContext>, TSharedState>;
|
|
935
|
-
teams: EngineResult<TTeamContext, TTeamState>[];
|
|
1312
|
+
shared: EngineResult<Partial<TSharedContext>, TSharedState, TSessionBenchmarks>;
|
|
1313
|
+
teams: EngineResult<TTeamContext, TTeamState, TTeamBenchmarks, TTeamAssessments>[];
|
|
936
1314
|
}
|
|
937
1315
|
```
|
|
938
1316
|
|
|
@@ -946,9 +1324,12 @@ interface RunAggregateTickResult<
|
|
|
946
1324
|
TSharedContext,
|
|
947
1325
|
TTeamState = never,
|
|
948
1326
|
TSharedState = never,
|
|
1327
|
+
TTeamBenchmarks = never,
|
|
1328
|
+
TSessionBenchmarks = never,
|
|
1329
|
+
TTeamAssessments = never,
|
|
949
1330
|
> {
|
|
950
|
-
shared: RunResult<Partial<TSharedContext>, TSharedState>;
|
|
951
|
-
teams: RunResult<TTeamContext, TTeamState>[];
|
|
1331
|
+
shared: RunResult<Partial<TSharedContext>, TSharedState, TSessionBenchmarks>;
|
|
1332
|
+
teams: RunResult<TTeamContext, TTeamState, TTeamBenchmarks, TTeamAssessments>[];
|
|
952
1333
|
}
|
|
953
1334
|
```
|
|
954
1335
|
|
|
@@ -967,7 +1348,12 @@ interface RunMeta extends LogicMeta {
|
|
|
967
1348
|
What the engine's `Run` returns: an `EngineResult`, plus whether the game is now over for this team.
|
|
968
1349
|
|
|
969
1350
|
```ts
|
|
970
|
-
interface RunResult<
|
|
1351
|
+
interface RunResult<
|
|
1352
|
+
TContext,
|
|
1353
|
+
TState = never,
|
|
1354
|
+
TBenchmarks = never,
|
|
1355
|
+
TAssessments = never,
|
|
1356
|
+
> extends EngineResult<TContext, TState, TBenchmarks, TAssessments> {
|
|
971
1357
|
complete?: boolean;
|
|
972
1358
|
}
|
|
973
1359
|
```
|
|
@@ -1109,6 +1495,12 @@ interface Schema {
|
|
|
1109
1495
|
SDKPackage?: SDKPackage;
|
|
1110
1496
|
SDKEngine?: SDKEngine;
|
|
1111
1497
|
SDKCapability?: SDKCapability;
|
|
1498
|
+
BenchmarkField?: BenchmarkField;
|
|
1499
|
+
BenchmarkDefinition?: BenchmarkDefinition;
|
|
1500
|
+
SDKBenchmark?: SDKBenchmark;
|
|
1501
|
+
AssessmentBand?: AssessmentBand;
|
|
1502
|
+
AssessmentDefinition?: AssessmentDefinition;
|
|
1503
|
+
SDKAssessment?: SDKAssessment;
|
|
1112
1504
|
SDKScenario?: SDKScenario;
|
|
1113
1505
|
SDKUserInterface?: SDKUserInterface;
|
|
1114
1506
|
SDKSetup?: SDKSetup;
|
|
@@ -1130,6 +1522,26 @@ interface Schema {
|
|
|
1130
1522
|
}
|
|
1131
1523
|
```
|
|
1132
1524
|
|
|
1525
|
+
### SDKAssessment
|
|
1526
|
+
|
|
1527
|
+
Bundle containing an assessment definition
|
|
1528
|
+
|
|
1529
|
+
```ts
|
|
1530
|
+
interface SDKAssessment {
|
|
1531
|
+
definition: AssessmentDefinition;
|
|
1532
|
+
}
|
|
1533
|
+
```
|
|
1534
|
+
|
|
1535
|
+
### SDKBenchmark
|
|
1536
|
+
|
|
1537
|
+
Bundle containing a benchmark definition
|
|
1538
|
+
|
|
1539
|
+
```ts
|
|
1540
|
+
interface SDKBenchmark {
|
|
1541
|
+
definition: BenchmarkDefinition;
|
|
1542
|
+
}
|
|
1543
|
+
```
|
|
1544
|
+
|
|
1133
1545
|
### SDKCapability
|
|
1134
1546
|
|
|
1135
1547
|
Bundle containing a capability definition
|
|
@@ -1359,6 +1771,11 @@ interface SessionUserInterfaceCallbacks {
|
|
|
1359
1771
|
getPastState: <T = Record<string, unknown>>(
|
|
1360
1772
|
query: PastStateQuery<T>
|
|
1361
1773
|
) => Promise<PastStateEntry<T>[]>;
|
|
1774
|
+
getBenchmark: (
|
|
1775
|
+
identifier: string,
|
|
1776
|
+
query?: BenchmarkQuery
|
|
1777
|
+
) => Promise<BenchmarkStatistics | null>;
|
|
1778
|
+
getAssessment: (identifier: string) => Promise<AssessmentReport>;
|
|
1362
1779
|
requestTick: (teamId?: string) => Promise<void>;
|
|
1363
1780
|
pauseTimer: (teamId?: string) => Promise<void>;
|
|
1364
1781
|
resumeTimer: (teamId?: string) => Promise<void>;
|
|
@@ -1553,6 +1970,8 @@ interface TimerState {
|
|
|
1553
1970
|
pausedMs: number;
|
|
1554
1971
|
extendedMs: number;
|
|
1555
1972
|
scheduleStartedAt: number | null;
|
|
1973
|
+
dormant?: boolean;
|
|
1974
|
+
dormantAt?: number | null;
|
|
1556
1975
|
}
|
|
1557
1976
|
```
|
|
1558
1977
|
|
|
@@ -1571,6 +1990,11 @@ interface UserInterfaceCallbacks {
|
|
|
1571
1990
|
getPastState: <T = Record<string, unknown>>(
|
|
1572
1991
|
query: PastStateQuery<T>
|
|
1573
1992
|
) => Promise<PastStateEntry<T>[]>;
|
|
1993
|
+
getBenchmark: (
|
|
1994
|
+
identifier: string,
|
|
1995
|
+
query?: BenchmarkQuery
|
|
1996
|
+
) => Promise<BenchmarkStatistics | null>;
|
|
1997
|
+
getAssessment: (identifier: string) => Promise<AssessmentReport>;
|
|
1574
1998
|
getAllTeamsParticipants: () => Promise<Participant[]>;
|
|
1575
1999
|
endpoints: Record<string, (request: unknown) => Promise<unknown>>;
|
|
1576
2000
|
setThemePreference: (preference: ThemePreference) => void;
|
|
@@ -1658,6 +2082,341 @@ Runtime callback API (a service) a logic-bearing resource is permitted to invoke
|
|
|
1658
2082
|
type ApiUse = 'generateText' | 'extractText' | 'generateSpeech' | 'writeBlob';
|
|
1659
2083
|
```
|
|
1660
2084
|
|
|
2085
|
+
### AssessmentAudience
|
|
2086
|
+
|
|
2087
|
+
Which results a report holds: everyone's, one team's, or one participant's own.
|
|
2088
|
+
|
|
2089
|
+
```ts
|
|
2090
|
+
type AssessmentAudience =
|
|
2091
|
+
| {
|
|
2092
|
+
kind: 'all';
|
|
2093
|
+
}
|
|
2094
|
+
| {
|
|
2095
|
+
kind: 'team';
|
|
2096
|
+
teamId: string;
|
|
2097
|
+
}
|
|
2098
|
+
| {
|
|
2099
|
+
kind: 'participant';
|
|
2100
|
+
teamId: string;
|
|
2101
|
+
participantId: string;
|
|
2102
|
+
};
|
|
2103
|
+
```
|
|
2104
|
+
|
|
2105
|
+
### AssessmentLevel
|
|
2106
|
+
|
|
2107
|
+
Whether an assessment is scored once per participant or once per team.
|
|
2108
|
+
|
|
2109
|
+
```ts
|
|
2110
|
+
type AssessmentLevel = 'participant' | 'team';
|
|
2111
|
+
```
|
|
2112
|
+
|
|
2113
|
+
### AssessmentRecordWrite
|
|
2114
|
+
|
|
2115
|
+
A write to one result. A patch over the current record: a field set to `null` is removed. `null` in place of the whole write removes the result. A result always has a score, so the first write must carry one.
|
|
2116
|
+
|
|
2117
|
+
```ts
|
|
2118
|
+
type AssessmentRecordWrite = {
|
|
2119
|
+
score?: number;
|
|
2120
|
+
feedback?: string | null;
|
|
2121
|
+
final?: boolean | null;
|
|
2122
|
+
} | null;
|
|
2123
|
+
```
|
|
2124
|
+
|
|
2125
|
+
### AssessmentSettings
|
|
2126
|
+
|
|
2127
|
+
The built-in `assessments` settings as they resolve: each assessment's bands, by band id, with their threshold and pass.
|
|
2128
|
+
|
|
2129
|
+
```ts
|
|
2130
|
+
type AssessmentSettings = Record<string, Record<string, AssessmentBandSetting>>;
|
|
2131
|
+
```
|
|
2132
|
+
|
|
2133
|
+
### AssessmentWrite
|
|
2134
|
+
|
|
2135
|
+
The write for one assessment: a record write for a team-level assessment, or record writes by participant id for a participant-level one, where `null` in place of the whole write removes every result.
|
|
2136
|
+
|
|
2137
|
+
```ts
|
|
2138
|
+
type AssessmentWrite<TRecords> = TRecords extends {
|
|
2139
|
+
score: unknown;
|
|
2140
|
+
}
|
|
2141
|
+
? AssessmentRecordWrite
|
|
2142
|
+
: {
|
|
2143
|
+
[participantId: string]: AssessmentRecordWrite;
|
|
2144
|
+
} | null;
|
|
2145
|
+
```
|
|
2146
|
+
|
|
2147
|
+
### AssessmentWrites
|
|
2148
|
+
|
|
2149
|
+
The writes an engine result carries under `assessments`, by identifier.
|
|
2150
|
+
|
|
2151
|
+
```ts
|
|
2152
|
+
type AssessmentWrites<TAssessments> = {
|
|
2153
|
+
[K in keyof TAssessments]?: AssessmentWrite<TAssessments[K]>;
|
|
2154
|
+
};
|
|
2155
|
+
```
|
|
2156
|
+
|
|
2157
|
+
### BenchmarkField
|
|
2158
|
+
|
|
2159
|
+
One field of a benchmark: a number, pooled as a distribution, or one of a short declared list of options, pooled as a count per option
|
|
2160
|
+
|
|
2161
|
+
```ts
|
|
2162
|
+
type BenchmarkField =
|
|
2163
|
+
| {
|
|
2164
|
+
type: 'number';
|
|
2165
|
+
description?: string;
|
|
2166
|
+
}
|
|
2167
|
+
| {
|
|
2168
|
+
enum:
|
|
2169
|
+
| [string]
|
|
2170
|
+
| [string, string]
|
|
2171
|
+
| [string, string, string]
|
|
2172
|
+
| [string, string, string, string]
|
|
2173
|
+
| [string, string, string, string, string]
|
|
2174
|
+
| [string, string, string, string, string, string]
|
|
2175
|
+
| [string, string, string, string, string, string, string]
|
|
2176
|
+
| [string, string, string, string, string, string, string, string]
|
|
2177
|
+
| [string, string, string, string, string, string, string, string, string]
|
|
2178
|
+
| [string, string, string, string, string, string, string, string, string, string]
|
|
2179
|
+
| [
|
|
2180
|
+
string,
|
|
2181
|
+
string,
|
|
2182
|
+
string,
|
|
2183
|
+
string,
|
|
2184
|
+
string,
|
|
2185
|
+
string,
|
|
2186
|
+
string,
|
|
2187
|
+
string,
|
|
2188
|
+
string,
|
|
2189
|
+
string,
|
|
2190
|
+
string,
|
|
2191
|
+
]
|
|
2192
|
+
| [
|
|
2193
|
+
string,
|
|
2194
|
+
string,
|
|
2195
|
+
string,
|
|
2196
|
+
string,
|
|
2197
|
+
string,
|
|
2198
|
+
string,
|
|
2199
|
+
string,
|
|
2200
|
+
string,
|
|
2201
|
+
string,
|
|
2202
|
+
string,
|
|
2203
|
+
string,
|
|
2204
|
+
string,
|
|
2205
|
+
]
|
|
2206
|
+
| [
|
|
2207
|
+
string,
|
|
2208
|
+
string,
|
|
2209
|
+
string,
|
|
2210
|
+
string,
|
|
2211
|
+
string,
|
|
2212
|
+
string,
|
|
2213
|
+
string,
|
|
2214
|
+
string,
|
|
2215
|
+
string,
|
|
2216
|
+
string,
|
|
2217
|
+
string,
|
|
2218
|
+
string,
|
|
2219
|
+
string,
|
|
2220
|
+
]
|
|
2221
|
+
| [
|
|
2222
|
+
string,
|
|
2223
|
+
string,
|
|
2224
|
+
string,
|
|
2225
|
+
string,
|
|
2226
|
+
string,
|
|
2227
|
+
string,
|
|
2228
|
+
string,
|
|
2229
|
+
string,
|
|
2230
|
+
string,
|
|
2231
|
+
string,
|
|
2232
|
+
string,
|
|
2233
|
+
string,
|
|
2234
|
+
string,
|
|
2235
|
+
string,
|
|
2236
|
+
]
|
|
2237
|
+
| [
|
|
2238
|
+
string,
|
|
2239
|
+
string,
|
|
2240
|
+
string,
|
|
2241
|
+
string,
|
|
2242
|
+
string,
|
|
2243
|
+
string,
|
|
2244
|
+
string,
|
|
2245
|
+
string,
|
|
2246
|
+
string,
|
|
2247
|
+
string,
|
|
2248
|
+
string,
|
|
2249
|
+
string,
|
|
2250
|
+
string,
|
|
2251
|
+
string,
|
|
2252
|
+
string,
|
|
2253
|
+
]
|
|
2254
|
+
| [
|
|
2255
|
+
string,
|
|
2256
|
+
string,
|
|
2257
|
+
string,
|
|
2258
|
+
string,
|
|
2259
|
+
string,
|
|
2260
|
+
string,
|
|
2261
|
+
string,
|
|
2262
|
+
string,
|
|
2263
|
+
string,
|
|
2264
|
+
string,
|
|
2265
|
+
string,
|
|
2266
|
+
string,
|
|
2267
|
+
string,
|
|
2268
|
+
string,
|
|
2269
|
+
string,
|
|
2270
|
+
string,
|
|
2271
|
+
]
|
|
2272
|
+
| [
|
|
2273
|
+
string,
|
|
2274
|
+
string,
|
|
2275
|
+
string,
|
|
2276
|
+
string,
|
|
2277
|
+
string,
|
|
2278
|
+
string,
|
|
2279
|
+
string,
|
|
2280
|
+
string,
|
|
2281
|
+
string,
|
|
2282
|
+
string,
|
|
2283
|
+
string,
|
|
2284
|
+
string,
|
|
2285
|
+
string,
|
|
2286
|
+
string,
|
|
2287
|
+
string,
|
|
2288
|
+
string,
|
|
2289
|
+
string,
|
|
2290
|
+
]
|
|
2291
|
+
| [
|
|
2292
|
+
string,
|
|
2293
|
+
string,
|
|
2294
|
+
string,
|
|
2295
|
+
string,
|
|
2296
|
+
string,
|
|
2297
|
+
string,
|
|
2298
|
+
string,
|
|
2299
|
+
string,
|
|
2300
|
+
string,
|
|
2301
|
+
string,
|
|
2302
|
+
string,
|
|
2303
|
+
string,
|
|
2304
|
+
string,
|
|
2305
|
+
string,
|
|
2306
|
+
string,
|
|
2307
|
+
string,
|
|
2308
|
+
string,
|
|
2309
|
+
string,
|
|
2310
|
+
]
|
|
2311
|
+
| [
|
|
2312
|
+
string,
|
|
2313
|
+
string,
|
|
2314
|
+
string,
|
|
2315
|
+
string,
|
|
2316
|
+
string,
|
|
2317
|
+
string,
|
|
2318
|
+
string,
|
|
2319
|
+
string,
|
|
2320
|
+
string,
|
|
2321
|
+
string,
|
|
2322
|
+
string,
|
|
2323
|
+
string,
|
|
2324
|
+
string,
|
|
2325
|
+
string,
|
|
2326
|
+
string,
|
|
2327
|
+
string,
|
|
2328
|
+
string,
|
|
2329
|
+
string,
|
|
2330
|
+
string,
|
|
2331
|
+
]
|
|
2332
|
+
| [
|
|
2333
|
+
string,
|
|
2334
|
+
string,
|
|
2335
|
+
string,
|
|
2336
|
+
string,
|
|
2337
|
+
string,
|
|
2338
|
+
string,
|
|
2339
|
+
string,
|
|
2340
|
+
string,
|
|
2341
|
+
string,
|
|
2342
|
+
string,
|
|
2343
|
+
string,
|
|
2344
|
+
string,
|
|
2345
|
+
string,
|
|
2346
|
+
string,
|
|
2347
|
+
string,
|
|
2348
|
+
string,
|
|
2349
|
+
string,
|
|
2350
|
+
string,
|
|
2351
|
+
string,
|
|
2352
|
+
string,
|
|
2353
|
+
];
|
|
2354
|
+
description?: string;
|
|
2355
|
+
};
|
|
2356
|
+
```
|
|
2357
|
+
|
|
2358
|
+
### BenchmarkFieldStatistics
|
|
2359
|
+
|
|
2360
|
+
```ts
|
|
2361
|
+
type BenchmarkFieldStatistics = NumericBenchmarkStatistics | ChoiceBenchmarkStatistics;
|
|
2362
|
+
```
|
|
2363
|
+
|
|
2364
|
+
### BenchmarkFilter
|
|
2365
|
+
|
|
2366
|
+
A filter on tag values. `{}` matches every record.
|
|
2367
|
+
|
|
2368
|
+
```ts
|
|
2369
|
+
type BenchmarkFilter = Record<string, string>;
|
|
2370
|
+
```
|
|
2371
|
+
|
|
2372
|
+
### BenchmarkRecord
|
|
2373
|
+
|
|
2374
|
+
One benchmark record as the engine reads and writes it: the declared fields, the tags it is grouped by, and whether it is withdrawn. Every field is optional, because a record may be filled in round by round.
|
|
2375
|
+
|
|
2376
|
+
```ts
|
|
2377
|
+
type BenchmarkRecord<
|
|
2378
|
+
TFields extends Record<string, unknown> = Record<string, number | string>,
|
|
2379
|
+
TTags extends string = string,
|
|
2380
|
+
> = {
|
|
2381
|
+
[K in keyof TFields]?: TFields[K];
|
|
2382
|
+
} & {
|
|
2383
|
+
tags?: {
|
|
2384
|
+
[K in TTags]?: string;
|
|
2385
|
+
};
|
|
2386
|
+
excluded?: boolean;
|
|
2387
|
+
};
|
|
2388
|
+
```
|
|
2389
|
+
|
|
2390
|
+
### BenchmarkScope
|
|
2391
|
+
|
|
2392
|
+
Whose results were pooled, for a user interface to say so. The runtime decides it; the game only shows it.
|
|
2393
|
+
|
|
2394
|
+
```ts
|
|
2395
|
+
type BenchmarkScope = 'organisation' | 'global';
|
|
2396
|
+
```
|
|
2397
|
+
|
|
2398
|
+
### BenchmarkWrite
|
|
2399
|
+
|
|
2400
|
+
A write to one benchmark, as an engine returns it under `benchmarks`. It is a patch, merged one level deep over the current record: a field set to `null` is removed, and `tags` replaces the record's tags whole. `null` in place of the whole write removes the record.
|
|
2401
|
+
|
|
2402
|
+
```ts
|
|
2403
|
+
type BenchmarkWrite<TRecord> =
|
|
2404
|
+
| {
|
|
2405
|
+
[K in keyof TRecord]?: TRecord[K] | null;
|
|
2406
|
+
}
|
|
2407
|
+
| null;
|
|
2408
|
+
```
|
|
2409
|
+
|
|
2410
|
+
### BenchmarkWrites
|
|
2411
|
+
|
|
2412
|
+
The writes an engine result carries under `benchmarks`, by identifier.
|
|
2413
|
+
|
|
2414
|
+
```ts
|
|
2415
|
+
type BenchmarkWrites<TBenchmarks> = {
|
|
2416
|
+
[K in keyof TBenchmarks]?: BenchmarkWrite<TBenchmarks[K]>;
|
|
2417
|
+
};
|
|
2418
|
+
```
|
|
2419
|
+
|
|
1661
2420
|
### ContentBlock
|
|
1662
2421
|
|
|
1663
2422
|
A content block inside an LLM message or response.
|
|
@@ -2063,6 +2822,9 @@ type InitAggregateFunction<
|
|
|
2063
2822
|
TCallbacks = SignatureCallbacks,
|
|
2064
2823
|
TTeamState = never,
|
|
2065
2824
|
TSharedState = never,
|
|
2825
|
+
TTeamBenchmarks = never,
|
|
2826
|
+
TSessionBenchmarks = never,
|
|
2827
|
+
TTeamAssessments = never,
|
|
2066
2828
|
> = (
|
|
2067
2829
|
args: RunAggregateFunctionArgs<
|
|
2068
2830
|
TTeamContext,
|
|
@@ -2070,9 +2832,22 @@ type InitAggregateFunction<
|
|
|
2070
2832
|
TSettings,
|
|
2071
2833
|
TCallbacks,
|
|
2072
2834
|
TTeamState,
|
|
2073
|
-
TSharedState
|
|
2835
|
+
TSharedState,
|
|
2836
|
+
TTeamBenchmarks,
|
|
2837
|
+
TSessionBenchmarks,
|
|
2838
|
+
TTeamAssessments
|
|
2074
2839
|
>
|
|
2075
|
-
) => Promise<
|
|
2840
|
+
) => Promise<
|
|
2841
|
+
RunAggregateResult<
|
|
2842
|
+
TTeamContext,
|
|
2843
|
+
TSharedContext,
|
|
2844
|
+
TTeamState,
|
|
2845
|
+
TSharedState,
|
|
2846
|
+
TTeamBenchmarks,
|
|
2847
|
+
TSessionBenchmarks,
|
|
2848
|
+
TTeamAssessments
|
|
2849
|
+
>
|
|
2850
|
+
>;
|
|
2076
2851
|
```
|
|
2077
2852
|
|
|
2078
2853
|
### InitializationFunction
|
|
@@ -2083,9 +2858,11 @@ type InitializationFunction<
|
|
|
2083
2858
|
TSettings = unknown,
|
|
2084
2859
|
TCallbacks = SignatureCallbacks,
|
|
2085
2860
|
TState = never,
|
|
2861
|
+
TBenchmarks = never,
|
|
2862
|
+
TAssessments = never,
|
|
2086
2863
|
> = (
|
|
2087
|
-
args: EngineFunctionArgs<TContext, TSettings, TCallbacks, TState>
|
|
2088
|
-
) => Promise<EngineResult<TContext, TState>>;
|
|
2864
|
+
args: EngineFunctionArgs<TContext, TSettings, TCallbacks, TState, TBenchmarks, TAssessments>
|
|
2865
|
+
) => Promise<EngineResult<TContext, TState, TBenchmarks, TAssessments>>;
|
|
2089
2866
|
```
|
|
2090
2867
|
|
|
2091
2868
|
### LLMGenerateFunction
|
|
@@ -2121,6 +2898,14 @@ type LogicCallbacks<Uses extends ApiUse = never> = Required<Pick<SignatureCallba
|
|
|
2121
2898
|
UngatedSignatureCallbacks;
|
|
2122
2899
|
```
|
|
2123
2900
|
|
|
2901
|
+
### ParticipantAssessmentRecords
|
|
2902
|
+
|
|
2903
|
+
A participant-level assessment's records, by participant id.
|
|
2904
|
+
|
|
2905
|
+
```ts
|
|
2906
|
+
type ParticipantAssessmentRecords = Record<string, AssessmentRecord>;
|
|
2907
|
+
```
|
|
2908
|
+
|
|
2124
2909
|
### RequestTickFunction
|
|
2125
2910
|
|
|
2126
2911
|
A validator's `RequestTick` export: the gate on a participant's request for the next tick. Only a player surface's request reaches it; the facilitator's ticks, the timer's and every system-trusted caller's pass straight through.
|
|
@@ -2141,6 +2926,9 @@ type RunAggregateFunction<
|
|
|
2141
2926
|
TCallbacks = SignatureCallbacks,
|
|
2142
2927
|
TTeamState = never,
|
|
2143
2928
|
TSharedState = never,
|
|
2929
|
+
TTeamBenchmarks = never,
|
|
2930
|
+
TSessionBenchmarks = never,
|
|
2931
|
+
TTeamAssessments = never,
|
|
2144
2932
|
> = (
|
|
2145
2933
|
args: RunAggregateFunctionArgs<
|
|
2146
2934
|
TTeamContext,
|
|
@@ -2148,9 +2936,22 @@ type RunAggregateFunction<
|
|
|
2148
2936
|
TSettings,
|
|
2149
2937
|
TCallbacks,
|
|
2150
2938
|
TTeamState,
|
|
2151
|
-
TSharedState
|
|
2939
|
+
TSharedState,
|
|
2940
|
+
TTeamBenchmarks,
|
|
2941
|
+
TSessionBenchmarks,
|
|
2942
|
+
TTeamAssessments
|
|
2943
|
+
>
|
|
2944
|
+
) => Promise<
|
|
2945
|
+
RunAggregateTickResult<
|
|
2946
|
+
TTeamContext,
|
|
2947
|
+
TSharedContext,
|
|
2948
|
+
TTeamState,
|
|
2949
|
+
TSharedState,
|
|
2950
|
+
TTeamBenchmarks,
|
|
2951
|
+
TSessionBenchmarks,
|
|
2952
|
+
TTeamAssessments
|
|
2152
2953
|
>
|
|
2153
|
-
|
|
2954
|
+
>;
|
|
2154
2955
|
```
|
|
2155
2956
|
|
|
2156
2957
|
### RunFunction
|
|
@@ -2161,9 +2962,11 @@ type RunFunction<
|
|
|
2161
2962
|
TSettings = unknown,
|
|
2162
2963
|
TCallbacks = SignatureCallbacks,
|
|
2163
2964
|
TState = never,
|
|
2965
|
+
TBenchmarks = never,
|
|
2966
|
+
TAssessments = never,
|
|
2164
2967
|
> = (
|
|
2165
|
-
args: EngineFunctionArgs<TContext, TSettings, TCallbacks, TState>
|
|
2166
|
-
) => Promise<RunResult<TContext, TState>>;
|
|
2968
|
+
args: EngineFunctionArgs<TContext, TSettings, TCallbacks, TState, TBenchmarks, TAssessments>
|
|
2969
|
+
) => Promise<RunResult<TContext, TState, TBenchmarks, TAssessments>>;
|
|
2167
2970
|
```
|
|
2168
2971
|
|
|
2169
2972
|
### RunKind
|
|
@@ -2215,7 +3018,19 @@ type StepFunction<
|
|
|
2215
3018
|
TSettings = unknown,
|
|
2216
3019
|
TCallbacks = SignatureCallbacks,
|
|
2217
3020
|
TState = unknown,
|
|
2218
|
-
|
|
3021
|
+
TBenchmarks = unknown,
|
|
3022
|
+
TAssessments = unknown,
|
|
3023
|
+
> = (
|
|
3024
|
+
args: EngineFunctionArgs<TContext, TSettings, TCallbacks, TState, TBenchmarks, TAssessments>
|
|
3025
|
+
) => Promise<TContext>;
|
|
3026
|
+
```
|
|
3027
|
+
|
|
3028
|
+
### TeamAssessmentRecord
|
|
3029
|
+
|
|
3030
|
+
A team-level assessment's record: one result for the whole team.
|
|
3031
|
+
|
|
3032
|
+
```ts
|
|
3033
|
+
type TeamAssessmentRecord = AssessmentRecord;
|
|
2219
3034
|
```
|
|
2220
3035
|
|
|
2221
3036
|
### ThemePreference
|