@seriousgaming/sdk-tools 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (165) hide show
  1. package/README.md +4 -4
  2. package/dist/brands/awkward/brand.json +16 -0
  3. package/dist/brands/awkward/logo-on-light.svg +4 -0
  4. package/dist/brands/serious-gaming/brand.json +42 -0
  5. package/dist/brands/serious-gaming/fonts/OFL-sora.txt +93 -0
  6. package/dist/brands/serious-gaming/fonts/OFL-work-sans.txt +93 -0
  7. package/dist/brands/serious-gaming/fonts/sora-latin-400-normal.woff2 +0 -0
  8. package/dist/brands/serious-gaming/fonts/sora-latin-600-normal.woff2 +0 -0
  9. package/dist/brands/serious-gaming/fonts/sora-latin-700-normal.woff2 +0 -0
  10. package/dist/brands/serious-gaming/fonts/work-sans-latin-wght-normal.woff2 +0 -0
  11. package/dist/brands/serious-gaming/icon.svg +24 -0
  12. package/dist/brands/serious-gaming/loader-on-dark.svg +25 -0
  13. package/dist/brands/serious-gaming/loader-on-light.svg +25 -0
  14. package/dist/brands/serious-gaming/logo-on-dark.svg +38 -0
  15. package/dist/brands/serious-gaming/logo-on-light.svg +42 -0
  16. package/dist/cli.js +20003 -5523
  17. package/dist/client.js +15534 -1134
  18. package/dist/core/save-scenario.d.ts +25 -0
  19. package/dist/core/session-endpoints.d.ts +12 -13
  20. package/dist/core/session-host.d.ts +9 -1
  21. package/dist/core/session-writes.d.ts +2 -2
  22. package/dist/core/session.d.ts +9 -1
  23. package/dist/dev/brand-summary.d.ts +16 -0
  24. package/dist/dev/brands.d.ts +213 -0
  25. package/dist/dev/console/assets/icon-CRaj5uhr.svg +24 -0
  26. package/dist/dev/console/assets/index-q6-lvlN3.css +1 -0
  27. package/dist/dev/console/assets/index-qxHcu9fJ.js +204 -0
  28. package/dist/dev/console/assets/sora-latin-400-normal-CRt88UEn.woff2 +0 -0
  29. package/dist/dev/console/assets/sora-latin-600-normal-Cdg4DaK0.woff2 +0 -0
  30. package/dist/dev/console/assets/sora-latin-700-normal-9waGdLWo.woff2 +0 -0
  31. package/dist/dev/console/assets/work-sans-latin-wght-normal-Bl-S9Xys.woff2 +0 -0
  32. package/dist/dev/console/index.html +3 -1
  33. package/dist/dev/routes.d.ts +9 -0
  34. package/dist/dev/shell.d.ts +14 -0
  35. package/dist/dev/view/batch.d.ts +0 -2
  36. package/dist/docs/ai-agents.md +75 -0
  37. package/dist/docs/api/deck.md +38 -0
  38. package/dist/docs/api/index.md +5 -5
  39. package/dist/docs/api/sdk-commands.md +1 -1
  40. package/dist/docs/api/sdk-e2e.md +1 -0
  41. package/dist/docs/api/sdk-projection.md +1 -0
  42. package/dist/docs/api/sdk-testing.md +52 -1
  43. package/dist/docs/api/sdk-tools-client.md +1 -0
  44. package/dist/docs/api/sdk-ui-testing.md +30 -4
  45. package/dist/docs/api/sdk-ui.md +166 -0
  46. package/dist/docs/api/sdk.md +70 -4
  47. package/dist/docs/changelog.md +60 -4
  48. package/dist/docs/cli-and-dev-server.md +2 -0
  49. package/dist/docs/cli-error-codes.md +65 -59
  50. package/dist/docs/cli-reference.md +84 -45
  51. package/dist/docs/concepts/index.md +74 -6
  52. package/dist/docs/concepts/terminology.md +17 -11
  53. package/dist/docs/getting-started.md +30 -11
  54. package/dist/docs/guides/ai-facilitation.md +5 -1
  55. package/dist/docs/guides/capabilities.md +3 -1
  56. package/dist/docs/guides/designing-a-game.md +85 -0
  57. package/dist/docs/guides/endpoints.md +57 -13
  58. package/dist/docs/guides/engine-testing.md +4 -13
  59. package/dist/docs/guides/engine.md +14 -2
  60. package/dist/docs/guides/file-handling.md +14 -10
  61. package/dist/docs/guides/games.md +2 -8
  62. package/dist/docs/guides/guide.md +64 -3
  63. package/dist/docs/guides/index.md +3 -4
  64. package/dist/docs/guides/internationalization.md +8 -14
  65. package/dist/docs/guides/llm-integration.md +19 -31
  66. package/dist/docs/guides/multi-team-games.md +9 -14
  67. package/dist/docs/guides/patterns.md +0 -6
  68. package/dist/docs/guides/presentation.md +6 -10
  69. package/dist/docs/guides/production-constraints.md +2 -9
  70. package/dist/docs/guides/scenario-editor.md +11 -11
  71. package/dist/docs/guides/scenarios.md +26 -14
  72. package/dist/docs/guides/session.md +29 -35
  73. package/dist/docs/guides/settings.md +28 -2
  74. package/dist/docs/guides/setup.md +2 -7
  75. package/dist/docs/guides/speech-generation.md +8 -17
  76. package/dist/docs/guides/starter-game.md +2 -1
  77. package/dist/docs/guides/testing.md +45 -43
  78. package/dist/docs/guides/theming-and-branding.md +194 -0
  79. package/dist/docs/guides/tick-controller.md +8 -4
  80. package/dist/docs/guides/type-safety.md +8 -6
  81. package/dist/docs/guides/ui.md +41 -62
  82. package/dist/docs/guides/upgrading.md +5 -3
  83. package/dist/docs/guides/validators.md +64 -3
  84. package/dist/docs/guides/waiting-room.md +3 -10
  85. package/dist/docs/index.md +40 -10
  86. package/dist/docs/recipes/adapt-ui-for-observers.md +1 -1
  87. package/dist/docs/recipes/call-endpoint-from-ui.md +2 -0
  88. package/dist/docs/recipes/create-capability.md +1 -1
  89. package/dist/docs/recipes/create-endpoint.md +7 -2
  90. package/dist/docs/recipes/create-engine.md +1 -1
  91. package/dist/docs/recipes/create-guide.md +2 -2
  92. package/dist/docs/recipes/create-hook.md +1 -1
  93. package/dist/docs/recipes/create-session-ui.md +1 -1
  94. package/dist/docs/recipes/create-settings.md +1 -1
  95. package/dist/docs/recipes/create-tick-controller.md +1 -1
  96. package/dist/docs/recipes/create-user-interface.md +1 -1
  97. package/dist/docs/recipes/create-validator.md +1 -1
  98. package/dist/docs/recipes/declare-api-uses.md +2 -2
  99. package/dist/docs/recipes/design-state-for-concurrent-writes.md +2 -2
  100. package/dist/docs/recipes/distribute-package.md +3 -3
  101. package/dist/docs/recipes/e2e-testing.md +11 -9
  102. package/dist/docs/recipes/index.md +6 -2
  103. package/dist/docs/recipes/make-a-guide-follow-the-scenario.md +89 -0
  104. package/dist/docs/recipes/make-an-endpoint-external.md +1 -1
  105. package/dist/docs/recipes/publish-a-package.md +1 -1
  106. package/dist/docs/recipes/remember-a-viewers-choice.md +1 -1
  107. package/dist/docs/recipes/review-a-past-day.md +4 -2
  108. package/dist/docs/recipes/share-assets-across-scenarios.md +3 -3
  109. package/dist/docs/recipes/share-logic-between-engine-and-ui.md +1 -1
  110. package/dist/docs/recipes/test-a-multi-role-game.md +1 -1
  111. package/dist/docs/recipes/test-user-interface.md +13 -2
  112. package/dist/docs/recipes/validate-scenarios.md +91 -0
  113. package/dist/docs/troubleshooting.md +44 -2
  114. package/dist/execution/blob-inputs.d.ts +7 -2
  115. package/dist/execution/config-resolver.d.ts +10 -0
  116. package/dist/execution/endpoint-runner.d.ts +8 -1
  117. package/dist/execution/executor-callbacks.d.ts +7 -0
  118. package/dist/execution/executor.d.ts +11 -0
  119. package/dist/execution/logic-calls.d.ts +8 -1
  120. package/dist/execution/scenario-gates.d.ts +34 -0
  121. package/dist/guide/effective-guide.d.ts +20 -0
  122. package/dist/guide/locale.d.ts +12 -0
  123. package/dist/guide/settings.d.ts +67 -0
  124. package/dist/host/host-channel.d.ts +11 -2
  125. package/dist/host/index.d.ts +7 -1
  126. package/dist/host/protocol.d.ts +49 -5
  127. package/dist/host/theme.d.ts +28 -2
  128. package/dist/host.js +11490 -15
  129. package/dist/runtime/index.d.ts +1 -1
  130. package/dist/runtime/manifest-version.d.ts +17 -0
  131. package/dist/runtime.js +12 -1
  132. package/dist/schema.json +32 -4
  133. package/dist/storage/blob-store.d.ts +3 -2
  134. package/dist/templates/endpoint/logic.test.ts.liquid +19 -1
  135. package/dist/templates/endpoint/logic.ts.liquid +18 -0
  136. package/dist/templates/hook/logic.test.ts.liquid +2 -2
  137. package/dist/templates/package/CLAUDE.md.template +5 -2
  138. package/dist/templates/package/README.md.liquid +2 -0
  139. package/dist/templates/package/claude/rules/workflow-create-endpoint.md +5 -4
  140. package/dist/templates/package/claude/rules/workflow-create-guide.md +1 -0
  141. package/dist/templates/presentation/src/App.tsx.liquid +5 -11
  142. package/dist/templates/session/src/App.test.tsx.liquid +2 -4
  143. package/dist/templates/session/src/theme.ts.liquid +26 -33
  144. package/dist/templates/settings-editor/src/theme.ts.liquid +13 -18
  145. package/dist/templates/starter-game/hooks/assignproducts/logic/logic.test.ts +2 -8
  146. package/dist/templates/starter-game/session/src/App.test.tsx +6 -10
  147. package/dist/templates/starter-game/session/src/theme.ts +26 -33
  148. package/dist/templates/starter-game/ui/src/App.tsx +2 -0
  149. package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +25 -0
  150. package/dist/templates/starter-game/ui/src/HostLogo.tsx +38 -0
  151. package/dist/templates/starter-game/ui/src/theme.ts +26 -33
  152. package/dist/templates/starter-game/validators/capacity/types.ts +2 -0
  153. package/dist/templates/starter-game/waiting_room/src/theme.ts +26 -33
  154. package/dist/templates/ui/src/App.test.tsx.liquid +7 -19
  155. package/dist/templates/ui/src/theme.ts.liquid +26 -33
  156. package/dist/templates/validator/logic.ts.liquid +4 -0
  157. package/dist/templates/waiting-room/src/App.test.tsx.liquid +17 -31
  158. package/dist/templates/waiting-room/src/theme.ts.liquid +26 -33
  159. package/dist/utils/error-codes.d.ts +15 -3
  160. package/dist/validation/ajv.d.ts +9 -5
  161. package/dist/validation/facilitator-guide-validator.d.ts +6 -0
  162. package/dist/validation/file-settings.d.ts +49 -0
  163. package/dist/validation/guide-settings-validator.d.ts +26 -0
  164. package/package.json +6 -5
  165. package/dist/dev/console/assets/index-DgFglsnA.js +0 -204
