@seriousgaming/sdk-tools 1.0.0 → 1.2.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/README.md +4 -4
- package/dist/brands/awkward/brand.json +16 -0
- package/dist/brands/awkward/logo-on-light.svg +4 -0
- package/dist/brands/serious-gaming/brand.json +42 -0
- package/dist/brands/serious-gaming/fonts/OFL-sora.txt +93 -0
- package/dist/brands/serious-gaming/fonts/OFL-work-sans.txt +93 -0
- package/dist/brands/serious-gaming/fonts/sora-latin-400-normal.woff2 +0 -0
- package/dist/brands/serious-gaming/fonts/sora-latin-600-normal.woff2 +0 -0
- package/dist/brands/serious-gaming/fonts/sora-latin-700-normal.woff2 +0 -0
- package/dist/brands/serious-gaming/fonts/work-sans-latin-wght-normal.woff2 +0 -0
- package/dist/brands/serious-gaming/icon.svg +24 -0
- package/dist/brands/serious-gaming/loader-on-dark.svg +25 -0
- package/dist/brands/serious-gaming/loader-on-light.svg +25 -0
- package/dist/brands/serious-gaming/logo-on-dark.svg +38 -0
- package/dist/brands/serious-gaming/logo-on-light.svg +42 -0
- package/dist/cli.js +20161 -5495
- package/dist/client.js +15737 -1151
- package/dist/core/save-scenario.d.ts +25 -0
- package/dist/core/session-endpoints.d.ts +12 -13
- package/dist/core/session-host.d.ts +9 -1
- package/dist/core/session-writes.d.ts +2 -2
- package/dist/core/session.d.ts +9 -1
- package/dist/dev/brand-summary.d.ts +16 -0
- package/dist/dev/brands.d.ts +230 -0
- package/dist/dev/console/assets/icon-CRaj5uhr.svg +24 -0
- package/dist/dev/console/assets/index-BNLEVOQA.js +204 -0
- package/dist/dev/console/assets/index-q6-lvlN3.css +1 -0
- package/dist/dev/console/assets/sora-latin-400-normal-CRt88UEn.woff2 +0 -0
- package/dist/dev/console/assets/sora-latin-600-normal-Cdg4DaK0.woff2 +0 -0
- package/dist/dev/console/assets/sora-latin-700-normal-9waGdLWo.woff2 +0 -0
- package/dist/dev/console/assets/work-sans-latin-wght-normal-Bl-S9Xys.woff2 +0 -0
- package/dist/dev/console/index.html +3 -1
- package/dist/dev/routes.d.ts +9 -0
- package/dist/dev/shell.d.ts +14 -0
- package/dist/dev/view/batch.d.ts +0 -2
- package/dist/docs/ai-agents.md +75 -0
- package/dist/docs/api/deck.md +38 -0
- package/dist/docs/api/index.md +5 -5
- package/dist/docs/api/sdk-commands.md +1 -1
- package/dist/docs/api/sdk-e2e.md +1 -0
- package/dist/docs/api/sdk-projection.md +1 -0
- package/dist/docs/api/sdk-testing.md +52 -1
- package/dist/docs/api/sdk-tools-client.md +1 -0
- package/dist/docs/api/sdk-ui-testing.md +30 -4
- package/dist/docs/api/sdk-ui.md +185 -0
- package/dist/docs/api/sdk.md +70 -4
- package/dist/docs/changelog.md +85 -4
- package/dist/docs/cli-and-dev-server.md +2 -0
- package/dist/docs/cli-error-codes.md +65 -59
- package/dist/docs/cli-reference.md +84 -45
- package/dist/docs/concepts/index.md +74 -6
- package/dist/docs/concepts/terminology.md +17 -11
- package/dist/docs/getting-started.md +30 -11
- package/dist/docs/guides/ai-facilitation.md +5 -1
- package/dist/docs/guides/capabilities.md +3 -1
- package/dist/docs/guides/designing-a-game.md +85 -0
- package/dist/docs/guides/endpoints.md +57 -13
- package/dist/docs/guides/engine-testing.md +4 -13
- package/dist/docs/guides/engine.md +14 -2
- package/dist/docs/guides/file-handling.md +14 -10
- package/dist/docs/guides/games.md +2 -8
- package/dist/docs/guides/guide.md +98 -6
- package/dist/docs/guides/index.md +3 -4
- package/dist/docs/guides/internationalization.md +8 -14
- package/dist/docs/guides/llm-integration.md +19 -31
- package/dist/docs/guides/multi-team-games.md +9 -14
- package/dist/docs/guides/patterns.md +0 -6
- package/dist/docs/guides/presentation.md +6 -10
- package/dist/docs/guides/production-constraints.md +3 -10
- package/dist/docs/guides/scenario-editor.md +11 -11
- package/dist/docs/guides/scenarios.md +26 -14
- package/dist/docs/guides/session.md +32 -36
- package/dist/docs/guides/settings.md +28 -2
- package/dist/docs/guides/setup.md +2 -7
- package/dist/docs/guides/speech-generation.md +8 -17
- package/dist/docs/guides/starter-game.md +2 -1
- package/dist/docs/guides/testing.md +45 -43
- package/dist/docs/guides/theming-and-branding.md +208 -0
- package/dist/docs/guides/tick-controller.md +8 -4
- package/dist/docs/guides/type-safety.md +8 -6
- package/dist/docs/guides/ui.md +41 -62
- package/dist/docs/guides/upgrading.md +13 -3
- package/dist/docs/guides/validators.md +64 -3
- package/dist/docs/guides/waiting-room.md +3 -10
- package/dist/docs/index.md +40 -10
- package/dist/docs/recipes/adapt-ui-for-observers.md +1 -1
- package/dist/docs/recipes/call-endpoint-from-ui.md +2 -0
- package/dist/docs/recipes/create-capability.md +1 -1
- package/dist/docs/recipes/create-endpoint.md +7 -2
- package/dist/docs/recipes/create-engine.md +1 -1
- package/dist/docs/recipes/create-guide.md +4 -4
- package/dist/docs/recipes/create-hook.md +1 -1
- package/dist/docs/recipes/create-session-ui.md +1 -1
- package/dist/docs/recipes/create-settings.md +1 -1
- package/dist/docs/recipes/create-tick-controller.md +1 -1
- package/dist/docs/recipes/create-user-interface.md +1 -1
- package/dist/docs/recipes/create-validator.md +1 -1
- package/dist/docs/recipes/declare-api-uses.md +2 -2
- package/dist/docs/recipes/design-state-for-concurrent-writes.md +2 -2
- package/dist/docs/recipes/distribute-package.md +3 -3
- package/dist/docs/recipes/e2e-testing.md +11 -9
- package/dist/docs/recipes/index.md +6 -2
- package/dist/docs/recipes/make-a-guide-follow-the-scenario.md +89 -0
- package/dist/docs/recipes/make-an-endpoint-external.md +1 -1
- package/dist/docs/recipes/publish-a-package.md +1 -1
- package/dist/docs/recipes/remember-a-viewers-choice.md +1 -1
- package/dist/docs/recipes/review-a-past-day.md +4 -2
- package/dist/docs/recipes/share-assets-across-scenarios.md +3 -3
- package/dist/docs/recipes/share-logic-between-engine-and-ui.md +1 -1
- package/dist/docs/recipes/test-a-multi-role-game.md +1 -1
- package/dist/docs/recipes/test-user-interface.md +13 -2
- package/dist/docs/recipes/validate-scenarios.md +91 -0
- package/dist/docs/troubleshooting.md +44 -2
- package/dist/execution/blob-inputs.d.ts +7 -2
- package/dist/execution/config-resolver.d.ts +10 -0
- package/dist/execution/endpoint-runner.d.ts +8 -1
- package/dist/execution/executor-callbacks.d.ts +7 -0
- package/dist/execution/executor.d.ts +11 -0
- package/dist/execution/logic-calls.d.ts +8 -1
- package/dist/execution/scenario-gates.d.ts +34 -0
- package/dist/guide/effective-guide.d.ts +20 -0
- package/dist/guide/locale.d.ts +12 -0
- package/dist/guide/settings.d.ts +74 -0
- package/dist/guide/video-registry.d.ts +33 -1
- package/dist/host/host-channel.d.ts +11 -2
- package/dist/host/index.d.ts +9 -1
- package/dist/host/protocol.d.ts +49 -5
- package/dist/host/theme.d.ts +28 -2
- package/dist/host.js +11621 -15
- package/dist/runtime/index.d.ts +1 -1
- package/dist/runtime/manifest-version.d.ts +17 -0
- package/dist/runtime.js +12 -1
- package/dist/schema.json +32 -4
- package/dist/storage/blob-store.d.ts +3 -2
- package/dist/templates/endpoint/logic.test.ts.liquid +19 -1
- package/dist/templates/endpoint/logic.ts.liquid +18 -0
- package/dist/templates/hook/logic.test.ts.liquid +2 -2
- package/dist/templates/package/CLAUDE.md.template +5 -2
- package/dist/templates/package/README.md.liquid +2 -0
- package/dist/templates/package/claude/rules/workflow-create-endpoint.md +5 -4
- package/dist/templates/package/claude/rules/workflow-create-guide.md +9 -2
- package/dist/templates/presentation/src/App.tsx.liquid +5 -11
- package/dist/templates/session/src/App.test.tsx.liquid +2 -4
- package/dist/templates/session/src/theme.ts.liquid +26 -33
- package/dist/templates/settings-editor/src/theme.ts.liquid +13 -18
- package/dist/templates/starter-game/hooks/assignproducts/logic/logic.test.ts +2 -8
- package/dist/templates/starter-game/session/src/App.test.tsx +6 -10
- package/dist/templates/starter-game/session/src/theme.ts +26 -33
- package/dist/templates/starter-game/ui/src/App.tsx +2 -0
- package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +25 -0
- package/dist/templates/starter-game/ui/src/HostLogo.tsx +38 -0
- package/dist/templates/starter-game/ui/src/theme.ts +26 -33
- package/dist/templates/starter-game/validators/capacity/types.ts +2 -0
- package/dist/templates/starter-game/waiting_room/src/theme.ts +26 -33
- package/dist/templates/ui/src/App.test.tsx.liquid +7 -19
- package/dist/templates/ui/src/theme.ts.liquid +26 -33
- package/dist/templates/validator/logic.ts.liquid +4 -0
- package/dist/templates/waiting-room/src/App.test.tsx.liquid +17 -31
- package/dist/templates/waiting-room/src/theme.ts.liquid +26 -33
- package/dist/utils/error-codes.d.ts +15 -3
- package/dist/validation/ajv.d.ts +9 -5
- package/dist/validation/facilitator-guide-validator.d.ts +11 -1
- package/dist/validation/file-settings.d.ts +49 -0
- package/dist/validation/guide-settings-validator.d.ts +26 -0
- package/dist/validation/schema-validation.d.ts +12 -4
- package/package.json +6 -5
- package/dist/dev/console/assets/index-DgFglsnA.js +0 -204
|
@@ -1,22 +1,15 @@
|
|
|
1
1
|
# Building waiting room UIs
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The waiting room is the holding screen participants see while a session is parked, and you can replace the host's stock panel with your own.
|
|
4
4
|
|
|
5
5
|
**Keywords:** waiting room, holding screen, lobby, waiting to begin, session paused, park a session, break, waitingRoom, setWaitingRoom
|
|
6
6
|
|
|
7
|
-
## What you'll learn
|
|
8
|
-
|
|
9
|
-
- What the waiting room is and who controls it
|
|
10
|
-
- Why a waiting room UI is a game UI rather than a new kind of surface
|
|
11
|
-
- How to tell 'not started yet' from 'parked mid-play'
|
|
12
|
-
- How to start every session with the room already open
|
|
13
|
-
- How to stop the tick clock while participants wait
|
|
14
|
-
- How to let your own session UI open and close the room
|
|
15
|
-
|
|
16
7
|
## What is the waiting room?
|
|
17
8
|
|
|
18
9
|
The waiting room is a single per-session flag. While it is open, every participant in the session sees a holding screen instead of the game UIs; while it is closed, they see the game. The facilitator toggles it, and the change reaches every team at once.
|
|
19
10
|
|
|
11
|
+
Holding participants here gives a facilitator space for a discussion or a briefing, between rounds or before play starts.
|
|
12
|
+
|
|
20
13
|
```
|
|
21
14
|
Waiting room closed Waiting room open
|
|
22
15
|
+---------------------+ +---------------------+
|
package/dist/docs/index.md
CHANGED
|
@@ -1,19 +1,46 @@
|
|
|
1
1
|
# Serious Gaming SDK documentation
|
|
2
2
|
|
|
3
|
-
The Serious Gaming SDK is for building
|
|
3
|
+
The Serious Gaming SDK is for building serious games: facilitated learning experiences, such as business simulations and experiential learning, in which teams make decisions and see the consequences.
|
|
4
|
+
|
|
5
|
+
You write the rules and the screens in TypeScript and React, play the game on your own machine in the dev server, and publish it to the Serious Gaming platform, which runs it for real groups. Participants play on their own devices, in one room, remote, or hybrid, while a facilitator steers the session and leads the debrief.
|
|
6
|
+
|
|
7
|
+
## What the SDK does for you
|
|
8
|
+
|
|
9
|
+
A serious game is more than a web app with a score. Everything a live session needs beyond your game's own rules and screens is already built, in the dev server on your machine and on the platform in production:
|
|
10
|
+
|
|
11
|
+
- **Teams and joining**: participants join a session on their own devices, are placed in teams, and can rejoin after losing their connection
|
|
12
|
+
- **Live state**: every device on a team sees the same state, kept in step as teammates make decisions
|
|
13
|
+
- **Rounds**: your engine plays one round at a time, by hand or on a timer, with undo and a snapshot of every round to look back on
|
|
14
|
+
- **The facilitator's controls**: a session screen for the whole room, a waiting room to hold participants in, and a setup form for each session
|
|
15
|
+
- **Variants**: scenarios and settings, so one game serves different audiences without code changes
|
|
16
|
+
- **The debrief**: a slide deck built from the session's own results, and a facilitator guide in markdown
|
|
17
|
+
- **AI**: generated text and speech from your logic, and endpoints a facilitator's AI agent can call
|
|
18
|
+
- **Testing**: unit tests, whole games played in-process, and browser tests, with the starter game as a worked example
|
|
4
19
|
|
|
5
20
|
## How a session runs
|
|
6
21
|
|
|
7
|
-
1. A facilitator
|
|
8
|
-
2. Participants join on their own devices, in teams, and each sees your game
|
|
9
|
-
3.
|
|
10
|
-
4.
|
|
11
|
-
5. After the last
|
|
22
|
+
1. A facilitator creates a session of your game, choosing a scenario and filling in its setup form if it has one
|
|
23
|
+
2. Participants join on their own devices, in teams, and each sees your game's screen
|
|
24
|
+
3. In each round, teams make decisions, which your game can check and refuse
|
|
25
|
+
4. The facilitator, or a timer, ends the round: your engine works out what the decisions caused, and every screen shows the result
|
|
26
|
+
5. After the last round the game is complete, and the facilitator leads the debrief
|
|
27
|
+
|
|
28
|
+
[Core concepts](./concepts/index.md) tells the same story in terms of the code you write.
|
|
29
|
+
|
|
30
|
+
## What you need
|
|
31
|
+
|
|
32
|
+
To build and play a game locally, you need Node.js 24 or later and pnpm 12, and nothing else: the packages are on the public npm registry, and no account is needed.
|
|
33
|
+
|
|
34
|
+
To publish a game, you need an account on the Serious Gaming platform with publishing access, which Business Simulations grants: see [Publish a package](./recipes/publish-a-package.md). Generated text needs a platform API key, the same one publishing uses (see [LLM integration](./guides/llm-integration.md)), and generated speech in the dev server needs an ElevenLabs API key (see [Speech generation](./guides/speech-generation.md)).
|
|
35
|
+
|
|
36
|
+
The SDK and the deck library are Apache-2.0. The CLI and the dev server are under the Serious Gaming SDK Tools Licence, in their package's `LICENSE` file: you may use them to build games for the platform, you own the games you build, and what the tools generate or copy into your project is yours under Apache-2.0.
|
|
12
37
|
|
|
13
38
|
## Start here
|
|
14
39
|
|
|
15
|
-
- **[Getting started](./getting-started.md)**: scaffold the starter game, play it, and change it
|
|
40
|
+
- **[Getting started](./getting-started.md)**: scaffold the starter game, play it, and change it, in about 15 minutes
|
|
41
|
+
- **[Designing a serious game](./guides/designing-a-game.md)**: from a learning outcome to the decisions, rounds, feedback, and debrief that teach it
|
|
16
42
|
- **[A tour of the starter game](./guides/starter-game.md)**: every file in the game you are given, and what it does
|
|
43
|
+
- **[For AI agents](./ai-agents.md)**: the commands to scaffold, check, and play a game without a browser or a prompt
|
|
17
44
|
- **[Terminology](./concepts/terminology.md)**: the words these docs use, each with one meaning
|
|
18
45
|
|
|
19
46
|
## The documentation
|
|
@@ -31,11 +58,14 @@ The Serious Gaming SDK is for building business simulations: live, in-person lea
|
|
|
31
58
|
- **[CLI error codes](./cli-error-codes.md)**: every code a failed command reports, and its exit code
|
|
32
59
|
- **[Environment variables](./environment-variables.md)**: every variable the dev server and CLI read
|
|
33
60
|
|
|
34
|
-
## When something
|
|
61
|
+
## When something goes wrong
|
|
35
62
|
|
|
36
|
-
- **[
|
|
63
|
+
- **[Troubleshooting](./troubleshooting.md)**: symptoms, causes, and fixes
|
|
37
64
|
- **[Changelog](./changelog.md)**: what changed in each release from 1.0, and what to do about it
|
|
65
|
+
|
|
66
|
+
## Upgrading from an earlier release
|
|
67
|
+
|
|
68
|
+
- **[Upgrading](./guides/upgrading.md)**: the steps from 0.6 to 1.0
|
|
38
69
|
- **[Changelog for 0.x](./changelog-0.x.md)**: every release before 1.0
|
|
39
|
-
- **[Troubleshooting](./troubleshooting.md)**: symptoms, causes, and fixes
|
|
40
70
|
|
|
41
71
|
The docs at sdk.seriousgaming.com describe the newest release. The docs for the version you have installed ship inside it: `pnpm run sdk docs view` lists them and prints any page, and `pnpm run sdk docs export` copies them into your package for an editor or agent to search.
|
|
@@ -53,7 +53,7 @@ An observer is a facilitator watching one team's live game UI without joining as
|
|
|
53
53
|
}
|
|
54
54
|
```
|
|
55
55
|
|
|
56
|
-
5. Open the observer view at `/team/<n>/observe`. It renders the same game UI with no participant identity and no presence
|
|
56
|
+
5. Open the observer view at `/team/<n>/observe`. It renders the same game UI with no participant identity and no presence
|
|
57
57
|
|
|
58
58
|
## Verify
|
|
59
59
|
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
**Keywords:** call endpoint, invoke endpoint, callbacks.endpoints, UI endpoint, request response, EndpointError, endpoint failure
|
|
4
4
|
|
|
5
|
+
Call a server-side endpoint from any of your game's screens and handle its response or its failure.
|
|
6
|
+
|
|
5
7
|
## Prerequisites
|
|
6
8
|
|
|
7
9
|
- An [endpoint](create-endpoint.md) already scaffolded in the same package (or installed via another package)
|
|
@@ -31,7 +31,7 @@ Define a named slice of the game's state that the engine and screens read and wr
|
|
|
31
31
|
|
|
32
32
|
This writes `capabilities/pricing/capability.sdk.json`. For nested objects, arrays, and keyed collections, see [Variable types](../guides/capabilities.md#variable-types).
|
|
33
33
|
|
|
34
|
-
2. Optional: give it a `scope` other than the default `team`, by adding `"scope"` to the `definition` above: `shared` for one value across all teams, `team-readable` for a per-team value other teams may watch, or `private` for engine bookkeeping no screen receives. See [Scope](../guides/capabilities.md#scope)
|
|
34
|
+
2. Optional: give it a `scope` other than the default `team`, by adding `"scope"` to the `definition` above: `shared` for one value across all teams, `team-readable` for a per-team value other teams may watch, or `private` for engine bookkeeping no screen receives. See [Scope](../guides/capabilities.md#scope)
|
|
35
35
|
|
|
36
36
|
3. Declare it on each resource that uses it, in `reads` or `writes`. For the engine:
|
|
37
37
|
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
**Keywords:** create endpoint, new endpoint, server handler, callable handler, scaffold endpoint
|
|
4
4
|
|
|
5
|
+
Add a server-side handler your screens, or callers outside the game, can invoke by name with a validated request and response.
|
|
6
|
+
|
|
5
7
|
## Prerequisites
|
|
6
8
|
|
|
7
9
|
- A package with a valid `seriousgaming.sdk.json`
|
|
@@ -79,7 +81,9 @@
|
|
|
79
81
|
{ "scope": "session" }
|
|
80
82
|
```
|
|
81
83
|
|
|
82
|
-
`scope` defaults to `'team'`, which gives the handler that team's board and a `team` naming it: `team.teamId`, `team.index` and `team.name`. Use `team`, not `caller`, to find the team's own row in anything keyed by team: `caller` says who is calling, and a facilitator's agent or the CLI calls on a team's behalf without being on it, so its `caller.teamId` is absent. `caller.teamId` is set only for a participant or an observer, and names their own team. A session UI
|
|
84
|
+
`scope` defaults to `'team'`, which gives the handler that team's board and a `team` naming it: `team.teamId`, `team.index` and `team.name`. Use `team`, not `caller`, to find the team's own row in anything keyed by team: `caller` says who is calling, and a facilitator's agent or the CLI calls on a team's behalf without being on it, so its `caller.teamId` is absent. `caller.teamId` is set only for a participant or an observer, and names their own team. A session UI or a setup screen has no team of its own, so calling a team-scoped endpoint from one fails the build.
|
|
85
|
+
|
|
86
|
+
An endpoint for the scenario editor, or for an agent writing a scenario, is `{ "scope": "scenario" }`: it runs on a scenario draft, with the draft's settings and no game state (see [Scenario-scoped endpoints](../guides/endpoints.md#scenario-scoped-endpoints)).
|
|
83
87
|
|
|
84
88
|
4. Declare the endpoint on every UI that should be allowed to call it:
|
|
85
89
|
|
|
@@ -115,7 +119,8 @@
|
|
|
115
119
|
- _'Endpoint "X" rejected the request: \<path\> must have required property ...'_: the iframe sent a payload that does not match `requestSchema`. Check that the UI's call matches the declared request shape
|
|
116
120
|
- _'"ui" does not list endpoint "X" in its endpoints'_: add the endpoint identifier to the UI's `endpoints` array
|
|
117
121
|
- _'Resource "X" attempted to call callback "Y" but did not declare it in its bundle's "uses" array'_: add the `ApiUse` value to the endpoint bundle's `uses` array
|
|
118
|
-
- _'which is team-scoped, but this surface has no team of its own'_: a session UI
|
|
122
|
+
- _'which is team-scoped, but this surface has no team of its own'_: a session UI or setup screen is calling it; set `"scope": "session"` on the endpoint
|
|
123
|
+
- `EDITOR_ENDPOINT_NOT_SCENARIO`: the scenario editor lists it; an endpoint for the editor is `"scope": "scenario"` (see [Scenario-scoped endpoints](../guides/endpoints.md#scenario-scoped-endpoints))
|
|
119
124
|
- _'wrote X, which it does not declare in writes'_: the handler returned a capability outside its `writes`; add it, or stop returning it
|
|
120
125
|
- _'The game moved on while the endpoint was running'_: a tick committed mid-call, so the patch was computed against a board that no longer exists. Make the handler faster, or move the work into the engine
|
|
121
126
|
|
|
@@ -70,7 +70,7 @@ Write the engine that moves the game on each tick: here, one that reads a price
|
|
|
70
70
|
});
|
|
71
71
|
```
|
|
72
72
|
|
|
73
|
-
3. If you replaced the starter game's engine, replace or delete `engine/logic.test.ts` and the starter's other engine files, which test the old logic
|
|
73
|
+
3. If you replaced the starter game's engine, replace or delete `engine/logic.test.ts` and the starter's other engine files, which test the old logic
|
|
74
74
|
|
|
75
75
|
4. In a package made with `--empty`, set how long the game runs (the starter already sets `maxTicks`):
|
|
76
76
|
|
|
@@ -32,7 +32,7 @@ Bundle a facilitator guide with your game: markdown chapters shown on the facili
|
|
|
32
32
|
}'
|
|
33
33
|
```
|
|
34
34
|
|
|
35
|
-
2. Write the chapters as markdown files in `guide/content/<locale>/`, ordered by file name, with the same file names in every locale (`01-at-a-glance.md`, `02-preparation.md`, and so on)
|
|
35
|
+
2. Write the chapters as markdown files in `guide/content/<locale>/`, ordered by file name, with the same file names in every locale (`01-at-a-glance.md`, `02-preparation.md`, and so on)
|
|
36
36
|
|
|
37
37
|
3. Mark the live script with admonitions:
|
|
38
38
|
|
|
@@ -48,7 +48,7 @@ Bundle a facilitator guide with your game: markdown chapters shown on the facili
|
|
|
48
48
|
|
|
49
49
|
`timing`, `note`, `warning`, and `tip` work the same way. See [Content rules](../guides/guide.md#content-rules) for headings, images, and video blocks.
|
|
50
50
|
|
|
51
|
-
4. Put images in `guide/assets/` and reference them relatively from a chapter: `
|
|
51
|
+
4. Put images in `guide/assets/` and reference them relatively from a chapter: ``
|
|
52
52
|
|
|
53
53
|
## Verify
|
|
54
54
|
|
|
@@ -56,7 +56,7 @@ Bundle a facilitator guide with your game: markdown chapters shown on the facili
|
|
|
56
56
|
pnpm run sdk build --validate-only
|
|
57
57
|
```
|
|
58
58
|
|
|
59
|
-
Validation warns when a locale is missing a chapter the reference locale has, and fails on a malformed video block or an image that does not resolve. Then open `/guide` in the dev server: the page has its own locale picker and a print button.
|
|
59
|
+
Validation warns when a locale is missing a chapter the reference locale has, and fails on a malformed video block, or an image or video file that does not resolve. Then open `/guide` in the dev server: the page has its own locale picker and a print button.
|
|
60
60
|
|
|
61
61
|
## Troubleshooting
|
|
62
62
|
|
|
@@ -64,7 +64,7 @@ Validation warns when a locale is missing a chapter the reference locale has, an
|
|
|
64
64
|
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
|
|
65
65
|
| `new guide` fails with `RESOURCE_EXISTS` | The slot is filled: use `update guide` and edit the chapters, or `pnpm run sdk delete guide --yes` first |
|
|
66
66
|
| A chapter shows a 'not yet translated' note | That file is missing from the selected locale's directory; content falls back per file to the reference locale |
|
|
67
|
-
| A video renders an error block | The provider must be `youtube`
|
|
67
|
+
| A video renders an error block | The provider must be `youtube` with an 11-character YouTube id, or `file` with a `src` in `assets/` |
|
|
68
68
|
| An image does not display | The path must resolve inside `guide/`, for example `../../assets/diagram.png` from a chapter |
|
|
69
69
|
| Raw HTML appears as text | By design: the renderer escapes HTML. Use markdown, admonitions, and video blocks |
|
|
70
70
|
|
|
@@ -47,7 +47,7 @@ React to a lifecycle signal, such as a participant joining a team, outside the t
|
|
|
47
47
|
});
|
|
48
48
|
```
|
|
49
49
|
|
|
50
|
-
3. If several hooks subscribe to the same signal and order matters, number their directories: they run in directory-name order
|
|
50
|
+
3. If several hooks subscribe to the same signal and order matters, number their directories: they run in directory-name order
|
|
51
51
|
|
|
52
52
|
4. Build:
|
|
53
53
|
|
|
@@ -83,7 +83,7 @@ Build the facilitator's screen: every team's state side by side, with controls t
|
|
|
83
83
|
|
|
84
84
|
A `scope: 'shared'` capability arrives once, in `sessionData.shared.context`, and is written with the one-argument `setData(update)`. See [Writing shared capabilities](../guides/multi-team-games.md#facilitator-writable-shared-capabilities) and the [session UI hooks reference](../guides/session.md#hooks-reference) for roster control, timers, undo, and reset.
|
|
85
85
|
|
|
86
|
-
3. If you replaced the starter's session UI, delete its other components and tests under `session/src/`, which read capabilities this one no longer declares
|
|
86
|
+
3. If you replaced the starter's session UI, delete its other components and tests under `session/src/`, which read capabilities this one no longer declares
|
|
87
87
|
|
|
88
88
|
4. Build:
|
|
89
89
|
|
|
@@ -59,7 +59,7 @@ Give a game a read-only parameter, such as a price, a difficulty, or an answer k
|
|
|
59
59
|
return <p>Typical demand: {settings.demand.BaseDemand}</p>;
|
|
60
60
|
```
|
|
61
61
|
|
|
62
|
-
5. Optional: override it in a scenario, keyed by settings identifier (see [Create a scenario](create-scenario.md)). To change it for every session, edit its `default
|
|
62
|
+
5. Optional: override it in a scenario, keyed by settings identifier (see [Create a scenario](create-scenario.md)). To change it for every session, edit its `default`
|
|
63
63
|
|
|
64
64
|
## Verify
|
|
65
65
|
|
|
@@ -21,7 +21,7 @@ Make ticks fire automatically, on an interval or a schedule your game's logic de
|
|
|
21
21
|
}'
|
|
22
22
|
```
|
|
23
23
|
|
|
24
|
-
2. Write `GetTickController` in `tick_controller/logic.ts`. Return a cadence with `intervalTick`, which takes milliseconds and refuses anything outside 30 seconds to
|
|
24
|
+
2. Write `GetTickController` in `tick_controller/logic.ts`. Return a cadence with `intervalTick`, which takes milliseconds and refuses anything outside 30 seconds to seven days:
|
|
25
25
|
|
|
26
26
|
```typescript
|
|
27
27
|
import { GetTickControllerFunction, intervalTick } from '@seriousgaming/sdk';
|
|
@@ -62,7 +62,7 @@ Build the game UI: the screen each participant sees, showing the game's state an
|
|
|
62
62
|
|
|
63
63
|
Never spread `data` (or a whole capability) back into `setData`: a write naming a capability outside `writes` is refused, and re-sending untouched fields overwrites a team-mate's concurrent write. See [Writing to context](../guides/ui.md#writing-to-context).
|
|
64
64
|
|
|
65
|
-
3. If you replaced the starter game's UI, delete the starter's other components and their tests under `ui/src/`: they read capabilities this UI no longer declares, so they stop type-checking
|
|
65
|
+
3. If you replaced the starter game's UI, delete the starter's other components and their tests under `ui/src/`: they read capabilities this UI no longer declares, so they stop type-checking
|
|
66
66
|
|
|
67
67
|
4. Build:
|
|
68
68
|
|
|
@@ -39,7 +39,7 @@ Reject a participant's write that breaks the game's rules, before the runtime ap
|
|
|
39
39
|
|
|
40
40
|
A validator never changes state. To read who wrote it, narrow on `actor.role` (see [The actor](../guides/validators.md#the-actor)).
|
|
41
41
|
|
|
42
|
-
3. Optional: gate a participant's request for the next tick by exporting `RequestTick` as well (see [Gating tick requests](../guides/validators.md#gating-tick-requests))
|
|
42
|
+
3. Optional: gate a participant's request for the next tick by exporting `RequestTick` as well (see [Gating tick requests](../guides/validators.md#gating-tick-requests))
|
|
43
43
|
|
|
44
44
|
4. Build:
|
|
45
45
|
|
|
@@ -10,7 +10,7 @@ A logic-bearing resource (engine, hook, tick controller, endpoint) must declare
|
|
|
10
10
|
|
|
11
11
|
## Steps
|
|
12
12
|
|
|
13
|
-
1. Open the resource's bundle file (for example `engine/engine.sdk.json`)
|
|
13
|
+
1. Open the resource's bundle file (for example `engine/engine.sdk.json`)
|
|
14
14
|
2. Add a `uses` array to the `definition`, listing the callback names you intend to call. The values are `generateText`, `extractText`, `generateSpeech`, and `writeBlob`; see [The closed enum](../guides/llm-integration.md#the-apis-it-gates) for what each does:
|
|
15
15
|
|
|
16
16
|
```json
|
|
@@ -25,7 +25,7 @@ A logic-bearing resource (engine, hook, tick controller, endpoint) must declare
|
|
|
25
25
|
}
|
|
26
26
|
```
|
|
27
27
|
|
|
28
|
-
3. Run `pnpm run sdk generate` to regenerate `types.ts`. The `Callbacks` type alias is narrowed to the callbacks you declared, each one present rather than optional, so undeclared calls fail at type-check before they fail at runtime and declared ones need no `?.` check
|
|
28
|
+
3. Run `pnpm run sdk generate` to regenerate `types.ts`. The `Callbacks` type alias is narrowed to the callbacks you declared, each one present rather than optional, so undeclared calls fail at type-check before they fail at runtime and declared ones need no `?.` check
|
|
29
29
|
4. In your logic file, type the function signature with the `Callbacks` generic so calls are narrowed:
|
|
30
30
|
|
|
31
31
|
```typescript
|
|
@@ -60,9 +60,9 @@ Shape capabilities and `setData` calls so that several participants writing at o
|
|
|
60
60
|
if (participant) setData({ votes: { Votes: { [participant.id]: 'yes' } } });
|
|
61
61
|
```
|
|
62
62
|
|
|
63
|
-
5. Await the writes that matter through `useMutationReporter`, and show its `failure` (leaving out `validation-rejected`, which `useUserInterfaceValidationRejections` already explains) and its `late` notice. Never retry on your own: on a `conflict` the host has already retried, so offer `failure.retry` behind a 'Try again' button. See [Awaiting state changes](../guides/ui.md#awaiting-state-changes)
|
|
63
|
+
5. Await the writes that matter through `useMutationReporter`, and show its `failure` (leaving out `validation-rejected`, which `useUserInterfaceValidationRejections` already explains) and its `late` notice. Never retry on your own: on a `conflict` the host has already retried, so offer `failure.retry` behind a 'Try again' button. See [Awaiting state changes](../guides/ui.md#awaiting-state-changes)
|
|
64
64
|
|
|
65
|
-
6. Arbitrate a slot that is contested by design (two people claiming one role) with a [validator](create-validator.md) that compares `previous` with `next` and rejects the losing write. For a shared numeric pool, reconcile in the engine at tick time instead
|
|
65
|
+
6. Arbitrate a slot that is contested by design (two people claiming one role) with a [validator](create-validator.md) that compares `previous` with `next` and rejects the losing write. For a shared numeric pool, reconcile in the engine at tick time instead
|
|
66
66
|
|
|
67
67
|
7. In component tests, merge as the host does with `mergingSetData`, or a minimal write that is correct in production fails the test. It applies `deletes` after the merge too:
|
|
68
68
|
|
|
@@ -70,9 +70,9 @@ unzip -l dist/com.example.pkg-1.2.0.zip | head
|
|
|
70
70
|
|
|
71
71
|
## Troubleshooting
|
|
72
72
|
|
|
73
|
-
- **'Build directory not found'
|
|
74
|
-
- **'Manifest not found'
|
|
75
|
-
- **Wrong identifier or version in the filename
|
|
73
|
+
- **'Build directory not found'**: run `pnpm run sdk build` before `pnpm run sdk package bundle`. The bundle command does not build
|
|
74
|
+
- **'Manifest not found'**: the build directory exists but has no `seriousgaming.json`. Re-run the build; check that it completed without errors
|
|
75
|
+
- **Wrong identifier or version in the filename**: both are read from `dist/seriousgaming.json`, but they are authored in different places: the identifier in `seriousgaming.sdk.json`, the version in `package.json` (the manifest carries no version field). Fix whichever is wrong and rebuild
|
|
76
76
|
|
|
77
77
|
## Related
|
|
78
78
|
|
|
@@ -15,9 +15,11 @@ Test your game's screens in a real browser against an isolated dev server.
|
|
|
15
15
|
|
|
16
16
|
```bash
|
|
17
17
|
pnpm add -D @playwright/test
|
|
18
|
-
pnpm exec playwright install chromium
|
|
18
|
+
pnpm exec playwright install chromium --only-shell
|
|
19
19
|
```
|
|
20
20
|
|
|
21
|
+
`--only-shell` installs only the headless shell, which is all a headless run needs. `--headed`, `--debug` and `--ui` open a real browser window, so to use them run the command again without the flag to install full Chromium.
|
|
22
|
+
|
|
21
23
|
2. Create `testing/e2e/global-setup.ts`, which starts an isolated dev server in Playwright's own process and stops it when the run ends:
|
|
22
24
|
|
|
23
25
|
```typescript
|
|
@@ -89,7 +91,7 @@ Test your game's screens in a real browser against an isolated dev server.
|
|
|
89
91
|
|
|
90
92
|
The faults are `conflict`, `denied`, `llm-failure`, `hook-throw`, `endpoint-timeout`, and `tick-failure`.
|
|
91
93
|
|
|
92
|
-
7. Wait for what happens later with `waitForState`, never a sleep. For automatic ticks, pass `clock: new FakeClock()` to `startDevServer` and move time with `advanceClock(ms)
|
|
94
|
+
7. Wait for what happens later with `waitForState`, never a sleep. For automatic ticks, pass `clock: new FakeClock()` to `startDevServer` and move time with `advanceClock(ms)`
|
|
93
95
|
|
|
94
96
|
## Verify
|
|
95
97
|
|
|
@@ -101,13 +103,13 @@ Every spec passes. Add `--headed` to watch, or `--debug` to step through.
|
|
|
101
103
|
|
|
102
104
|
## Troubleshooting
|
|
103
105
|
|
|
104
|
-
| Problem | Solution
|
|
105
|
-
| ------------------------------------- |
|
|
106
|
-
| The run hangs after the last test | The server was started with `webServer`; start it with `startDevServer` in a global setup (step 2)
|
|
107
|
-
| Tests pass alone and fail in a suite | Call `reinitialiseSession()` in `beforeEach`; `resetSession()` keeps teams an earlier test added
|
|
108
|
-
| Iframe content is not there yet | Wait on a locator inside the frame (`await frame.locator('#x').waitFor()`)
|
|
109
|
-
| The `/e2e` import does not resolve | Set `moduleResolution` to `"bundler"` or `"nodenext"` in `tsconfig.json`
|
|
110
|
-
| Every spec fails on a missing browser | Run `pnpm exec playwright install chromium` after a Playwright upgrade
|
|
106
|
+
| Problem | Solution |
|
|
107
|
+
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
108
|
+
| The run hangs after the last test | The server was started with `webServer`; start it with `startDevServer` in a global setup (step 2) |
|
|
109
|
+
| Tests pass alone and fail in a suite | Call `reinitialiseSession()` in `beforeEach`; `resetSession()` keeps teams an earlier test added |
|
|
110
|
+
| Iframe content is not there yet | Wait on a locator inside the frame (`await frame.locator('#x').waitFor()`) |
|
|
111
|
+
| The `/e2e` import does not resolve | Set `moduleResolution` to `"bundler"` or `"nodenext"` in `tsconfig.json` |
|
|
112
|
+
| Every spec fails on a missing browser | Run `pnpm exec playwright install chromium --only-shell` after a Playwright upgrade (drop `--only-shell` to run headed) |
|
|
111
113
|
|
|
112
114
|
## Related
|
|
113
115
|
|
|
@@ -4,11 +4,13 @@ Each recipe is one task, start to finish: prerequisites, numbered steps, a way t
|
|
|
4
4
|
|
|
5
5
|
## Getting started
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
7
|
+
New to the SDK? Start with [Getting started](../getting-started.md), which plays and changes the starter game, then come back here for one task at a time.
|
|
8
|
+
|
|
9
9
|
- [Create a capability](create-capability.md): a new slice of the game's state
|
|
10
|
+
- [Create an engine](create-engine.md): an engine that reads one capability and writes another
|
|
10
11
|
- [Create settings](create-settings.md): a read-only parameter logic and screens read, which scenarios and facilitators can change before play
|
|
11
12
|
- [Shape your game](create-game.md): set ticks, teams, and locales
|
|
13
|
+
- [Start a game from an empty package](start-from-an-empty-package.md): build a game from nothing, with a capability, an engine, and a game UI, once you know what the starter game does
|
|
12
14
|
|
|
13
15
|
## Scenarios
|
|
14
16
|
|
|
@@ -18,6 +20,7 @@ Each recipe is one task, start to finish: prerequisites, numbered steps, a way t
|
|
|
18
20
|
## Facilitation
|
|
19
21
|
|
|
20
22
|
- [Create a facilitator guide](create-guide.md): markdown facilitation content shown on the facilitator's page
|
|
23
|
+
- [Make a guide follow the scenario](make-a-guide-follow-the-scenario.md): show settings values in the guide, and content only some scenarios need
|
|
21
24
|
- [Create a presentation](create-presentation.md): the facilitator's slide deck, live with the session's results and exportable to PDF and PowerPoint
|
|
22
25
|
|
|
23
26
|
## User interfaces
|
|
@@ -58,6 +61,7 @@ The full reference is the [Multi-team games](../guides/multi-team-games.md) guid
|
|
|
58
61
|
## Validation
|
|
59
62
|
|
|
60
63
|
- [Create a validator](create-validator.md): reject UI mutations that break the game's rules
|
|
64
|
+
- [Validate a game's scenarios](validate-scenarios.md): refuse a scenario whose settings break the game's rules, at build and on save
|
|
61
65
|
|
|
62
66
|
## Runtime callbacks
|
|
63
67
|
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# Make a guide follow the scenario
|
|
2
|
+
|
|
3
|
+
Show the session's settings in the facilitator guide, and show content only to the scenarios that need it.
|
|
4
|
+
|
|
5
|
+
**Keywords:** scenario-specific guide, conditional content, guide settings, show setting value, hide chapter, per-scenario facilitator notes, when directive
|
|
6
|
+
|
|
7
|
+
## Prerequisites
|
|
8
|
+
|
|
9
|
+
- A package with a facilitator guide (see [Create a facilitator guide](create-guide.md))
|
|
10
|
+
- The settings you want to show or test, in a settings resource (see [Create settings](create-settings.md))
|
|
11
|
+
|
|
12
|
+
## Steps
|
|
13
|
+
|
|
14
|
+
1. List the settings resources the guide reads:
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
pnpm run sdk update guide --patch '[
|
|
18
|
+
{ "op": "add", "path": "/definition/settings", "value": ["engine"] }
|
|
19
|
+
]'
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
2. Replace a vague sentence with the value, naming the settings resource and the property:
|
|
23
|
+
|
|
24
|
+
```markdown
|
|
25
|
+
The game runs for :setting[engine.totalWeeks] weeks.
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
3. Wrap text only some scenarios need in a `:::when`. A true-or-false setting needs no more:
|
|
29
|
+
|
|
30
|
+
```markdown
|
|
31
|
+
:::when{setting="engine.observers"}
|
|
32
|
+
Seat an observer in each team before the first round.
|
|
33
|
+
:::
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
For any other setting, compare it with `is`, and add `not` to turn the result round:
|
|
37
|
+
|
|
38
|
+
```markdown
|
|
39
|
+
:::when{setting="engine.mode" is="sandbox" not}
|
|
40
|
+
Tools unlock one round at a time.
|
|
41
|
+
:::
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
4. To show a whole chapter in one scenario only, add a setting that scenario sets, such as `Edition` in a settings resource only the guide reads, with a default for every other scenario:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
pnpm run sdk update scenario northwind --patch '[
|
|
48
|
+
{ "op": "add", "path": "/definition/settings/guide", "value": { "Edition": "northwind" } }
|
|
49
|
+
]'
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Then wrap the chapter, its title included, in one block. Give the block four colons when the chapter has admonitions inside it:
|
|
53
|
+
|
|
54
|
+
```markdown
|
|
55
|
+
::::when{setting="guide.Edition" is="northwind"}
|
|
56
|
+
|
|
57
|
+
# Northwind edition
|
|
58
|
+
|
|
59
|
+
:::say
|
|
60
|
+
Northwind runs its plants on tighter margins than the standard market.
|
|
61
|
+
:::
|
|
62
|
+
::::
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Verify
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
pnpm run sdk build --validate-only
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Then open `/guide` in the dev server and switch scenario: the values change and the conditioned content comes and goes.
|
|
72
|
+
|
|
73
|
+
## Troubleshooting
|
|
74
|
+
|
|
75
|
+
| Problem | Solution |
|
|
76
|
+
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
77
|
+
| 'reads settings "…", which the guide does not list' | Add the settings resource to the guide's `settings` |
|
|
78
|
+
| 'can show only a number or text' | `:setting` cannot show a true-or-false value or a list. Use a `:::when` for a true-or-false setting |
|
|
79
|
+
| 'needs is="…", since it is not true or false' | Compare the setting with `is="value"` |
|
|
80
|
+
| 'sits inside another :::when' | Conditions do not nest. Give the inner block its own condition |
|
|
81
|
+
| 'this ::: closes nothing' | The outer block closed early, at an admonition's `:::`, so the text after it shows in every scenario. Give the `:::when` more colons than the admonitions inside it (`::::when` … `::::`) |
|
|
82
|
+
| 'is empty under the defaults and every scenario' | No scenario turns the condition on. Check the `is` value, or the scenario's settings |
|
|
83
|
+
| A red error shows in the guide in place of a value | The setting could not be read for this session. Run the build validation, which names the cause |
|
|
84
|
+
|
|
85
|
+
## Related
|
|
86
|
+
|
|
87
|
+
- [Facilitator guides](../guides/guide.md#following-the-scenarios-settings): the full rules
|
|
88
|
+
- [Create a scenario](create-scenario.md)
|
|
89
|
+
- [Create settings](create-settings.md)
|
|
@@ -90,7 +90,7 @@ Publish one of your endpoints to callers outside the game, such as a facilitator
|
|
|
90
90
|
- _'is external, so its requestSchema must declare `"type": "object"`'_ (`EXTERNAL_REQUEST_NOT_OBJECT`): Wrap the request in an object with a named property for each value, such as `{ "price": 3.53 }` rather than `3.53`
|
|
91
91
|
- _'is internal, so a caller outside the game cannot call it'_: Set `"visibility": "external"` on the endpoint
|
|
92
92
|
- _'`agentCallable` has been replaced by `visibility`'_: Replace `"agentCallable": true` with `"visibility": "external"`
|
|
93
|
-
- _'which is team-scoped, but this surface has no team of its own'_: A session UI
|
|
93
|
+
- _'which is team-scoped, but this surface has no team of its own'_: A session UI or setup screen also lists this endpoint; give it `"scope": "session"` or stop listing it there
|
|
94
94
|
- _Two endpoints get confused for each other_: Run `endpoint list --external` and read the descriptions together. If they do not say when to pick one over the other, the agent has nothing to go on
|
|
95
95
|
- _No user interface requests it_: That warning is suppressed for external endpoints, whose caller no bundle names. If you see it, `visibility` is not `external`
|
|
96
96
|
|
|
@@ -126,7 +126,7 @@ pnpm run --silent sdk package publish --json | tee publish.json
|
|
|
126
126
|
- **'No API key configured'**: set `SERIOUSGAMING_API_KEY` in your environment or pass `--api-key`
|
|
127
127
|
- **'No publisher configured'**: set `SERIOUSGAMING_PUBLISHER`, pass `--publisher <slug>`, or run `pnpm run sdk config set platform.defaultPublisher <slug>`
|
|
128
128
|
- **'Invalid API key'** (401): the token is malformed or has been revoked. Issue a new one
|
|
129
|
-
- **'The account that created this API key does not have publishing access'** (403): the key is valid, but its account cannot publish. Ask
|
|
129
|
+
- **'The account that created this API key does not have publishing access'** (403): the key is valid, but its account cannot publish. Ask Serious Gaming support to grant publishing access to that account, or use a key from an account that has it
|
|
130
130
|
- **An identifier error mentioning a publisher** (400): the package is already bound to a different publisher. Upload later versions under the same publisher it was first published with
|
|
131
131
|
- **'Version X.Y.Z of <identifier> already exists'** (409): bump the version (`pnpm run sdk package version patch`) and retry. The CLI deliberately does not auto-bump, so an agent can decide whether to bump or abort
|
|
132
132
|
- **'Bundle not found at dist/...'**: run `pnpm run sdk build` first, or drop `--no-auto-bundle` and let the command bundle for you
|
|
@@ -26,7 +26,7 @@ A viewer's own choices, such as the tab they had open, a panel they collapsed, o
|
|
|
26
26
|
<Tabs value={tab} onChange={(_, value: number) => setTab(value)}>
|
|
27
27
|
```
|
|
28
28
|
|
|
29
|
-
3. Keep the key short and specific to the surface: it only has to be unique among the values one surface stores. The hook adds the session key, the surface and the viewer itself
|
|
29
|
+
3. Keep the key short and specific to the surface: it only has to be unique among the values one surface stores. The hook adds the session key, the surface and the viewer itself
|
|
30
30
|
|
|
31
31
|
## What it is keyed by
|
|
32
32
|
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
Let participants scrub back through their team's committed ticks, or chart a value across every tick, with `usePastState` and `getPastState`.
|
|
4
4
|
|
|
5
|
+
Revisiting a round supports reflection: a team can see what it decided and what followed before it decides again.
|
|
6
|
+
|
|
5
7
|
**Keywords:** getPastState, usePastState, PastStateQuery, PastStateEntry, tick snapshot, review past day, history, scrubber, timeline, replay, previous tick, completedTicks, cross-team history, TickSnapshotError, results table, history chart, round_history growing
|
|
6
8
|
|
|
7
9
|
## Prerequisites
|
|
@@ -44,9 +46,9 @@ Let participants scrub back through their team's committed ticks, or chart a val
|
|
|
44
46
|
|
|
45
47
|
This is what lets you drop a `round_history` capability that grows every tick.
|
|
46
48
|
|
|
47
|
-
4. In a shared-state game, review every team at that tick with `teams: 'all'`, typed by the generated `CrossTeamContext`. Other teams' rows arrive only for capabilities the surface lists in `crossTeamReads` (see [Observe other teams' state](observe-other-teams-state.md)). A session UI calls the same `getPastState` from `useSessionUserInterfaceCallbacks()`, and its default is the whole session
|
|
49
|
+
4. In a shared-state game, review every team at that tick with `teams: 'all'`, typed by the generated `CrossTeamContext`. Other teams' rows arrive only for capabilities the surface lists in `crossTeamReads` (see [Observe other teams' state](observe-other-teams-state.md)). A session UI calls the same `getPastState` from `useSessionUserInterfaceCallbacks()`, and its default is the whole session
|
|
48
50
|
|
|
49
|
-
5. Optional: for a slider dragged quickly, debounce the query, and cache entries by tick. Evict cached ticks at or above `completedTicks` when it drops, so an undo never shows a stale board
|
|
51
|
+
5. Optional: for a slider dragged quickly, debounce the query, and cache entries by tick. Evict cached ticks at or above `completedTicks` when it drops, so an undo never shows a stale board
|
|
50
52
|
|
|
51
53
|
## Verify
|
|
52
54
|
|
|
@@ -108,9 +108,9 @@ Start the dev server and confirm the file is served at `/api/shared/assets/story
|
|
|
108
108
|
|
|
109
109
|
## Troubleshooting
|
|
110
110
|
|
|
111
|
-
- **404 from the shared asset URL
|
|
112
|
-
- **The wrong file resolves
|
|
113
|
-
- **`getAssetUrl` or `useAssetUrl` throws
|
|
111
|
+
- **404 from the shared asset URL**: the path inside `shared:<path>` is relative to `shared-assets/`, not to a scenario's `assets/`. Check the file exists under `shared-assets/<path>` and that you ran `build` so it was copied into `dist/`
|
|
112
|
+
- **The wrong file resolves**: `shared:` and `asset:` never shadow each other. If you meant the scenario's own copy, use `asset:<path>`; if you meant the shared copy, use `shared:<path>`
|
|
113
|
+
- **`getAssetUrl` or `useAssetUrl` throws**: the reference must start with `asset:`, `shared:`, or `blob:`. A bare path is not a valid reference
|
|
114
114
|
|
|
115
115
|
## Related
|
|
116
116
|
|
|
@@ -58,7 +58,7 @@ Writing the formula twice works right up until someone changes one copy. Then th
|
|
|
58
58
|
}
|
|
59
59
|
```
|
|
60
60
|
|
|
61
|
-
3. Import it from your engine's logic. The engine stays the authority: it computes the value that is written to state
|
|
61
|
+
3. Import it from your engine's logic. The engine stays the authority: it computes the value that is written to state
|
|
62
62
|
|
|
63
63
|
```typescript
|
|
64
64
|
// engine/logic.ts
|
|
@@ -23,7 +23,7 @@ A fresh team starts with one participant, at `/team/<n>/player/1`. Participants
|
|
|
23
23
|
|
|
24
24
|
Use **Add participant** on the team's row in the dev drawer to create each role, or `pnpm run sdk participant add Buyer --team 1` from the CLI, which names it too. To rename one later, use `pnpm run sdk participant rename <participantId> <name>`; `pnpm run sdk view` lists the ids. Creating a participant fires the `participantJoin` hook, exactly as it would in production, so any join-driven setup runs.
|
|
25
25
|
|
|
26
|
-
If the game declares `teams.perTeam.minParticipants` / `maxParticipants`, the roster shows an advisory caption (for example '2
|
|
26
|
+
If the game declares `teams.perTeam.minParticipants` / `maxParticipants`, the roster shows an advisory caption (for example '2 to 5 recommended for this scenario'). It is guidance only and never blocks adding or removing.
|
|
27
27
|
|
|
28
28
|
### 3. Open each participant in its own tab
|
|
29
29
|
|