@seriousgaming/sdk-tools 1.3.0 → 1.4.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/cli.js +3216 -2538
- package/dist/client.js +693 -161
- package/dist/core/session-host.d.ts +4 -2
- package/dist/core/settings-locks.d.ts +27 -2
- package/dist/dev/console/assets/{index-DEV8N0na.js → index-BvB-LFQZ.js} +10 -10
- package/dist/dev/console/index.html +1 -1
- package/dist/dev/routes.d.ts +4 -0
- package/dist/dev/view/batch.d.ts +7 -1
- package/dist/docs/api/index.md +1 -1
- package/dist/docs/api/sdk-tools-client.md +1 -0
- package/dist/docs/api/sdk.md +79 -2
- package/dist/docs/changelog.md +25 -0
- package/dist/docs/concepts/terminology.md +1 -1
- package/dist/docs/guides/capabilities.md +2 -0
- package/dist/docs/guides/endpoints.md +2 -2
- package/dist/docs/guides/engine-testing.md +1 -1
- package/dist/docs/guides/file-handling.md +113 -21
- package/dist/docs/guides/llm-integration.md +1 -1
- package/dist/docs/guides/scenario-editor.md +1 -1
- package/dist/docs/guides/scenarios.md +9 -1
- package/dist/docs/guides/settings.md +62 -2
- package/dist/docs/guides/validators.md +62 -4
- package/dist/docs/recipes/upload-and-display-files.md +7 -7
- package/dist/docs/recipes/validate-scenarios.md +4 -1
- package/dist/execution/endpoint-runner.d.ts +6 -0
- package/dist/execution/logic-calls.d.ts +7 -2
- package/dist/execution/scenario-gates.d.ts +21 -1
- package/dist/guide/settings.d.ts +1 -1
- package/dist/host.js +64 -2
- package/dist/runtime/manifest-version.d.ts +1 -1
- package/dist/runtime.js +7 -2
- package/dist/storage/asset-resolver.d.ts +24 -1
- package/dist/storage/blob-store.d.ts +7 -0
- package/dist/utils/local-refs.d.ts +40 -0
- package/dist/utils/schema-members.d.ts +19 -0
- package/package.json +3 -3
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
6
6
|
<link rel="icon" type="image/svg+xml" href="/assets/icon-CRaj5uhr.svg" />
|
|
7
7
|
<title>Serious Gaming</title>
|
|
8
|
-
<script type="module" crossorigin src="/assets/index-
|
|
8
|
+
<script type="module" crossorigin src="/assets/index-BvB-LFQZ.js"></script>
|
|
9
9
|
<link rel="stylesheet" crossorigin href="/assets/index-q6-lvlN3.css">
|
|
10
10
|
</head>
|
|
11
11
|
<body>
|
package/dist/dev/routes.d.ts
CHANGED
|
@@ -48,12 +48,16 @@ declare const ASSET_PATHS: {
|
|
|
48
48
|
readonly '/api': {
|
|
49
49
|
readonly blob: "/api/blobs/:blobId";
|
|
50
50
|
readonly scenario: "/api/scenario/assets/*path";
|
|
51
|
+
readonly editedScenario: "/api/scenarios/:scenario/assets/*path";
|
|
52
|
+
readonly noScenario: "/api/no-scenario/assets/*path";
|
|
51
53
|
readonly shared: "/api/shared/assets/*path";
|
|
52
54
|
readonly redeem: "/api/asset-auth/redeem";
|
|
53
55
|
};
|
|
54
56
|
readonly '/assets': {
|
|
55
57
|
readonly blob: "/assets/blobs/:blobId";
|
|
56
58
|
readonly scenario: "/assets/scenario/*path";
|
|
59
|
+
readonly editedScenario: "/assets/scenarios/:scenario/*path";
|
|
60
|
+
readonly noScenario: "/assets/no-scenario/*path";
|
|
57
61
|
readonly shared: "/assets/shared/*path";
|
|
58
62
|
readonly redeem: "/assets/auth/redeem";
|
|
59
63
|
};
|
package/dist/dev/view/batch.d.ts
CHANGED
|
@@ -114,8 +114,14 @@ export declare function themeMessages(theme: Theme): HostMessage[];
|
|
|
114
114
|
*
|
|
115
115
|
* On the asset origin, beside the bundles, so a frame reads them as its own
|
|
116
116
|
* origin under `connect-src 'self'` and never needs the console's.
|
|
117
|
+
*
|
|
118
|
+
* `asset:` resolves against the session's scenario, except in the scenario
|
|
119
|
+
* editor, which reads the files of the scenario it is open on whatever the
|
|
120
|
+
* session runs (§6.5), and none when it is open on no scenario (§6.7).
|
|
117
121
|
*/
|
|
118
|
-
export declare function assetUrls(assetOrigin: string
|
|
122
|
+
export declare function assetUrls(assetOrigin: string, editing?: {
|
|
123
|
+
scenario: string | null;
|
|
124
|
+
}): Record<string, string>;
|
|
119
125
|
/**
|
|
120
126
|
* The whole initial batch for one surface.
|
|
121
127
|
*
|
package/dist/docs/api/index.md
CHANGED
|
@@ -6,7 +6,7 @@ Every type, function, hook and component your game imports, one page per entry p
|
|
|
6
6
|
|
|
7
7
|
| Entry point | Exports |
|
|
8
8
|
| ---------------------------------------------------------- | -------------------------------------------------------------- |
|
|
9
|
-
| [`@seriousgaming/sdk`](./sdk.md) |
|
|
9
|
+
| [`@seriousgaming/sdk`](./sdk.md) | 12 functions, 3 classes, 1 constant, 100 interfaces, 48 types |
|
|
10
10
|
| [`@seriousgaming/sdk/ui`](./sdk-ui.md) | 49 functions, 3 classes, 39 constants, 26 interfaces, 37 types |
|
|
11
11
|
| [`@seriousgaming/sdk/ui/testing`](./sdk-ui-testing.md) | 14 functions, 6 types |
|
|
12
12
|
| [`@seriousgaming/sdk/testing`](./sdk-testing.md) | 8 functions, 4 constants, 8 types |
|
|
@@ -129,6 +129,7 @@ Every callback a runtime may offer logic: the engine, hooks, tick controllers an
|
|
|
129
129
|
interface SignatureCallbacks {
|
|
130
130
|
generateText: LLMGenerateFunction;
|
|
131
131
|
readAsset: (reference: string) => Promise<ReadAssetResponse>;
|
|
132
|
+
describeAsset?: (reference: string) => Promise<AssetDescription | undefined>;
|
|
132
133
|
getPastState: <T = Record<string, unknown>>(
|
|
133
134
|
query: PastStateQuery<T>
|
|
134
135
|
) => Promise<PastStateEntry<T>[]>;
|
package/dist/docs/api/sdk.md
CHANGED
|
@@ -86,6 +86,14 @@ function nextWeeklyAt(
|
|
|
86
86
|
): number;
|
|
87
87
|
```
|
|
88
88
|
|
|
89
|
+
### parseSettingPath
|
|
90
|
+
|
|
91
|
+
Read a setting path back into its settings identifier and keys, or `undefined` when it is not a setting path. The inverse of `settingPath`: `parseSettingPath('ui.Cast["a.b"].portrait')` is `{ identifier: 'ui', keys: ['Cast', 'a.b', 'portrait'] }`. A plain key written in brackets, `ui["MinPrice"]`, reads as the same key.
|
|
92
|
+
|
|
93
|
+
```ts
|
|
94
|
+
function parseSettingPath(path: string): ParsedSettingPath | undefined;
|
|
95
|
+
```
|
|
96
|
+
|
|
89
97
|
### scheduledTick
|
|
90
98
|
|
|
91
99
|
Convenience builder that creates a `TickControllerResult` for scheduled (absolute-time) ticking.
|
|
@@ -107,6 +115,14 @@ A seeded pseudo-random generator: call it for the next value in `[0, 1)`, like `
|
|
|
107
115
|
function seededRandom(seed: string): () => number;
|
|
108
116
|
```
|
|
109
117
|
|
|
118
|
+
### settingPath
|
|
119
|
+
|
|
120
|
+
The path naming a setting: its settings identifier, then each key below it.
|
|
121
|
+
|
|
122
|
+
```ts
|
|
123
|
+
function settingPath(identifier: string, ...keys: (string | number)[]): string;
|
|
124
|
+
```
|
|
125
|
+
|
|
110
126
|
## Classes
|
|
111
127
|
|
|
112
128
|
### EndpointError
|
|
@@ -124,6 +140,19 @@ class EndpointError extends Error {
|
|
|
124
140
|
}
|
|
125
141
|
```
|
|
126
142
|
|
|
143
|
+
### ScenarioAssetTooLargeError
|
|
144
|
+
|
|
145
|
+
Error a `Scenario` gate's `readAsset` rejects with for a file larger than `SCENARIO_GATE_READ_LIMIT_BYTES`. A gate that lets it escape counts as having thrown, so the build fails, or the save is refused, naming the file. To check a large file's presence or size, call `describeAsset`.
|
|
146
|
+
|
|
147
|
+
```ts
|
|
148
|
+
class ScenarioAssetTooLargeError extends Error {
|
|
149
|
+
readonly reference: string;
|
|
150
|
+
readonly size: number;
|
|
151
|
+
readonly limit: number;
|
|
152
|
+
constructor(reference: string, size: number);
|
|
153
|
+
}
|
|
154
|
+
```
|
|
155
|
+
|
|
127
156
|
### UndeclaredApiUseError
|
|
128
157
|
|
|
129
158
|
Error thrown when a resource invokes a callback it did not declare in its bundle's `uses` array. Carries the offending resource identifier and the callback name so a runtime can surface both to the operator.
|
|
@@ -136,6 +165,16 @@ class UndeclaredApiUseError extends Error {
|
|
|
136
165
|
}
|
|
137
166
|
```
|
|
138
167
|
|
|
168
|
+
## Constants
|
|
169
|
+
|
|
170
|
+
### SCENARIO_GATE_READ_LIMIT_BYTES
|
|
171
|
+
|
|
172
|
+
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.
|
|
173
|
+
|
|
174
|
+
```ts
|
|
175
|
+
const SCENARIO_GATE_READ_LIMIT_BYTES: number;
|
|
176
|
+
```
|
|
177
|
+
|
|
139
178
|
## Interfaces
|
|
140
179
|
|
|
141
180
|
### AggregateFunctionShared
|
|
@@ -160,6 +199,17 @@ interface AggregateFunctionTeam<TTeamContext, TTeamState = never> {
|
|
|
160
199
|
}
|
|
161
200
|
```
|
|
162
201
|
|
|
202
|
+
### AssetDescription
|
|
203
|
+
|
|
204
|
+
Shape returned by `describeAsset`: what a file is, without its bytes.
|
|
205
|
+
|
|
206
|
+
```ts
|
|
207
|
+
interface AssetDescription {
|
|
208
|
+
mimeType: string;
|
|
209
|
+
size: number;
|
|
210
|
+
}
|
|
211
|
+
```
|
|
212
|
+
|
|
163
213
|
### CapabilityDefinition
|
|
164
214
|
|
|
165
215
|
Definition of a capability
|
|
@@ -726,6 +776,17 @@ interface PackageManifest {
|
|
|
726
776
|
}
|
|
727
777
|
```
|
|
728
778
|
|
|
779
|
+
### ParsedSettingPath
|
|
780
|
+
|
|
781
|
+
A setting path read back into the keys `settingPath` wrote it from.
|
|
782
|
+
|
|
783
|
+
```ts
|
|
784
|
+
interface ParsedSettingPath {
|
|
785
|
+
identifier: string;
|
|
786
|
+
keys: string[];
|
|
787
|
+
}
|
|
788
|
+
```
|
|
789
|
+
|
|
729
790
|
### Participant
|
|
730
791
|
|
|
731
792
|
A participant the platform tracks for some team in the session.
|
|
@@ -909,6 +970,17 @@ interface RunResult<TContext, TState = never> extends EngineResult<TContext, TSt
|
|
|
909
970
|
}
|
|
910
971
|
```
|
|
911
972
|
|
|
973
|
+
### ScenarioCallbacks
|
|
974
|
+
|
|
975
|
+
What a `Scenario` gate may call: the two file reads, and nothing else. No text generation and no `extractText`, so the gate stays deterministic.
|
|
976
|
+
|
|
977
|
+
```ts
|
|
978
|
+
interface ScenarioCallbacks {
|
|
979
|
+
readAsset: (reference: string) => Promise<ReadAssetResponse>;
|
|
980
|
+
describeAsset: (reference: string) => Promise<AssetDescription | undefined>;
|
|
981
|
+
}
|
|
982
|
+
```
|
|
983
|
+
|
|
912
984
|
### ScenarioDefinition
|
|
913
985
|
|
|
914
986
|
Definition of a scenario — a named flavour of a game bundling settings overrides and static assets
|
|
@@ -970,12 +1042,13 @@ Arguments of a validator's `Scenario` gate.
|
|
|
970
1042
|
interface ScenarioFunctionArgs<TSettings> {
|
|
971
1043
|
settings: TSettings;
|
|
972
1044
|
locale: string;
|
|
1045
|
+
callbacks?: ScenarioCallbacks;
|
|
973
1046
|
}
|
|
974
1047
|
```
|
|
975
1048
|
|
|
976
1049
|
### ScenarioProblem
|
|
977
1050
|
|
|
978
|
-
One thing wrong with a scenario. `path` names the setting it is about,
|
|
1051
|
+
One thing wrong with a scenario. `path` names the setting it is about as a setting path, from the settings identifier (`ui.MinPrice`), so an editor can show the problem beside the field. Build it with `settingPath`, which writes a key that is not a plain name in brackets (`ui.Cast["a.b"].portrait`).
|
|
979
1052
|
|
|
980
1053
|
```ts
|
|
981
1054
|
interface ScenarioProblem {
|
|
@@ -1364,6 +1437,7 @@ Every callback a runtime may offer logic: the engine, hooks, tick controllers an
|
|
|
1364
1437
|
interface SignatureCallbacks {
|
|
1365
1438
|
generateText: LLMGenerateFunction;
|
|
1366
1439
|
readAsset: (reference: string) => Promise<ReadAssetResponse>;
|
|
1440
|
+
describeAsset?: (reference: string) => Promise<AssetDescription | undefined>;
|
|
1367
1441
|
getPastState: <T = Record<string, unknown>>(
|
|
1368
1442
|
query: PastStateQuery<T>
|
|
1369
1443
|
) => Promise<PastStateEntry<T>[]>;
|
|
@@ -2144,7 +2218,10 @@ type ThemePreference = 'light' | 'dark' | 'system';
|
|
|
2144
2218
|
The `SignatureCallbacks` members that `uses` does not gate.
|
|
2145
2219
|
|
|
2146
2220
|
```ts
|
|
2147
|
-
type UngatedSignatureCallbacks = Pick<
|
|
2221
|
+
type UngatedSignatureCallbacks = Pick<
|
|
2222
|
+
SignatureCallbacks,
|
|
2223
|
+
'readAsset' | 'describeAsset' | 'getPastState'
|
|
2224
|
+
>;
|
|
2148
2225
|
```
|
|
2149
2226
|
|
|
2150
2227
|
### ValidationResult
|
package/dist/docs/changelog.md
CHANGED
|
@@ -31,6 +31,31 @@ are in the [0.x changelog](changelog-0.x.md).
|
|
|
31
31
|
|
|
32
32
|
## [Unreleased]
|
|
33
33
|
|
|
34
|
+
## [1.4.0] — 2026-10-26
|
|
35
|
+
|
|
36
|
+
### Added
|
|
37
|
+
|
|
38
|
+
- **`describeAsset(reference)` tells logic a file's type and size without reading it**, or `undefined` when there is no such file, so checking that a scenario's videos exist no longer reads each one whole. It resolves references exactly as `readAsset` does and needs no `uses` entry. It is optional in `SignatureCallbacks`, so call it with `?.`, and a test that builds its callbacks by hand still compiles; `createStubCallbacks` describes the blobs it wrote. `examples/factory`'s `attachresearch` endpoint answers with the size of the document it attached. See [Checking a file without reading it](guides/file-handling.md#checking-a-file-without-reading-it)
|
|
39
|
+
- **A `Scenario` gate can check the files a scenario names.** List `scenario-files` in `requires`, and the gate receives `callbacks` with `readAsset` and `describeAsset`, resolved against the scenario being judged: its own files at build, a draft's on save. So a scenario naming a missing portrait is refused when it is saved, rather than the rule living again in an endpoint and a test. Without the feature, a call throws, naming it. A gate's `readAsset` reads no file over 10 MB (`SCENARIO_GATE_READ_LIMIT_BYTES`), the same in every runtime: a larger one rejects with a `ScenarioAssetTooLargeError`, which refuses the scenario naming the file, so check a video with `describeAsset`. Once you list it, your generated `ScenarioFunction` requires `callbacks`, so a test calling the gate passes them. `examples/factory`'s `scenariocheck` refuses a branding logo the scenario does not have. See [Checking the files a scenario names](guides/validators.md#checking-the-files-a-scenario-names)
|
|
40
|
+
- **Settings and capability schemas can reuse a shape, and nest it to any depth.** Declare it under `$defs` (or `definitions`) and use it with a local `$ref`, from inside itself included, so recursive data such as a rule whose branches are rules is checked at every level. `pnpm run sdk generate` used to fail on any `$ref` with `MissingPointerError`; it now emits one type per shape, so `"$ref": "#/$defs/rule"` is typed `Rule`, and a shape containing itself is an interface naming itself. The build refuses a `$ref` that names nothing or reaches outside its own schema, and scenarios, setup writes, scenario drafts, file settings and guide conditions all follow it. See [Reuse a shape, or nest it to any depth](guides/settings.md#reuse-a-shape-or-nest-it-to-any-depth). A schema is still JSON Schema Draft 7, read the same way whatever `$schema` it names; `$defs` and keywords beside a `$ref` are the two later-draft features it takes
|
|
41
|
+
|
|
42
|
+
- **`settingPath` and `parseSettingPath` build and read a setting path.** Use `settingPath('ui', 'Cast', key)` for a `Scenario` gate's problem `path` rather than joining keys with dots, so an editor reads back a map entry whose key holds a dot. See [How a setting is named](./guides/settings.md#how-a-setting-is-named)
|
|
43
|
+
|
|
44
|
+
### Changed
|
|
45
|
+
|
|
46
|
+
- **A package file's media type comes from one table.** The dev server serves a scenario or shared file, and `readAsset` reports it, under the type its extension names in the same table the build checks a file setting's `accept` against, so a file is served as the type it was accepted as. The table now also covers Office and OpenDocument files (`.docx`, `.xlsx`, `.pptx` and their older and open forms), `.zip`, `.xml`, `.yaml`, `.js` and `.mjs`, `.rtf`, more audio and video (`.m4a`, `.aac`, `.flac`, `.mov`, `.m4v`), and `.avif`, `.bmp`, `.tif`, `.vtt`, `.ttf` and `.otf`. A file with an extension the table does not list is `application/octet-stream`, where the dev server used to guess. The table is in the [file handling guide](guides/file-handling.md#media-types)
|
|
47
|
+
- **A custom scenario reads the files of the built-in scenario it was copied from.** An `asset:` reference your code builds, which copying a scenario cannot convert, resolves against that scenario, through any copies of copies, and a runtime refuses a custom scenario whose built-in scenario your release no longer ships. Bump `scenarioFormat` when you move or remove a built-in scenario's files. See [Files a custom scenario reads](guides/scenarios.md#files-a-custom-scenario-reads). A copy of a restricted scenario is restricted with it, offered only to callers granted the original
|
|
48
|
+
|
|
49
|
+
- **A setting under a key that is not a plain name is named in brackets.** A refusal, a lock's message or a file check naming a setting writes a key that is empty or holds a `.`, `[`, `]`, `"` or space as a JSON string, `ui.Cast["a.b"].portrait`, where it wrote `ui.Cast.a.b.portrait`, which reads two ways. Every path whose keys are plain names reads as before, and a guide's `:setting` and `:::when` read the bracketed form
|
|
50
|
+
|
|
51
|
+
### Fixed
|
|
52
|
+
|
|
53
|
+
- **The dev server answers a byte range of a blob.** A request for part of an uploaded or generated file, as a `<video>` or `<audio>` element makes to seek, was answered with the whole file, so a browser could not seek a blob's video and Safari would not play it. It is answered with `206 Partial Content`, as scenario and shared files already were, and a `HEAD` request carries `Accept-Ranges`
|
|
54
|
+
- **A `readOnly` lock the dev server could not enforce now fails the build.** A lock beneath an array's `items`, or a map's `additionalProperties` or `patternProperties`, was never enforced, so a scenario or a setup screen could change a value the game believed fixed. `sdk build` now refuses it, saying to lock the whole list or map instead. A lock reached through a local `$ref` is now enforced like one written in place, and a scenario naming it is refused
|
|
55
|
+
- **A file inside a keyed map is checked like any other.** A file setting or an endpoint file input declared as the entries of a map, through `additionalProperties` or `patternProperties` (`"Cast": { "additionalProperties": { "properties": { "portrait": { "type": "string", "blob": {...} } } } }`), was never checked: the build passed a scenario naming a file the package does not ship, the dev server stored a setting naming an upload of the wrong type, and an endpoint handler received a `data:` URI or a URL where it expected a `blob:` reference. Each entry is now held to the declaration, named by its key (`cast.Cast.ada.portrait`), and the generated `Request` types it as a `blob:` reference. A document per language is one such map, keyed by locale: see [A file per language](guides/file-handling.md#a-file-per-language)
|
|
56
|
+
- **On the dev server, the scenario editor reads the files of the scenario it is editing.** `getAssetUrl`, `readAsset` and `useAssetUrl` in the editor, and `readAsset` and `extractText` in the scenario-scoped endpoints it calls, resolved `asset:` references against the scenario the session was running. An editor open on any other scenario found that scenario's own files missing, and read the session's copy of any file both scenarios ship. You no longer need to restart the session on a scenario to edit it
|
|
57
|
+
- **An endpoint's generated `Settings` type matches the engine's.** Inside an object-valued setting, the keys its default carries are now required in an endpoint's `types.ts`, as they already were for every other resource, so code shared between an endpoint and the engine can use one type. A test that builds an endpoint's settings by hand may need those keys added; spreading the generated `defaultSettings` supplies them
|
|
58
|
+
|
|
34
59
|
## [1.3.0] — 2026-10-26
|
|
35
60
|
|
|
36
61
|
### Added
|
|
@@ -298,7 +298,7 @@ The quality and cost level of an LLM call. The platform maps each tier to a mode
|
|
|
298
298
|
|
|
299
299
|
### Asset reference
|
|
300
300
|
|
|
301
|
-
A string naming a file the SDK can read: `asset:<path>` for a file in the active scenario's `assets/` directory, or `blob:<id>` for a file uploaded at run time. Every callback that takes a file takes one: `getAssetUrl`, `readAsset`, `extractText`. See [Asset references](../guides/file-handling.md).
|
|
301
|
+
A string naming a file the SDK can read: `asset:<path>` for a file in the active scenario's `assets/` directory, or `blob:<id>` for a file uploaded at run time. Every callback that takes a file takes one: `getAssetUrl`, `readAsset`, `describeAsset`, `extractText`. See [Asset references](../guides/file-handling.md).
|
|
302
302
|
|
|
303
303
|
### Blob
|
|
304
304
|
|
|
@@ -14,6 +14,8 @@ A capability is a named collection of related variables, declared by a schema. F
|
|
|
14
14
|
|
|
15
15
|
Each capability declares its variables in a `variablesSchema`: a full JSON Schema 7 object whose properties are the variables, each with a type, a `default`, and any constraints. Every capability starts from those defaults, so its variables exist from the first tick for anything that declares it.
|
|
16
16
|
|
|
17
|
+
A shape used in several places, or one that contains itself, is declared once under `$defs` and used with a `$ref`, as in a settings schema (see [Reuse a shape, or nest it to any depth](./settings.md#reuse-a-shape-or-nest-it-to-any-depth)). The variable's `default` goes beside the `$ref`.
|
|
18
|
+
|
|
17
19
|
### Context is scoped by capability
|
|
18
20
|
|
|
19
21
|
A team's state, the context, is one object keyed by capability identifier, each value holding that capability's variables:
|
|
@@ -120,7 +120,7 @@ The handler receives:
|
|
|
120
120
|
- `context`: the capabilities listed in `reads` and `writes`, and nothing else. On a session-scoped endpoint, only the shared ones (see above)
|
|
121
121
|
- `team`: on a team-scoped endpoint, the team the call acts on. `teams`: on a session-scoped one, every team's declared values
|
|
122
122
|
- `settings`: exactly the settings resources listed in `settings`, keyed by identifier, read-only
|
|
123
|
-
- `callbacks`: the callbacks named in `uses`, plus the ungated `readAsset` and `getPastState`. An undeclared gated callback throws
|
|
123
|
+
- `callbacks`: the callbacks named in `uses`, plus the ungated `readAsset`, `describeAsset` and `getPastState`. An undeclared gated callback throws
|
|
124
124
|
- `caller`: who is calling, issued by the host and never by the iframe (see below)
|
|
125
125
|
- `meta`: the facts true of the whole run: `meta.locale` (the session locale), `meta.seed`, `meta.runKind`, `meta.now`, the instant the call started, and `meta.scenarioName`, the active scenario's name for display
|
|
126
126
|
- `participants`: a read-only copy of the roster the call covers, the addressed team's on a team-scoped endpoint and every participant on a session-scoped one
|
|
@@ -284,7 +284,7 @@ A request field can be a file. Mark a string property with `blob`, saying which
|
|
|
284
284
|
}
|
|
285
285
|
```
|
|
286
286
|
|
|
287
|
-
The handler always receives a `blob:` reference, typed `` `blob:${string}` ``, already checked against the declaration. It reads the file with `callbacks.readAsset`, passes it to `extractText`, or stores the reference in a capability for a screen to show with `getAssetUrl`.
|
|
287
|
+
The handler always receives a `blob:` reference, typed `` `blob:${string}` ``, already checked against the declaration. It reads the file with `callbacks.readAsset`, asks its size with `callbacks.describeAsset`, passes it to `extractText`, or stores the reference in a capability for a screen to show with `getAssetUrl`.
|
|
288
288
|
|
|
289
289
|
The caller sends one of two things:
|
|
290
290
|
|
|
@@ -286,7 +286,7 @@ Tests are offline by default, whether they run a whole session or call one logic
|
|
|
286
286
|
- **`generateSpeech`** stores 100ms of silence as a WAV blob and returns `{ reference: 'blob:<id>', mimeType: 'audio/wav', durationMs: 100, charactersBilled: 0 }`, so `readAsset` resolves it as it would real audio
|
|
287
287
|
- **`extractText`** answers `{ content: '[stub] text of <reference>', mimeType: 'text/plain' }`, without reading the file
|
|
288
288
|
|
|
289
|
-
With no session behind them, the arguments `logicArgs` builds stub the rest as well: `writeBlob` stores in memory and returns `blob:stub-<n>`, `readAsset` reads back only a blob written in the same test (and rejects anything else, `asset:` references included), and `getPastState` answers `[]`.
|
|
289
|
+
With no session behind them, the arguments `logicArgs` builds stub the rest as well: `writeBlob` stores in memory and returns `blob:stub-<n>`, `readAsset` reads back only a blob written in the same test (and rejects anything else, `asset:` references included), `describeAsset` describes only such a blob (and answers `undefined` for anything else), and `getPastState` answers `[]`.
|
|
290
290
|
|
|
291
291
|
| Export | From | Use it to |
|
|
292
292
|
| --------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
|
@@ -30,6 +30,7 @@ Every callback that works on a file takes a reference:
|
|
|
30
30
|
|
|
31
31
|
- **`getAssetUrl(reference)`** returns a URL the browser can fetch, for `<img>`, `<embed>`, `<video>` and the like. Synchronous, and in a UI only. In a hosted runtime the URL is on the runtime's asset host, cross-origin to the surface's iframe. `useAssetUrl` is the hook form
|
|
32
32
|
- **`readAsset(reference)`** returns the bytes, MIME type, and display name. Asynchronous. In logic the runtime resolves the reference server-side; in a UI the SDK fetches the URL with `credentials: 'include'`. `useAsset` is the hook form that reads text, JSON, or a `Blob`
|
|
33
|
+
- **`describeAsset(reference)`** returns the MIME type and size of a file without reading it, or `undefined` when there is no such file. In logic only: a UI can ask its URL with a `HEAD` request
|
|
33
34
|
- **`extractText(reference)`** returns plain text from a PDF. It is offered to the engine, hooks, tick controllers, and endpoints that declare it in `uses`; a UI reaches it through an endpoint
|
|
34
35
|
|
|
35
36
|
In a UI, `getAssetUrl` strips the prefix and appends the rest to an absolute prefix the host supplies for each scheme. Under `sdk dev` those prefixes are on the asset origin (`--asset-port`), so `asset:shared/hero.jpg` becomes `http://localhost:<asset-port>/assets/scenario/shared/hero.jpg`; a hosted runtime points them at its own asset host. With no scenario active an `asset:` reference still produces a URL, which answers 404. A string with none of the three prefixes throws.
|
|
@@ -53,6 +54,44 @@ A scenario writes references with the prefix in place, usually as values of sett
|
|
|
53
54
|
|
|
54
55
|
Here `briefing` is a settings resource (`settings/briefing/`) declaring `Logo` and `ScenarioBrief` as strings with an empty default, which the engine and UI examples below list in their `settings`. The runtime takes these strings as they are: nothing checks at scenario load that the file exists, and a reference that does not resolve fails when something calls `getAssetUrl`, `readAsset`, or `extractText` with it. See [Scenarios](./scenarios.md#2-add-assets-optional) for where the files go.
|
|
55
56
|
|
|
57
|
+
### A file per language
|
|
58
|
+
|
|
59
|
+
A file setting (see [Settings that hold a file](./settings.md#settings-that-hold-a-file)) holds one file. For a document translated per language, key a map by locale and let its entries hold the files: the `blob` declaration goes on the map's `additionalProperties`, so every entry is checked as a file setting of its own:
|
|
60
|
+
|
|
61
|
+
```json
|
|
62
|
+
"Brief": {
|
|
63
|
+
"title": "Briefing document",
|
|
64
|
+
"description": "The briefing as a PDF, one per language, keyed by locale. A language with no entry reads English",
|
|
65
|
+
"type": "object",
|
|
66
|
+
"default": {},
|
|
67
|
+
"propertyNames": { "enum": ["en", "fr"] },
|
|
68
|
+
"additionalProperties": {
|
|
69
|
+
"type": "string",
|
|
70
|
+
"blob": { "accept": ["application/pdf"], "maxBytes": 5242880 }
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
A scenario sets one entry per language it ships:
|
|
76
|
+
|
|
77
|
+
```json
|
|
78
|
+
"briefing": {
|
|
79
|
+
"Brief": { "en": "asset:brief.pdf", "fr": "asset:brief-fr.pdf" }
|
|
80
|
+
}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
The build checks every entry, as it checks a single file setting: each file must be shipped, within `maxBytes`, and of a type `accept` lists, and the error names the entry (`briefing.Brief.fr`). A setup screen, the scenario editor or an agent writing one entry is held to the same declaration, and a scenario may set one language and leave the others to the layer beneath, since a map merges key by key.
|
|
84
|
+
|
|
85
|
+
The game picks the entry for its locale, falling back to the one it always ships:
|
|
86
|
+
|
|
87
|
+
```tsx
|
|
88
|
+
const { settings } = useUserInterfaceData<Context, Settings>();
|
|
89
|
+
const { locale } = useUserInterfaceLocale();
|
|
90
|
+
const src = useAssetUrl(settings.briefing.Brief[locale] ?? settings.briefing.Brief.en);
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Use this when a scenario chooses the files. A file the package ships for every scenario alike can instead sit in a directory named for its locale, which `useAsset` finds on its own (see [Internationalization](./internationalization.md)).
|
|
94
|
+
|
|
56
95
|
### How a file moves through a game
|
|
57
96
|
|
|
58
97
|
```
|
|
@@ -193,6 +232,28 @@ export const Run: RunFunction<Context, Settings> = async ({ context, callbacks }
|
|
|
193
232
|
- `data` is a `Uint8Array`. Use `decodeUtf8` for text formats; pass binary directly to downstream APIs
|
|
194
233
|
- The same callback resolves `asset:shared/brief.pdf` and `blob:abc123`: there is no separate API for bundled and uploaded files
|
|
195
234
|
|
|
235
|
+
## Checking a file without reading it
|
|
236
|
+
|
|
237
|
+
`readAsset` returns every byte, which is waste when you only need to know a file is there, or how big it is: a scenario's videos, say. `describeAsset` resolves a reference exactly as `readAsset` does and answers `{ mimeType, size }`, or `undefined` when there is no such file:
|
|
238
|
+
|
|
239
|
+
```typescript
|
|
240
|
+
const video = await callbacks.describeAsset?.('asset:videos/intro.mp4');
|
|
241
|
+
|
|
242
|
+
if (video === undefined) {
|
|
243
|
+
// the scenario ships no intro video
|
|
244
|
+
} else if (video.size > 50_000_000) {
|
|
245
|
+
// too large to play in the room
|
|
246
|
+
}
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
**Notes:**
|
|
250
|
+
|
|
251
|
+
- Like `readAsset`, it needs no `uses` entry: every engine, hook, tick controller, and endpoint has it
|
|
252
|
+
- It is optional in the type, so call it with `?.`: a runtime built before SDK 1.4 does not provide it, and a test that builds its callbacks by hand need not either. Pass your own `describeAsset` in such a test to exercise the code that uses it
|
|
253
|
+
- `mimeType` is what `readAsset` would report: the type a blob was stored with, or the type of a bundled file judged from its extension
|
|
254
|
+
- A reference with none of the three prefixes still throws: that is a mistake rather than a missing file
|
|
255
|
+
- A validator's `Scenario` gate can have it too, with `readAsset`, to check the files a scenario names. There `readAsset` reads no file over 10 MB, so use `describeAsset` to check a large file. See [Checking the files a scenario names](./validators.md#checking-the-files-a-scenario-names)
|
|
256
|
+
|
|
196
257
|
## Extracting text from a document
|
|
197
258
|
|
|
198
259
|
Use the `extractText` callback to convert a document into plain text suitable for passing to an LLM. Available in the engine, hooks, tick controllers, and endpoints that declare `"extractText"` in `uses`. UIs reach it through an endpoint. Currently supports **PDF** files.
|
|
@@ -294,7 +355,7 @@ The field accepts two kinds of string, so the same endpoint serves every caller:
|
|
|
294
355
|
- **A `blob:` reference** to a file already stored. A UI passes the reference `uploadBlob` returned, as in the example above; a script or an agent uploads first (locally, `POST /api/blobs` or `pnpm run sdk blob upload`)
|
|
295
356
|
- **A `data:` URI** carrying the file inline, for a caller with no upload of its own: `data:application/pdf;name=brief.pdf;base64,...`. Up to 5 MB
|
|
296
357
|
|
|
297
|
-
Either way the handler receives a `blob:` reference, typed `` `blob:${string}` ``, that names a file of an accepted type, judged by its bytes, within the size. A URL, a wrong type or an oversized file is refused before the handler runs. Without `blob`, a field is a plain string the handler must check itself.
|
|
358
|
+
A file field may also be the entries of a map, with `blob` on its `additionalProperties` or a `patternProperties` schema, and each entry is checked as a field of its own. Either way the handler receives a `blob:` reference, typed `` `blob:${string}` ``, that names a file of an accepted type, judged by its bytes, within the size. A URL, a wrong type or an oversized file is refused before the handler runs. Without `blob`, a field is a plain string the handler must check itself.
|
|
298
359
|
|
|
299
360
|
See [Take a file in an endpoint](../recipes/take-a-file-in-an-endpoint.md).
|
|
300
361
|
|
|
@@ -358,26 +419,57 @@ pnpm run sdk patch \
|
|
|
358
419
|
"[{\"op\":\"replace\",\"path\":\"/upload/DocumentRef\",\"value\":\"$REFERENCE\"}]"
|
|
359
420
|
```
|
|
360
421
|
|
|
361
|
-
##
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
| Extension
|
|
366
|
-
|
|
|
367
|
-
| `.
|
|
368
|
-
| `.
|
|
369
|
-
| `.
|
|
370
|
-
| `.
|
|
371
|
-
| `.
|
|
372
|
-
| `.
|
|
373
|
-
| `.
|
|
374
|
-
| `.
|
|
375
|
-
| `.
|
|
376
|
-
| `.
|
|
377
|
-
| `.
|
|
378
|
-
| `.
|
|
379
|
-
| `.
|
|
380
|
-
|
|
|
422
|
+
## Media types
|
|
423
|
+
|
|
424
|
+
A package file's media type comes from its extension, compared without regard to case, by the table below. The build checks a file setting's `accept` against it, the dev server serves scenario and shared files under it, `readAsset` reports it, and so does every runtime, so a file the build accepted arrives as the type it was accepted as. An extension the table does not list is `application/octet-stream` everywhere: rename a file to a listed extension if a game or an `accept` depends on its type. A blob keeps the type it was uploaded with, whatever its name, and `sdk blob upload` takes it from the same table.
|
|
425
|
+
|
|
426
|
+
| Extension | Media type |
|
|
427
|
+
| ------------------ | --------------------------------------------------------------------------- |
|
|
428
|
+
| `.aac` | `audio/aac` |
|
|
429
|
+
| `.avif` | `image/avif` |
|
|
430
|
+
| `.bmp` | `image/bmp` |
|
|
431
|
+
| `.css` | `text/css` |
|
|
432
|
+
| `.csv` | `text/csv` |
|
|
433
|
+
| `.doc` | `application/msword` |
|
|
434
|
+
| `.docx` | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
|
|
435
|
+
| `.flac` | `audio/flac` |
|
|
436
|
+
| `.gif` | `image/gif` |
|
|
437
|
+
| `.htm`, `.html` | `text/html` |
|
|
438
|
+
| `.ico` | `image/x-icon` |
|
|
439
|
+
| `.jpeg`, `.jpg` | `image/jpeg` |
|
|
440
|
+
| `.js`, `.mjs` | `text/javascript` |
|
|
441
|
+
| `.json` | `application/json` |
|
|
442
|
+
| `.m4a` | `audio/mp4` |
|
|
443
|
+
| `.m4v`, `.mp4` | `video/mp4` |
|
|
444
|
+
| `.md` | `text/markdown` |
|
|
445
|
+
| `.mov` | `video/quicktime` |
|
|
446
|
+
| `.mp3` | `audio/mpeg` |
|
|
447
|
+
| `.odp` | `application/vnd.oasis.opendocument.presentation` |
|
|
448
|
+
| `.ods` | `application/vnd.oasis.opendocument.spreadsheet` |
|
|
449
|
+
| `.odt` | `application/vnd.oasis.opendocument.text` |
|
|
450
|
+
| `.ogg`, `.opus` | `audio/ogg` |
|
|
451
|
+
| `.otf` | `font/otf` |
|
|
452
|
+
| `.pdf` | `application/pdf` |
|
|
453
|
+
| `.png` | `image/png` |
|
|
454
|
+
| `.ppt` | `application/vnd.ms-powerpoint` |
|
|
455
|
+
| `.pptx` | `application/vnd.openxmlformats-officedocument.presentationml.presentation` |
|
|
456
|
+
| `.rtf` | `application/rtf` |
|
|
457
|
+
| `.svg` | `image/svg+xml` |
|
|
458
|
+
| `.tif`, `.tiff` | `image/tiff` |
|
|
459
|
+
| `.ttf` | `font/ttf` |
|
|
460
|
+
| `.txt` | `text/plain` |
|
|
461
|
+
| `.vtt` | `text/vtt` |
|
|
462
|
+
| `.wav` | `audio/wav` |
|
|
463
|
+
| `.webm` | `video/webm` |
|
|
464
|
+
| `.webp` | `image/webp` |
|
|
465
|
+
| `.woff` | `font/woff` |
|
|
466
|
+
| `.woff2` | `font/woff2` |
|
|
467
|
+
| `.xls` | `application/vnd.ms-excel` |
|
|
468
|
+
| `.xlsx` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` |
|
|
469
|
+
| `.xml` | `application/xml` |
|
|
470
|
+
| `.yaml`, `.yml` | `application/yaml` |
|
|
471
|
+
| `.zip` | `application/zip` |
|
|
472
|
+
| Any other, or none | `application/octet-stream` |
|
|
381
473
|
|
|
382
474
|
## Capability design
|
|
383
475
|
|
|
@@ -438,7 +438,7 @@ The mental model is a phone app's permissions: a static declaration, enforced at
|
|
|
438
438
|
| `generateSpeech` | Text-to-speech, returning an audio blob; see [Speech generation](./speech-generation.md) |
|
|
439
439
|
| `writeBlob` | Writes raw bytes to the blob store and returns a `blob:<id>` reference; most useful in an endpoint that returns a file |
|
|
440
440
|
|
|
441
|
-
The list is closed and fixed by the SDK (see [`ApiUse`](../api/sdk.md#apiuse)). Every other callback is runtime plumbing and is never gated: logic always has `readAsset` and `getPastState`, and a UI's `getAssetUrl`, `uploadBlob`, `requestTick` and the rest are always there when the surface exposes them.
|
|
441
|
+
The list is closed and fixed by the SDK (see [`ApiUse`](../api/sdk.md#apiuse)). Every other callback is runtime plumbing and is never gated: logic always has `readAsset`, `describeAsset` and `getPastState`, and a UI's `getAssetUrl`, `uploadBlob`, `requestTick` and the rest are always there when the surface exposes them.
|
|
442
442
|
|
|
443
443
|
### What happens when a resource calls one it did not declare
|
|
444
444
|
|
|
@@ -49,7 +49,7 @@ An agent writing a scenario changes settings and nothing else, so anything you w
|
|
|
49
49
|
}
|
|
50
50
|
```
|
|
51
51
|
|
|
52
|
-
Once facilitators have saved scenarios, a release can leave them behind. When you remove, rename, or reshape a setting, change what a value means,
|
|
52
|
+
Once facilitators have saved scenarios, a release can leave them behind. When you remove, rename, or reshape a setting, change what a value means, change how the game loads scenario assets, or move or remove a built-in scenario's files, bump `scenarioFormat` in `seriousgaming.sdk.json` (it starts at 1), and a runtime refuses the older scenarios rather than applying them wrongly. A new setting with a default needs no bump. See [Scenario format: when to bump it](./scenarios.md#scenario-format-when-to-bump-it).
|
|
53
53
|
|
|
54
54
|
Build an editor when a form is not enough: values that only make sense together, uploaded assets, a preview of what participants will see, or guidance a facilitator needs while choosing.
|
|
55
55
|
|
|
@@ -123,11 +123,12 @@ The flag says the scenario is for a particular audience. It never says who they
|
|
|
123
123
|
|
|
124
124
|
What a production runtime does with the flag is its own business, but it must not offer a restricted scenario for selection, list it, resolve it by identifier, or serve its assets to a caller it has not granted it to.
|
|
125
125
|
|
|
126
|
-
|
|
126
|
+
Four things are worth knowing before you rely on it:
|
|
127
127
|
|
|
128
128
|
- **The dev server ignores it.** There are no organisations locally and the package is yours, so restricted scenarios are offered exactly like any other. You cannot test the restriction from here
|
|
129
129
|
- **A restricted scenario cannot also be the default.** A default is what a caller gets when it picks nothing, so it has to be one every caller can be offered. The build refuses a scenario that sets both
|
|
130
130
|
- **It does not cover `shared:` assets.** Files under the package-level `shared-assets/` directory resolve whatever scenario is active, so anything belonging to one client goes under that scenario's own `assets/`, not in `shared-assets/`
|
|
131
|
+
- **Copies of it are restricted too.** A custom scenario copied from a restricted one reads its files, so a runtime offers the copy only to callers it has granted the original to. A client that loses the grant loses the copies built on it
|
|
131
132
|
|
|
132
133
|
The flag protects the scenario only on a runtime that implements grants: one that does not recognise the field offers the scenario normally. What it always does is record the intent in the package, reviewed alongside the content it describes, rather than leaving it to a setting somebody remembers to tick after the upload.
|
|
133
134
|
|
|
@@ -454,6 +455,12 @@ The editor is optional. `customScenarios.supported` is what switches custom scen
|
|
|
454
455
|
|
|
455
456
|
A saved scenario keeps every file it references for as long as it exists, whichever route uploaded it.
|
|
456
457
|
|
|
458
|
+
### Files a custom scenario reads
|
|
459
|
+
|
|
460
|
+
A custom scenario has no `assets/` directory of its own. Copying a scenario converts the `asset:` references in its settings, but not the ones your code builds, such as `` `asset:documents/${locale}/${id}.json` ``. Those resolve against the **built-in scenario the custom one descends from**: the scenario under `scenarios/` it was copied from, followed back through any copies of copies, as the package version the session runs ships it. A scenario draft does the same, so an editor or an agent working on a copy of `northwind` reads `northwind`'s files. A custom scenario begun from the defaults, with no built-in scenario behind it, resolves no `asset:` reference at all.
|
|
461
|
+
|
|
462
|
+
A runtime remembers which built-in scenario each custom scenario descends from, and refuses to apply one whose ancestor your current release no longer ships, naming it. So removing or renaming a built-in scenario retires every custom scenario copied from it, and moving its files breaks those your code reads: bump `scenarioFormat` when you do either (see below).
|
|
463
|
+
|
|
457
464
|
### Writing scenarios with an agent
|
|
458
465
|
|
|
459
466
|
A platform that lets an agent write scenarios gives it four things, and your game decides what each holds:
|
|
@@ -486,6 +493,7 @@ Bump it when a scenario saved against the previous release may no longer be corr
|
|
|
486
493
|
- A setting removed, renamed, or reshaped (an object split in two, a number that becomes an enum)
|
|
487
494
|
- A change in what a value means (a percentage that becomes a fraction, a per-round amount that becomes a total)
|
|
488
495
|
- A change in how the game loads scenario assets (a reference resolved from a different path)
|
|
496
|
+
- A built-in scenario's files moved or removed, or the scenario itself removed or renamed. A custom scenario reads the files your code names from the built-in scenario it was copied from (see [Files a custom scenario reads](#files-a-custom-scenario-reads))
|
|
489
497
|
- A lock or a narrower range on a setting a saved scenario may already set: a new `readOnly` in a settings schema, or a new or tighter entry in `gameSettingsConstraints` (see [Lock a setting](./settings.md#lock-a-setting)). A lock is enforced when a value is written, so the format is what stops an older scenario that carries the value from applying
|
|
490
498
|
- A new or stricter `Scenario` gate on a validator (see [Gating scenarios](./validators.md#gating-scenarios)). The gate runs when a scenario is saved, so the format is what stops one saved before the rule from applying
|
|
491
499
|
|