@@ -12,7 +12,7 @@ The codes are the contract: branch on the code, never on the message. A code is
12
12
  | --------- | ------------- | ------------------- | ----- |
13
13
  | 1 | `internal` | Internal error | 1 |
14
14
  | 2 | `usage` | Usage error | 15 |
15
- | 3 | `package` | Invalid package | 29 |
15
+ | 3 | `package` | Invalid package | 32 |
16
16
  | 4 | `refused` | Refused by the game | 11 |
17
17
  | 5 | `environment` | Environment | 18 |
18
18
 
@@ -48,37 +48,40 @@ A code marked as a diagnostic also appears in a failure's `diagnostics`, one fin
48
48
 
49
49
  ### Exit 3: invalid package
50
50
 
51
- | Code | When | Also a diagnostic |
52
- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
53
- | `PACKAGE_INVALID` | The package fails validation. The diagnostics say where. As a diagnostic code, a finding no finer code describes yet. | Yes |
54
- | `MANIFEST_NOT_FOUND` | There is no seriousgaming.sdk.json (or package.json) where the command looked. | |
55
- | `MANIFEST_INVALID` | seriousgaming.sdk.json or package.json cannot be read, or is not valid. | |
56
- | `BUNDLE_INVALID` | A resource's bundle file (such as engine.sdk.json) cannot be read, or is not valid. | |
57
- | `LOGIC_NODE_BUILTIN` | Game logic imports a Node built-in, which is absent in production: logic runs on the JavaScript language alone. | Yes |
58
- | `LOGIC_BUNDLE_FAILED` | A logic file does not bundle: a syntax error, or an import that does not resolve. | Yes |
59
- | `SCHEMA_INVALID` | A bundle or the manifest does not match the SDK's schema. The diagnostic's pointer names the value. | Yes |
60
- | `JSON_INVALID` | A bundle file is not valid JSON. | Yes |
61
- | `BUNDLE_MISSING` | A resource directory holds no bundle file. | Yes |
62
- | `REMOVED_FIELD` | A bundle or the manifest carries a field the SDK no longer reads. The hint says what replaced it. | Yes |
63
- | `LAYOUT_OUTDATED` | A directory or bundle file sits where an earlier version of the SDK kept it. The hint says where it goes now. | Yes |
64
- | `FEATURE_UNSUPPORTED` | The manifest's `requires` names an optional feature this version of the SDK does not support. | Yes |
65
- | `REFERENCE_UNKNOWN` | A `reads`, `writes`, `settings`, `configures` or `endpoints` entry names something the package does not declare. | Yes |
66
- | `SETTINGS_UNKNOWN` | A scenario overrides a settings resource the package does not declare. | Yes |
67
- | `SETTINGS_UNKNOWN_KEY` | A scenario overrides a key that its settings resource does not declare. | Yes |
68
- | `SETTINGS_INVALID` | A scenario's override does not match its settings resource's schema. | Yes |
69
- | `SETTINGS_RESERVED` | A settings resource is named `game`, which is reserved for the built-in game settings. | Yes |
70
- | `SETTINGS_LOCKED` | A scenario overrides a setting the game locks with `readOnly`, in its settings schema or its `gameSettingsConstraints`. | Yes |
71
- | `GAME_CONSTRAINT_INVALID` | A `gameSettingsConstraints` entry widens the SDK schema for the `game` settings rather than narrowing it. | Yes |
72
- | `GAME_CONSTRAINT_VIOLATED` | The game's own value for a `game` setting breaks its `gameSettingsConstraints`. | Yes |
73
- | `LOGIC_EXPORT_MISSING` | A logic file is missing, or does not export the functions its resource needs. | Yes |
74
- | `READ_NEVER_WRITTEN` | A warning: a resource reads a capability nothing in the package writes, so it only ever holds its defaults. | Yes |
75
- | `NO_TERMINATION` | A warning: the game declares neither `maxTicks` nor a tick controller, so only its engine can end it. | Yes |
76
- | `SCENARIO_EDITOR_UNREACHABLE` | A warning: the game ships a scenario editor but does not set `customScenarios.supported`, so no host ever opens it. | Yes |
77
- | `EDITOR_ENDPOINT_STATEFUL` | The scenario editor lists an endpoint that declares `reads`, `writes` or `actions`, which need a session the editor does not have. | Yes |
78
- | `EXTERNAL_REQUEST_NOT_OBJECT` | An external endpoint's `requestSchema` does not declare `"type": "object"` at the top, which a caller outside the game needs to pass named arguments. | Yes |
79
- | `ENDPOINT_UNREQUESTED` | A warning: an internal endpoint no user interface lists in its `endpoints`. | Yes |
80
- | `PLATFORM_REJECTED` | The platform refused the uploaded package as invalid. | |
81
- | `VERSION_EXISTS` | The platform already has this version of the package. Bump it and publish again. | |
51
+ | Code | When | Also a diagnostic |
52
+ | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
53
+ | `PACKAGE_INVALID` | The package fails validation. The diagnostics say where. As a diagnostic code, a finding no finer code describes yet. | Yes |
54
+ | `MANIFEST_NOT_FOUND` | There is no seriousgaming.sdk.json (or package.json) where the command looked. | |
55
+ | `MANIFEST_INVALID` | seriousgaming.sdk.json or package.json cannot be read, or is not valid. | |
56
+ | `BUNDLE_INVALID` | A resource's bundle file (such as engine.sdk.json) cannot be read, or is not valid. | |
57
+ | `LOGIC_NODE_BUILTIN` | Game logic imports a Node built-in, which is absent in production: logic runs on the JavaScript language alone. | Yes |
58
+ | `LOGIC_BUNDLE_FAILED` | A logic file does not bundle: a syntax error, or an import that does not resolve. | Yes |
59
+ | `SCHEMA_INVALID` | A bundle or the manifest does not match the SDK's schema. The diagnostic's pointer names the value. | Yes |
60
+ | `JSON_INVALID` | A bundle file is not valid JSON. | Yes |
61
+ | `BUNDLE_MISSING` | A resource directory holds no bundle file. | Yes |
62
+ | `REMOVED_FIELD` | A bundle or the manifest carries a field the SDK no longer reads. The hint says what replaced it. | Yes |
63
+ | `LAYOUT_OUTDATED` | A directory or bundle file sits where an earlier version of the SDK kept it. The hint says where it goes now. | Yes |
64
+ | `FEATURE_UNSUPPORTED` | The manifest's `requires` names an optional feature this version of the SDK does not support. | Yes |
65
+ | `FEATURE_UNDECLARED` | The package uses an optional feature its manifest's `requires` does not list, so a runtime without the feature would run it with part of it missing. | Yes |
66
+ | `REFERENCE_UNKNOWN` | A `reads`, `writes`, `settings`, `configures` or `endpoints` entry names something the package does not declare. | Yes |
67
+ | `SETTINGS_UNKNOWN` | A scenario overrides a settings resource the package does not declare. | Yes |
68
+ | `SETTINGS_UNKNOWN_KEY` | A scenario overrides a key that its settings resource does not declare. | Yes |
69
+ | `SETTINGS_INVALID` | A scenario's override does not match its settings resource's schema. | Yes |
70
+ | `SETTINGS_RESERVED` | A settings resource is named `game`, which is reserved for the built-in game settings. | Yes |
71
+ | `SETTINGS_LOCKED` | A scenario overrides a setting the game locks with `readOnly`, in its settings schema or its `gameSettingsConstraints`. | Yes |
72
+ | `GAME_CONSTRAINT_INVALID` | A `gameSettingsConstraints` entry widens the SDK schema for the `game` settings rather than narrowing it. | Yes |
73
+ | `GAME_CONSTRAINT_VIOLATED` | The game's own value for a `game` setting breaks its `gameSettingsConstraints`. | Yes |
74
+ | `LOGIC_EXPORT_MISSING` | A logic file is missing, or does not export the functions its resource needs. | Yes |
75
+ | `READ_NEVER_WRITTEN` | A warning: a resource reads a capability nothing in the package writes, so it only ever holds its defaults. | Yes |
76
+ | `NO_TERMINATION` | A warning: the game declares neither `maxTicks` nor a tick controller, so only its engine can end it. | Yes |
77
+ | `SCENARIO_EDITOR_UNREACHABLE` | A warning: the game ships a scenario editor but does not set `customScenarios.supported`, so no host ever opens it. | Yes |
78
+ | `SCENARIO_REFUSED` | A validator's `Scenario` gate found a problem with a package scenario, or with the defaults when no scenario is the default. The diagnostic points at the setting it names. | Yes |
79
+ | `EDITOR_ENDPOINT_NOT_SCENARIO` | The scenario editor lists an endpoint that is not scenario-scoped. It works on a scenario draft with no session, so it calls `"scope": "scenario"` endpoints alone. | Yes |
80
+ | `SCENARIO_ENDPOINT_STATEFUL` | A scenario-scoped endpoint declares `reads`, `writes`, `actions` or `roster`, which need a session a scenario draft does not have. | Yes |
81
+ | `EXTERNAL_REQUEST_NOT_OBJECT` | An external endpoint's `requestSchema` does not declare `"type": "object"` at the top, which a caller outside the game needs to pass named arguments. | Yes |
82
+ | `ENDPOINT_UNREQUESTED` | A warning: an internal endpoint no user interface lists in its `endpoints`. | Yes |
83
+ | `PLATFORM_REJECTED` | The platform refused the uploaded package as invalid. | |
84
+ | `VERSION_EXISTS` | The platform already has this version of the package. Bump it and publish again. | |
82
85
 
83
86
  ### Exit 4: refused by the game
84
87
 
@@ -123,33 +126,36 @@ A code marked as a diagnostic also appears in a failure's `diagnostics`, one fin
123
126
 
124
127
  The codes a diagnostic carries. `LOGIC_ERROR` is only ever a diagnostic: it sits under the command's `TICK_FAILED`, `SESSION_ERROR`, `HANDLER_ERROR` or `LLM_NOT_CONFIGURED`.
125
128
 
126
- | Code | When |
127
- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
128
- | `PACKAGE_INVALID` | The package fails validation. The diagnostics say where. As a diagnostic code, a finding no finer code describes yet. |
129
- | `SCHEMA_INVALID` | A bundle or the manifest does not match the SDK's schema. The diagnostic's pointer names the value. |
130
- | `JSON_INVALID` | A bundle file is not valid JSON. |
131
- | `BUNDLE_MISSING` | A resource directory holds no bundle file. |
132
- | `REMOVED_FIELD` | A bundle or the manifest carries a field the SDK no longer reads. The hint says what replaced it. |
133
- | `LAYOUT_OUTDATED` | A directory or bundle file sits where an earlier version of the SDK kept it. The hint says where it goes now. |
134
- | `FEATURE_UNSUPPORTED` | The manifest's `requires` names an optional feature this version of the SDK does not support. |
135
- | `REFERENCE_UNKNOWN` | A `reads`, `writes`, `settings`, `configures` or `endpoints` entry names something the package does not declare. |
136
- | `SETTINGS_UNKNOWN` | A scenario overrides a settings resource the package does not declare. |
137
- | `SETTINGS_UNKNOWN_KEY` | A scenario overrides a key that its settings resource does not declare. |
138
- | `SETTINGS_INVALID` | A scenario's override does not match its settings resource's schema. |
139
- | `SETTINGS_RESERVED` | A settings resource is named `game`, which is reserved for the built-in game settings. |
140
- | `SETTINGS_LOCKED` | A scenario overrides a setting the game locks with `readOnly`, in its settings schema or its `gameSettingsConstraints`. |
141
- | `GAME_CONSTRAINT_INVALID` | A `gameSettingsConstraints` entry widens the SDK schema for the `game` settings rather than narrowing it. |
142
- | `GAME_CONSTRAINT_VIOLATED` | The game's own value for a `game` setting breaks its `gameSettingsConstraints`. |
143
- | `LOGIC_EXPORT_MISSING` | A logic file is missing, or does not export the functions its resource needs. |
144
- | `LOGIC_NODE_BUILTIN` | Game logic imports a Node built-in, which is absent in production: logic runs on the JavaScript language alone. |
145
- | `LOGIC_BUNDLE_FAILED` | A logic file does not bundle: a syntax error, or an import that does not resolve. |
146
- | `READ_NEVER_WRITTEN` | A warning: a resource reads a capability nothing in the package writes, so it only ever holds its defaults. |
147
- | `NO_TERMINATION` | A warning: the game declares neither `maxTicks` nor a tick controller, so only its engine can end it. |
148
- | `SCENARIO_EDITOR_UNREACHABLE` | A warning: the game ships a scenario editor but does not set `customScenarios.supported`, so no host ever opens it. |
149
- | `EDITOR_ENDPOINT_STATEFUL` | The scenario editor lists an endpoint that declares `reads`, `writes` or `actions`, which need a session the editor does not have. |
150
- | `EXTERNAL_REQUEST_NOT_OBJECT` | An external endpoint's `requestSchema` does not declare `"type": "object"` at the top, which a caller outside the game needs to pass named arguments. |
151
- | `ENDPOINT_UNREQUESTED` | A warning: an internal endpoint no user interface lists in its `endpoints`. |
152
- | `LOGIC_ERROR` | Game logic (an engine, hook, endpoint, validator or tick controller) threw. A diagnostic, not an error code: it sits in `diagnostics` under the command's TICK_FAILED, SESSION_ERROR or HANDLER_ERROR, with the file, line and column it threw at. |
129
+ | Code | When |
130
+ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
131
+ | `PACKAGE_INVALID` | The package fails validation. The diagnostics say where. As a diagnostic code, a finding no finer code describes yet. |
132
+ | `SCHEMA_INVALID` | A bundle or the manifest does not match the SDK's schema. The diagnostic's pointer names the value. |
133
+ | `JSON_INVALID` | A bundle file is not valid JSON. |
134
+ | `BUNDLE_MISSING` | A resource directory holds no bundle file. |
135
+ | `REMOVED_FIELD` | A bundle or the manifest carries a field the SDK no longer reads. The hint says what replaced it. |
136
+ | `LAYOUT_OUTDATED` | A directory or bundle file sits where an earlier version of the SDK kept it. The hint says where it goes now. |
137
+ | `FEATURE_UNSUPPORTED` | The manifest's `requires` names an optional feature this version of the SDK does not support. |
138
+ | `FEATURE_UNDECLARED` | The package uses an optional feature its manifest's `requires` does not list, so a runtime without the feature would run it with part of it missing. |
139
+ | `REFERENCE_UNKNOWN` | A `reads`, `writes`, `settings`, `configures` or `endpoints` entry names something the package does not declare. |
140
+ | `SETTINGS_UNKNOWN` | A scenario overrides a settings resource the package does not declare. |
141
+ | `SETTINGS_UNKNOWN_KEY` | A scenario overrides a key that its settings resource does not declare. |
142
+ | `SETTINGS_INVALID` | A scenario's override does not match its settings resource's schema. |
143
+ | `SETTINGS_RESERVED` | A settings resource is named `game`, which is reserved for the built-in game settings. |
144
+ | `SETTINGS_LOCKED` | A scenario overrides a setting the game locks with `readOnly`, in its settings schema or its `gameSettingsConstraints`. |
145
+ | `GAME_CONSTRAINT_INVALID` | A `gameSettingsConstraints` entry widens the SDK schema for the `game` settings rather than narrowing it. |
146
+ | `GAME_CONSTRAINT_VIOLATED` | The game's own value for a `game` setting breaks its `gameSettingsConstraints`. |
147
+ | `LOGIC_EXPORT_MISSING` | A logic file is missing, or does not export the functions its resource needs. |
148
+ | `LOGIC_NODE_BUILTIN` | Game logic imports a Node built-in, which is absent in production: logic runs on the JavaScript language alone. |
149
+ | `LOGIC_BUNDLE_FAILED` | A logic file does not bundle: a syntax error, or an import that does not resolve. |
150
+ | `READ_NEVER_WRITTEN` | A warning: a resource reads a capability nothing in the package writes, so it only ever holds its defaults. |
151
+ | `NO_TERMINATION` | A warning: the game declares neither `maxTicks` nor a tick controller, so only its engine can end it. |
152
+ | `SCENARIO_EDITOR_UNREACHABLE` | A warning: the game ships a scenario editor but does not set `customScenarios.supported`, so no host ever opens it. |
153
+ | `SCENARIO_REFUSED` | A validator's `Scenario` gate found a problem with a package scenario, or with the defaults when no scenario is the default. The diagnostic points at the setting it names. |
154
+ | `EDITOR_ENDPOINT_NOT_SCENARIO` | The scenario editor lists an endpoint that is not scenario-scoped. It works on a scenario draft with no session, so it calls `"scope": "scenario"` endpoints alone. |
155
+ | `SCENARIO_ENDPOINT_STATEFUL` | A scenario-scoped endpoint declares `reads`, `writes`, `actions` or `roster`, which need a session a scenario draft does not have. |
156
+ | `EXTERNAL_REQUEST_NOT_OBJECT` | An external endpoint's `requestSchema` does not declare `"type": "object"` at the top, which a caller outside the game needs to pass named arguments. |
157
+ | `ENDPOINT_UNREQUESTED` | A warning: an internal endpoint no user interface lists in its `endpoints`. |
158
+ | `LOGIC_ERROR` | Game logic (an engine, hook, endpoint, validator or tick controller) threw. A diagnostic, not an error code: it sits in `diagnostics` under the command's TICK_FAILED, SESSION_ERROR or HANDLER_ERROR, with the file, line and column it threw at. |
153
159
 
154
160
  ## Warning codes
155
161
 
@@ -210,33 +210,36 @@ Without `--json`, each diagnostic that names a file is printed under the error a
210
210
 
211
211
  #### Diagnostic codes
212
212
 
213
- | Code | When |
214
- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
215
- | `PACKAGE_INVALID` | The package fails validation. The diagnostics say where. As a diagnostic code, a finding no finer code describes yet. |
216
- | `SCHEMA_INVALID` | A bundle or the manifest does not match the SDK's schema. The diagnostic's pointer names the value. |
217
- | `JSON_INVALID` | A bundle file is not valid JSON. |
218
- | `BUNDLE_MISSING` | A resource directory holds no bundle file. |
219
- | `REMOVED_FIELD` | A bundle or the manifest carries a field the SDK no longer reads. The hint says what replaced it. |
220
- | `LAYOUT_OUTDATED` | A directory or bundle file sits where an earlier version of the SDK kept it. The hint says where it goes now. |
221
- | `FEATURE_UNSUPPORTED` | The manifest's `requires` names an optional feature this version of the SDK does not support. |
222
- | `REFERENCE_UNKNOWN` | A `reads`, `writes`, `settings`, `configures` or `endpoints` entry names something the package does not declare. |
223
- | `SETTINGS_UNKNOWN` | A scenario overrides a settings resource the package does not declare. |
224
- | `SETTINGS_UNKNOWN_KEY` | A scenario overrides a key that its settings resource does not declare. |
225
- | `SETTINGS_INVALID` | A scenario's override does not match its settings resource's schema. |
226
- | `SETTINGS_RESERVED` | A settings resource is named `game`, which is reserved for the built-in game settings. |
227
- | `SETTINGS_LOCKED` | A scenario overrides a setting the game locks with `readOnly`, in its settings schema or its `gameSettingsConstraints`. |
228
- | `GAME_CONSTRAINT_INVALID` | A `gameSettingsConstraints` entry widens the SDK schema for the `game` settings rather than narrowing it. |
229
- | `GAME_CONSTRAINT_VIOLATED` | The game's own value for a `game` setting breaks its `gameSettingsConstraints`. |
230
- | `LOGIC_EXPORT_MISSING` | A logic file is missing, or does not export the functions its resource needs. |
231
- | `LOGIC_NODE_BUILTIN` | Game logic imports a Node built-in, which is absent in production: logic runs on the JavaScript language alone. |
232
- | `LOGIC_BUNDLE_FAILED` | A logic file does not bundle: a syntax error, or an import that does not resolve. |
233
- | `READ_NEVER_WRITTEN` | A warning: a resource reads a capability nothing in the package writes, so it only ever holds its defaults. |
234
- | `NO_TERMINATION` | A warning: the game declares neither `maxTicks` nor a tick controller, so only its engine can end it. |
235
- | `SCENARIO_EDITOR_UNREACHABLE` | A warning: the game ships a scenario editor but does not set `customScenarios.supported`, so no host ever opens it. |
236
- | `EDITOR_ENDPOINT_STATEFUL` | The scenario editor lists an endpoint that declares `reads`, `writes` or `actions`, which need a session the editor does not have. |
237
- | `EXTERNAL_REQUEST_NOT_OBJECT` | An external endpoint's `requestSchema` does not declare `"type": "object"` at the top, which a caller outside the game needs to pass named arguments. |
238
- | `ENDPOINT_UNREQUESTED` | A warning: an internal endpoint no user interface lists in its `endpoints`. |
239
- | `LOGIC_ERROR` | Game logic (an engine, hook, endpoint, validator or tick controller) threw. A diagnostic, not an error code: it sits in `diagnostics` under the command's TICK_FAILED, SESSION_ERROR or HANDLER_ERROR, with the file, line and column it threw at. |
213
+ | Code | When |
214
+ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
215
+ | `PACKAGE_INVALID` | The package fails validation. The diagnostics say where. As a diagnostic code, a finding no finer code describes yet. |
216
+ | `SCHEMA_INVALID` | A bundle or the manifest does not match the SDK's schema. The diagnostic's pointer names the value. |
217
+ | `JSON_INVALID` | A bundle file is not valid JSON. |
218
+ | `BUNDLE_MISSING` | A resource directory holds no bundle file. |
219
+ | `REMOVED_FIELD` | A bundle or the manifest carries a field the SDK no longer reads. The hint says what replaced it. |
220
+ | `LAYOUT_OUTDATED` | A directory or bundle file sits where an earlier version of the SDK kept it. The hint says where it goes now. |
221
+ | `FEATURE_UNSUPPORTED` | The manifest's `requires` names an optional feature this version of the SDK does not support. |
222
+ | `FEATURE_UNDECLARED` | The package uses an optional feature its manifest's `requires` does not list, so a runtime without the feature would run it with part of it missing. |
223
+ | `REFERENCE_UNKNOWN` | A `reads`, `writes`, `settings`, `configures` or `endpoints` entry names something the package does not declare. |
224
+ | `SETTINGS_UNKNOWN` | A scenario overrides a settings resource the package does not declare. |
225
+ | `SETTINGS_UNKNOWN_KEY` | A scenario overrides a key that its settings resource does not declare. |
226
+ | `SETTINGS_INVALID` | A scenario's override does not match its settings resource's schema. |
227
+ | `SETTINGS_RESERVED` | A settings resource is named `game`, which is reserved for the built-in game settings. |
228
+ | `SETTINGS_LOCKED` | A scenario overrides a setting the game locks with `readOnly`, in its settings schema or its `gameSettingsConstraints`. |
229
+ | `GAME_CONSTRAINT_INVALID` | A `gameSettingsConstraints` entry widens the SDK schema for the `game` settings rather than narrowing it. |
230
+ | `GAME_CONSTRAINT_VIOLATED` | The game's own value for a `game` setting breaks its `gameSettingsConstraints`. |
231
+ | `LOGIC_EXPORT_MISSING` | A logic file is missing, or does not export the functions its resource needs. |
232
+ | `LOGIC_NODE_BUILTIN` | Game logic imports a Node built-in, which is absent in production: logic runs on the JavaScript language alone. |
233
+ | `LOGIC_BUNDLE_FAILED` | A logic file does not bundle: a syntax error, or an import that does not resolve. |
234
+ | `READ_NEVER_WRITTEN` | A warning: a resource reads a capability nothing in the package writes, so it only ever holds its defaults. |
235
+ | `NO_TERMINATION` | A warning: the game declares neither `maxTicks` nor a tick controller, so only its engine can end it. |
236
+ | `SCENARIO_EDITOR_UNREACHABLE` | A warning: the game ships a scenario editor but does not set `customScenarios.supported`, so no host ever opens it. |
237
+ | `SCENARIO_REFUSED` | A validator's `Scenario` gate found a problem with a package scenario, or with the defaults when no scenario is the default. The diagnostic points at the setting it names. |
238
+ | `EDITOR_ENDPOINT_NOT_SCENARIO` | The scenario editor lists an endpoint that is not scenario-scoped. It works on a scenario draft with no session, so it calls `"scope": "scenario"` endpoints alone. |
239
+ | `SCENARIO_ENDPOINT_STATEFUL` | A scenario-scoped endpoint declares `reads`, `writes`, `actions` or `roster`, which need a session a scenario draft does not have. |
240
+ | `EXTERNAL_REQUEST_NOT_OBJECT` | An external endpoint's `requestSchema` does not declare `"type": "object"` at the top, which a caller outside the game needs to pass named arguments. |
241
+ | `ENDPOINT_UNREQUESTED` | A warning: an internal endpoint no user interface lists in its `endpoints`. |
242
+ | `LOGIC_ERROR` | Game logic (an engine, hook, endpoint, validator or tick controller) threw. A diagnostic, not an error code: it sits in `diagnostics` under the command's TICK_FAILED, SESSION_ERROR or HANDLER_ERROR, with the file, line and column it threw at. |
240
243
 
241
244
  ### Non-interactive use
242
245
 
@@ -1265,6 +1268,7 @@ Start the session, or put a running one back at tick 0.
1265
1268
  | `--locale [LOCALE]` | | Session locale to run the game in (defaults to en). |
1266
1269
  | `--no-server` | | Run in this process instead of starting a dev server. |
1267
1270
  | `--walkthrough` | | Drive the walkthrough run rather than the session. |
1271
+ | `--summary` | | Print only the session head, without any context. |
1268
1272
 
1269
1273
  Starts the session, or rebuilds a running one from the package. Any session command starts a session when none is running, so a fresh package needs no `init` at all. Reach for it to rebuild an existing session with a different team count, scenario, or locale, or after editing settings.
1270
1274
 
@@ -1275,6 +1279,7 @@ In more detail:
1275
1279
  - `--teams`: a whole number, one or more; anything else is a usage error (exit 2). Each team has its own context. See [Multi-team games](./guides/multi-team-games.md)
1276
1280
  - `--participants`: zero is allowed, for testing a team before anybody has joined it. Without it, each team gets one, or the game's `perTeam.minParticipants`. The count is kept for later `init` runs until you pass a different `--teams`, which drops a per-team list
1277
1281
  - `--scenario`: the scenario's settings overrides sit between the settings defaults and the session overrides (see [Overriding settings](./guides/settings.md#overriding-settings)). If omitted and the game has a default scenario, the default is used. A scenario the package does not hold is `RESOURCE_NOT_FOUND` (exit 2). See [Scenarios](./guides/scenarios.md)
1282
+ - `--summary`: print `gameId`, `completedTicks`, `maxTicks`, `complete` and `scenario`, with no context. See [A summary instead of the state](#a-summary-instead-of-the-state)
1278
1283
  - `--walkthrough`: see [Walkthrough runs](#walkthrough-runs)
1279
1284
 
1280
1285
  **Output:** JSON with the initial context and tick data, and `scenario`, the scenario the session started on (`null` when it has none). `maxTicks` is omitted for goal-based games whose `game` settings set no `maxTicks`. `sharedContext` is included when the game has shared capabilities, and `teamContexts` when it has several teams.
@@ -1329,6 +1334,7 @@ Execute the next tick, initializing the game first if it has not been run yet.
1329
1334
  | `--locale [LOCALE]` | | Change the session locale for this tick onwards. |
1330
1335
  | `--no-server` | | Run in this process instead of starting a dev server. |
1331
1336
  | `--walkthrough` | | Drive the walkthrough run rather than the session. |
1337
+ | `--summary` | | Print only the session head, without any context. |
1332
1338
 
1333
1339
  Executes one tick, optionally applying decisions first. Against a running `sdk dev` this advances that session, and the person watching the browser sees it immediately. With nothing running it starts a session and then ticks.
1334
1340
 
@@ -1344,6 +1350,7 @@ In more detail:
1344
1350
  - `--patch`: paths start at the capability (`/price/Price`)
1345
1351
  - `--team N`: the stable team id `team-N` to tick, and the team the `--patch` applies to. Required with `--patch` in a multi-team game, and refused in a one-team game
1346
1352
  - `--teams`, `--participants` and `--scenario` apply to the first run, when the tick starts the session. `--locale` changes the session locale from this tick onwards
1353
+ - `--summary`: print `gameId`, `completedTicks`, `maxTicks` and `complete`, with no context. See [A summary instead of the state](#a-summary-instead-of-the-state)
1347
1354
  - `--walkthrough`: see [Walkthrough runs](#walkthrough-runs)
1348
1355
 
1349
1356
  **Output:** JSON with the updated context for this tick. It includes `complete: true` when a tick controller has signalled that the game is finished. If the game is already complete, the command exits non-zero with the refusal.
@@ -1425,6 +1432,7 @@ View the current game state.
1425
1432
  | `-w, --working-dir [PATH]` | the current directory | The working directory to execute in. |
1426
1433
  | `--team [NUMBER]` | | Show a specific team (multi-team games only, 1-based). |
1427
1434
  | `--full` | | Print the whole state projection rather than the reading summary. |
1435
+ | `--summary` | | Print only the session head, without any context or roster. |
1428
1436
  | `--tick [NUMBER]` | | Print a past committed tick rather than the current one. |
1429
1437
  | `--to [NUMBER]` | | With --tick, print every tick from --tick to this one. |
1430
1438
  | `--no-server` | | Run in this process instead of starting a dev server. |
@@ -1438,6 +1446,7 @@ In more detail:
1438
1446
  - `--full`: the whole state projection is the session, every team's context and roster, the shared store, the resolved `settings`, the timer, and any armed faults. It is the same document the dev server serves at `GET /api/state` and the console renders from
1439
1447
  - `--tick N`: the state as it was at committed tick N, from the session's own snapshots. Returns `{ "entries": [...] }`, one per team per tick, each with `tick`, `teamId`, `index`, `name`, `context`, `recordedAt` and `complete`. The current tick is not in the past, so use `view` on its own for that
1440
1448
  - `--to M`: M is clamped to the last committed tick, so `--tick 0 --to 99` reads everything there is
1449
+ - `--summary`: print `gameId`, `completedTicks`, `maxTicks` and `complete`, with no context and no roster. With `--team N`, it adds `team` and `name`, and `completedTicks` and `complete` are that team's. It cannot be combined with `--full` or `--tick` (`USAGE_BAD_FLAG`, exit 2). See [A summary instead of the state](#a-summary-instead-of-the-state)
1441
1450
 
1442
1451
  **Output:** JSON with the latest tick data, the context, and each team's roster. In a multi-team game without `--team`, it returns `{ "teams": [...] }`. Every team carries `participants`, each with its `id`, `name`, `index`, and `connected`, so the plain view already answers who is in the room.
1443
1452
 
@@ -1453,6 +1462,25 @@ pnpm run sdk view --full
1453
1462
  pnpm run sdk view --tick 1 --to 3 --team 2
1454
1463
  ```
1455
1464
 
1465
+ ### A summary instead of the state
1466
+
1467
+ `init`, `tick` and `view` print the whole context by default, which for a large game runs to thousands of lines. A smoke check (does this game initialise and tick?) needs only the exit code and the head of the session, so each takes `--summary`:
1468
+
1469
+ ```bash
1470
+ pnpm run sdk tick --summary
1471
+ ```
1472
+
1473
+ ```json
1474
+ {
1475
+ "gameId": "com.example.factory.game",
1476
+ "completedTicks": 1,
1477
+ "maxTicks": 10,
1478
+ "complete": false
1479
+ }
1480
+ ```
1481
+
1482
+ The shape is the same for all three, except that `init` adds `scenario`, as it does without the flag. With `--json`, the envelope's `data` is this object. A failure is unchanged: it exits non-zero with the error envelope, and warnings still go to stderr and the envelope's `warnings`.
1483
+
1456
1484
  ### Undo, reset, and reconfigure
1457
1485
 
1458
1486
  ```text
@@ -1722,14 +1750,15 @@ pnpm run sdk blob upload <file> [options]
1722
1750
 
1723
1751
  Upload a file as a blob and print its blob ID.
1724
1752
 
1725
- | Option | Default | Description |
1726
- | -------------------------- | --------------------- | --------------------------------------------------------- |
1727
- | `-w, --working-dir [PATH]` | the current directory | The working directory to execute in. |
1728
- | `--settings` | | Store with settings retention (survives a session reset). |
1753
+ | Option | Default | Description |
1754
+ | -------------------------- | --------------------- | -------------------------------------------------------------------------------------- |
1755
+ | `-w, --working-dir [PATH]` | the current directory | The working directory to execute in. |
1756
+ | `--settings` | | Store with settings retention (survives a session reset). |
1757
+ | `--scenario` | | Store as a scenario draft's file, for a file setting (no session operation clears it). |
1729
1758
 
1730
1759
  Uploads a file and associates it with the game session. It returns the `blob:`-prefixed asset reference that you can patch into the game context for the engine and user interfaces to use (see [Asset references](./guides/file-handling.md#asset-references)).
1731
1760
 
1732
- `--settings` stores the blob with `'settings'` retention, as a setup or scenario editor upload is, which survives a session reset. Without it the blob has `'game'` retention, cleared on reset.
1761
+ `--settings` stores the blob with `'settings'` retention, as a setup upload is, which survives a session reset. `--scenario` stores it as a scenario draft's file, as a scenario editor upload is, which no session operation clears: use it for a file an agent writes into a [setting that holds a file](guides/settings.md#settings-that-hold-a-file). Without either the blob has `'game'` retention, cleared on reset. `--settings` and `--scenario` cannot be combined (`USAGE_BAD_FLAG`).
1733
1762
 
1734
1763
  **Output (default):**
1735
1764
 
@@ -1775,18 +1804,19 @@ pnpm run sdk endpoint call <identifier> [options]
1775
1804
 
1776
1805
  Invoke an endpoint against the running session and print its response.
1777
1806
 
1778
- | Option | Default | Description |
1779
- | ------------------------------ | --------------------- | ------------------------------------------------------------------------- |
1780
- | `-w, --working-dir [PATH]` | the current directory | The working directory to execute in. |
1781
- | `-r, --request [JSON]` | | The request payload, as JSON. |
1782
- | `-f, --file [PATH]` | | Read the request payload from a file. |
1783
- | `-t, --team [INDEX]` | | The team a team-scoped endpoint acts on (one-based). |
1784
- | `--external` | | Call as a caller outside the game, which reaches only external endpoints. |
1785
- | `--principal [KIND:ID[:NAME]]` | | With --external, who the call stands in for, e.g. agent:claude-7:Claude. |
1786
- | `--attach [FIELD=PATH]` | | Send a local file as a file field, inline as a data: URI (repeatable). |
1787
- | `--save-blobs [DIR]` | | Save every file the response names into DIR. |
1788
- | `--no-server` | | Run in this process rather than against a dev server. |
1789
- | `--walkthrough` | | Drive the walkthrough run rather than the session. |
1807
+ | Option | Default | Description |
1808
+ | ------------------------------ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
1809
+ | `-w, --working-dir [PATH]` | the current directory | The working directory to execute in. |
1810
+ | `-r, --request [JSON]` | | The request payload, as JSON. |
1811
+ | `-f, --file [PATH]` | | Read the request payload from a file. |
1812
+ | `-t, --team [INDEX]` | | The team a team-scoped endpoint acts on (one-based). |
1813
+ | `--external` | | Call as a caller outside the game, which reaches only external endpoints. |
1814
+ | `--principal [KIND:ID[:NAME]]` | | With --external, who the call stands in for, e.g. agent:claude-7:Claude. |
1815
+ | `--attach [FIELD=PATH]` | | Send a local file as a file field, inline as a data: URI (repeatable). |
1816
+ | `--save-blobs [DIR]` | | Save every file the response names into DIR. |
1817
+ | `--draft [SCENARIO]` | | Call a scenario-scoped endpoint on the draft of SCENARIO (the package's own settings when omitted), as the scenario's author. |
1818
+ | `--no-server` | | Run in this process rather than against a dev server. |
1819
+ | `--walkthrough` | | Drive the walkthrough run rather than the session. |
1790
1820
 
1791
1821
  Invokes one of the package's endpoints against the running session and prints its response as JSON.
1792
1822
 
@@ -1798,6 +1828,7 @@ In more detail:
1798
1828
  - `--principal`: who the call stands in for, as a platform would say after authenticating its caller. The handler sees it as `caller.principal`, and the audit records it
1799
1829
  - `--attach`: a file field is one whose schema carries `blob`. A dotted field reaches into nested objects
1800
1830
  - `--save-blobs`: each `blob:` reference in the response is saved into `DIR` under its stored name
1831
+ - `--draft`: calls a [scenario-scoped endpoint](guides/endpoints.md#scenario-scoped-endpoints) on the draft of the scenario named, or of the package's own settings when none is, rather than on the session. The handler sees the draft's settings and `caller.role` as `'author'`. With `--external` it is called as an agent writing the scenario would call it, so an internal endpoint is refused. It cannot be combined with `--team` (`USAGE_BAD_FLAG`), since a draft has no teams
1801
1832
  - `--json`: the [envelope](#json-output) carries the response as `data`, or the failure (see below)
1802
1833
 
1803
1834
  The request may also arrive on stdin, so a payload built by another command can be piped straight in.
@@ -1845,6 +1876,12 @@ pnpm run sdk endpoint call export --external --save-blobs ./exports
1845
1876
 
1846
1877
  To send a file the other way, upload it first with `sdk blob upload` and put the `blob:` reference it prints in the request.
1847
1878
 
1879
+ A scenario-scoped endpoint, as an agent writing the `hard_mode` scenario calls it:
1880
+
1881
+ ```bash
1882
+ pnpm run sdk endpoint call previewround --draft hard_mode --external --request '{"price": 10, "workers": 20}'
1883
+ ```
1884
+
1848
1885
  A team-scoped endpoint that changes state:
1849
1886
 
1850
1887
  ```bash
@@ -1952,6 +1989,7 @@ Start the Serious Gaming development server with hot reload.
1952
1989
  | `--fake-clock` | | Run on a clock that moves only when `sdk clock advance` moves it, to test automatic ticks without waiting. |
1953
1990
  | `--reinit-on-change` | | Restart the game at tick 0 whenever an edit applies only at initialisation (a setting, a manifest field such as teams, a capability removed or rescoped), rather than recording it as pending once play is under way. |
1954
1991
  | `--isolated` | | Run beside any dev server already running for this package, for tests and recordings: no lock file (CLI commands reach it through SERIOUSGAMING_DEV_URL), configuration from the package alone, and uploads in a temporary directory. |
1992
+ | `--brand <FILE>` | | A brand file to preview the game in, added to the brand picker and selected; repeat for more than one. |
1955
1993
 
1956
1994
  In more detail:
1957
1995
 
@@ -1963,6 +2001,7 @@ In more detail:
1963
2001
  - `--participants`: zero is allowed. Without it, each team gets one, or the game's `perTeam.minParticipants`
1964
2002
  - `--fake-clock`: moved with [`sdk clock advance`](#the-tick-timer)
1965
2003
  - `--reinit-on-change`: however far play has gone, rather than holding the edit as pending (see [What reloads](#what-reloads)). The console shows a short 'Settings changed, game restarted' notice each time. The hosted builder starts the dev server this way
2004
+ - `--brand`: a brand file to preview the game in, added to the console's **Brand** menu and selected. Repeat it for more than one; the first is selected. See [Preview your game in another brand](./guides/theming-and-branding.md#preview-your-game-in-another-brand)
1966
2005
  - `--isolated`: for a test run or a recording (see below)
1967
2006
 
1968
2007
  A package holds one session, so a second `sdk dev` for the same package is refused whatever port it asks for, and names the one already running. Stop that one with `sdk dev stop` to move it elsewhere, or start the second with `--isolated`.
@@ -2391,7 +2430,7 @@ pnpm run --silent sdk package publish --json > publish.json
2391
2430
  **Errors:**
2392
2431
 
2393
2432
  - `400` (`PLATFORM_REJECTED`, exit 3): each structured validation error (`{field, message}`) in the server's `errors[]` array is rendered as `field: message` on its own line. A version uploaded against the wrong publisher surfaces here
2394
- - `401` and `403` (`PLATFORM_UNAUTHORISED`, exit 5): 'Invalid API key. Check $SERIOUSGAMING_API_KEY and that it has not been revoked.', or 'The account that created this API key does not have publishing access. Ask Business Simulations to grant it.'
2433
+ - `401` and `403` (`PLATFORM_UNAUTHORISED`, exit 5): 'Invalid API key. Check $SERIOUSGAMING_API_KEY and that it has not been revoked.', or 'The account that created this API key does not have publishing access. Ask Serious Gaming support to grant it.'
2395
2434
  - `409` (`VERSION_EXISTS`, exit 3): 'Version {x.y.z} of {identifier} already exists. Bump it with `seriousgaming-sdk package version patch` and try again.'
2396
2435
  - Any other status (`PLATFORM_ERROR`, exit 5)
2397
2436
  - Network errors (`PLATFORM_UNREACHABLE`, exit 5) are surfaced with the original message
@@ -1,6 +1,10 @@
1
1
  # Core concepts
2
2
 
3
- The model behind the SDK on one page. Each resource kind has one guide that explains it in full and is its reference; this page says how they fit together. For the words these docs use, each with one meaning, see the [terminology](./terminology.md).
3
+ The model behind the SDK on one page, and how its parts fit together.
4
+
5
+ A serious game built with it has four moving parts: the **state** each team plays with, the **rules** that move that state on one round at a time, the **screens** participants and the facilitator see, and the **settings** that make one game serve many groups. Everything below is one of those, or how they connect.
6
+
7
+ Each resource kind has one guide that explains it in full and is its reference; this page says how they fit together. For the words these docs use, each with one meaning, see the [terminology](./terminology.md).
4
8
 
5
9
  ## A package is a game
6
10
 
@@ -27,20 +31,84 @@ A game holds exactly one of some kinds, each in a fixed **slot** named for it, a
27
31
 
28
32
  ## How a session runs
29
33
 
30
- 1. A facilitator creates a session, choosing a scenario and, if the game has a setup screen, filling it in. The session's settings are resolved and fixed
31
- 2. The engine's `Init` runs once per team, and the teams' surfaces mount
34
+ The same five steps as on the [home page](../index.md#how-a-session-runs), in terms of the code you write:
35
+
36
+ 1. A facilitator creates a session, choosing a scenario and, if the game has a [setup screen](../guides/setup.md), filling it in. The session's settings are resolved and fixed
37
+ 2. Participants join and are placed in teams. The engine's `Init` runs once per team, and each participant's game UI mounts
32
38
  3. In each round, participants make decisions: each is a write to their team's state, checked by the game's validators
33
- 4. A tick, requested by hand or by the tick controller, runs the engine's `Run` on what the teams submitted and records the round as a snapshot
34
- 5. When the last tick has run, or the tick controller says so, the game is complete
39
+ 4. A tick, requested by the facilitator or by the tick controller, runs the engine's `Run` on what the teams submitted, records the round as a snapshot, and every surface shows the result
40
+ 5. When the last tick has run, or the tick controller says so, the game is complete, and the facilitator leads the debrief, often from the [presentation](../guides/presentation.md)
35
41
 
36
42
  The [CLI and the dev server](../cli-and-dev-server.md) run the same session on your machine.
37
43
 
44
+ ## The model on one screen
45
+
46
+ A package, trimmed to the parts most games have:
47
+
48
+ ```
49
+ my-game/
50
+ ├── seriousgaming.sdk.json # identifier, locales, teams, waiting room
51
+ ├── package.json # the version
52
+ ├── capabilities/plan/ # state: capability.sdk.json holds a variablesSchema
53
+ ├── capabilities/results/
54
+ ├── settings/menu/ # parameters: settings.sdk.json holds a settingsSchema, every property with a default
55
+ ├── engine/ # rules: engine.sdk.json, logic.ts (Init, Run), types.ts (generated)
56
+ ├── validators/plan-within-capacity/
57
+ ├── ui/ # the participant's screen: ui.sdk.json, index.html, src/ (React)
58
+ ├── session/ # the facilitator's screen
59
+ └── scenarios/heatwave/ # a variant: settings overrides and assets
60
+ ```
61
+
62
+ Every resource declares what it touches in its bundle, and receives exactly that. The engine's `engine/engine.sdk.json`:
63
+
64
+ ```json
65
+ {
66
+ "definition": {
67
+ "reads": ["plan", "results"],
68
+ "writes": ["results"],
69
+ "settings": ["menu"]
70
+ },
71
+ "logic": { "directory": ".", "entrypoint": "logic.ts" },
72
+ "rootDirectory": "."
73
+ }
74
+ ```
75
+
76
+ Add `"uses": ["generateText"]` to call an external service such as generated text. The logic, typed from the generated `types.ts`, returns what it writes under `capabilities`, built with spreads. A simplified engine, with one number to plan where the [starter game](../guides/starter-game.md) has a whole menu:
77
+
78
+ ```typescript
79
+ import type { InitializationFunction, RunFunction } from '@seriousgaming/sdk';
80
+ import type { Context, Settings } from './types';
81
+
82
+ export const Init: InitializationFunction<Context, Settings> = async ({ context }) => ({
83
+ capabilities: { ...context, results: { ...context.results, Day: 0 } },
84
+ });
85
+
86
+ export const Run: RunFunction<Context, Settings> = async ({ context, settings }) => {
87
+ const sold = Math.min(context.plan.Make, settings.menu.Capacity);
88
+ return {
89
+ capabilities: {
90
+ ...context,
91
+ results: { ...context.results, Day: context.results.Day + 1, Sold: sold },
92
+ },
93
+ };
94
+ };
95
+ ```
96
+
97
+ What not to do:
98
+
99
+ - Never change `context` in place: return a new object
100
+ - Never return the capabilities flat: they go under `capabilities`, or the call fails
101
+ - Never use `Math.random()` or the clock in logic, since a round may run more than once: derive from `meta.seed` and read `meta.now`
102
+ - Never reach for Node.js or browser APIs in logic: it has the JavaScript language alone, and the callbacks it declares
103
+ - Never write a type by hand that mirrors a schema: run `pnpm run sdk generate` and import from `types.ts`
104
+ - Never hard-code a number a facilitator or scenario might change: make it a setting
105
+
38
106
  ## Key ideas
39
107
 
40
108
  1. **Scoped context**: state is organised under capability identifiers, so names cannot collide (`context.sales.Revenue`)
41
109
  2. **Immutable updates**: logic returns what it writes under `capabilities`, built with spreads, and removes paths with `deletes`. It never changes the context it was given
42
110
  3. **Declared data flow**: every resource declares the capabilities it reads and writes, the settings it reads, and the services it uses, so the SDK can generate exact types and deliver exactly that, and nothing else
43
- 4. **One engine, composed from functions**: a game has one engine, and a simulation with several steps calls them as plain functions from its `Run`, in the order it wants them
111
+ 4. **One engine, composed from functions**: a game has one engine, and a game with several steps calls them as plain functions from its `Run`, in the order it wants them
44
112
  5. **Logic runs anywhere**: logic uses the JavaScript language alone, with no Node.js or browser APIs, and reaches the outside world only through the callbacks it declares, so the same code runs in the dev server and in production
45
113
 
46
114
  Start with [Capabilities](../guides/capabilities.md) for the data model, then [Engine](../guides/engine.md).