@seriousgaming/sdk-tools 1.10.0 → 1.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/agent/guidance.md +31 -23
- package/dist/{cli-5V4N4BR4.js → cli-27TQVLVF.js} +1 -1
- package/dist/{cli-FGP6YYM7.js → cli-3VLBFWHN.js} +8 -8
- package/dist/{cli-XR3O2YTV.js → cli-4F24FUW6.js} +5 -5
- package/dist/{cli-CQ4ZR3ZQ.js → cli-5ATO27Z4.js} +5 -5
- package/dist/{cli-MGZYQDCH.js → cli-5TTJWM2R.js} +5 -5
- package/dist/{cli-6CYAOUYT.js → cli-5UKWX3IU.js} +4 -4
- package/dist/{cli-LLJQI2QP.js → cli-6AMK3DYS.js} +1 -1
- package/dist/{cli-WOFYI7HZ.js → cli-6JWDFCUV.js} +6 -6
- package/dist/{cli-A3AJQZEN.js → cli-6P6V2EHY.js} +7 -7
- package/dist/{cli-RSF5R3HC.js → cli-77T4LJQF.js} +10 -7
- package/dist/{cli-LNEZ6KDW.js → cli-ATAJSIXH.js} +4 -4
- package/dist/{cli-4A7RWFNO.js → cli-ATHATKI5.js} +47 -47
- package/dist/{cli-QW7VXL2V.js → cli-B2QAJ5RQ.js} +5 -5
- package/dist/{cli-BB6CU4ZC.js → cli-BINVO5R7.js} +8 -8
- package/dist/{cli-5SHG2M7E.js → cli-BJFYGVJV.js} +4 -4
- package/dist/{cli-J42N4PJG.js → cli-BZOKZ7LP.js} +11 -9
- package/dist/{cli-MUOLHQNL.js → cli-D3S7NJZ3.js} +1 -1
- package/dist/{cli-WLSACMYA.js → cli-DBMEH4Y5.js} +10 -8
- package/dist/{cli-CLO7HKEQ.js → cli-DH35TZ2Q.js} +4 -2
- package/dist/{cli-2ANX6E3A.js → cli-DQE7ITIR.js} +5 -5
- package/dist/{cli-467VRXGP.js → cli-EEO5ZPAZ.js} +1 -1
- package/dist/{cli-B5DWKRZ4.js → cli-ERJNDBDH.js} +1 -1
- package/dist/{cli-IQBY7Z7Q.js → cli-FT3X3D4P.js} +5 -5
- package/dist/{cli-5TKPT3CY.js → cli-FYPW25VD.js} +4 -4
- package/dist/{cli-36GABN2A.js → cli-G3TU6CP6.js} +5 -5
- package/dist/{cli-NAZTYKZT.js → cli-H6PP2MZT.js} +14 -2
- package/dist/{cli-5XE4OMFL.js → cli-HLI5UEKX.js} +8 -8
- package/dist/{cli-YZJBFKRI.js → cli-HMDYG6PS.js} +5 -5
- package/dist/{cli-2AH6D32V.js → cli-K4HSQWXC.js} +1 -1
- package/dist/{cli-EXUPHPDJ.js → cli-L7F4XKCB.js} +7 -7
- package/dist/{cli-O5WYATAI.js → cli-LHMRUJVN.js} +3 -1
- package/dist/{cli-VALLLE6Y.js → cli-LPFSJ625.js} +7 -7
- package/dist/{cli-HN442ZVK.js → cli-MSNSXVGF.js} +5 -5
- package/dist/{cli-OXU6TTEN.js → cli-NKKCDO6K.js} +5 -5
- package/dist/{cli-L54SXUK6.js → cli-OBLEROSC.js} +4 -4
- package/dist/{cli-RFAPPYXK.js → cli-OF36EA62.js} +8 -8
- package/dist/{cli-XB5PI2XT.js → cli-OM32UURE.js} +6 -6
- package/dist/{cli-2AVPNSAX.js → cli-OMTHTWYJ.js} +6 -6
- package/dist/{cli-I3ZAZYWP.js → cli-OVIJRBFI.js} +8 -8
- package/dist/{cli-IPTHJT3J.js → cli-PNS4KWWC.js} +10 -7
- package/dist/{cli-VZVHS5AP.js → cli-Q7QSWNY2.js} +5 -5
- package/dist/{cli-GRSQRFRG.js → cli-QEFYDXMH.js} +8 -1
- package/dist/{cli-TDLIPYKT.js → cli-QPV3TYOM.js} +8 -8
- package/dist/{cli-PYAST3G5.js → cli-R5SNTPND.js} +6 -6
- package/dist/{cli-WG7MAOCS.js → cli-REAM7LSC.js} +5 -5
- package/dist/{cli-URCHZDTS.js → cli-RHL4B4H7.js} +3 -2
- package/dist/{cli-KNXY43YV.js → cli-RKPQLB7J.js} +1 -1
- package/dist/{cli-PBSLPO6G.js → cli-RMD5WSUQ.js} +4 -4
- package/dist/{cli-PTXOKO2Y.js → cli-S3NHXAJM.js} +1 -1
- package/dist/{cli-33MZSPPK.js → cli-SRXDLMXY.js} +6 -6
- package/dist/{cli-M6AZFIMV.js → cli-TEBV2OIW.js} +5 -2
- package/dist/{cli-35GV2F6R.js → cli-TI2FOFPA.js} +4 -4
- package/dist/{cli-JMNPMDXH.js → cli-TLSTSZAC.js} +7 -7
- package/dist/{cli-XEEOJGBL.js → cli-UIYKPSIY.js} +8 -8
- package/dist/{cli-267QJ2DS.js → cli-UVIURDZC.js} +1 -1
- package/dist/{cli-JAVMRERQ.js → cli-VXLHOZSO.js} +5 -5
- package/dist/{cli-SOO6SEIS.js → cli-WJVPSVF2.js} +10 -7
- package/dist/{cli-RUEPTOWG.js → cli-WNBP3LOD.js} +7 -7
- package/dist/{cli-ILHHJR2S.js → cli-WNHMJM3Z.js} +5 -5
- package/dist/{cli-4JNF3O5N.js → cli-WQ7JBZNW.js} +1 -1
- package/dist/{cli-5DWR7RPQ.js → cli-X3TSTTYI.js} +1 -1
- package/dist/{cli-Z3DITVBE.js → cli-X52TXCNF.js} +7 -7
- package/dist/{cli-HNG6PZW2.js → cli-XJ7JESC2.js} +7 -7
- package/dist/{cli-7NUFHMGE.js → cli-XNOAO6DY.js} +1 -1
- package/dist/{cli-HHRP6FP6.js → cli-XOYUTNER.js} +7 -7
- package/dist/{cli-YFLQ7XOO.js → cli-YYXAGJQR.js} +5 -5
- package/dist/{cli-NQSL2CIH.js → cli-ZGCG6C22.js} +6 -6
- package/dist/cli.js +24 -24
- package/dist/client/index.d.ts +1 -1
- package/dist/client/test-session.d.ts +44 -6
- package/dist/client.js +16 -3
- package/dist/docs/api/index.md +3 -1
- package/dist/docs/api/sdk-tools-client.md +38 -6
- package/dist/docs/api/sdk-tools-vite.md +21 -0
- package/dist/docs/changelog.md +39 -0
- package/dist/docs/guides/endpoints.md +1 -1
- package/dist/docs/guides/engine-testing.md +49 -14
- package/dist/docs/guides/engine.md +2 -2
- package/dist/docs/guides/testing.md +3 -8
- package/dist/docs/guides/upgrading.md +15 -0
- package/dist/docs/page-index.md +4 -3
- package/dist/docs/recipes/create-game.md +1 -1
- package/dist/docs/recipes/fix-duplicate-packages.md +8 -19
- package/dist/oxlint/logic.json +184 -0
- package/dist/playwright.js +16 -3
- package/dist/templates/package/README.md.liquid +1 -0
- package/dist/templates/package/claude/rules/workflow-create-engine.md +1 -1
- package/dist/templates/package/claude/rules/workflow-create-user-interface.md +1 -1
- package/dist/templates/package/claude/rules/workflow-test-engine-or-ui.md +1 -1
- package/dist/templates/package/claude/rules/workflow-update-sdk-version.md +2 -2
- package/dist/templates/package/claude/settings.json.template +1 -0
- package/dist/templates/package/oxfmtrc.json.template +8 -1
- package/dist/templates/package/oxlintrc.json.template +1 -180
- package/dist/templates/package/package.json.liquid +1 -0
- package/dist/templates/package/vite.config.ts.liquid +2 -8
- package/dist/templates/package/vitest.config.ts.liquid +2 -8
- package/dist/templates/starter-game/package.json +2 -1
- package/dist/templates/starter-game/testing/engine/game.engine.test.ts +62 -37
- package/dist/templates/starter-game/vite.config.ts +2 -8
- package/dist/templates/starter-game/vitest.config.ts +4 -3
- package/dist/utils/resource-scan.d.ts +5 -0
- package/dist/vite/index.d.ts +30 -0
- package/dist/vite.js +12 -0
- package/package.json +12 -4
package/dist/cli.js
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
import {
|
|
3
3
|
RESOURCE_DESCRIPTORS,
|
|
4
4
|
lazy
|
|
5
|
-
} from "./cli-
|
|
5
|
+
} from "./cli-ATHATKI5.js";
|
|
6
6
|
import {
|
|
7
7
|
DEV_PORT_ENV_VAR,
|
|
8
8
|
ERROR_OVERLAY_ENV_VAR,
|
|
@@ -139,14 +139,14 @@ function newFileHelp(spec) {
|
|
|
139
139
|
|
|
140
140
|
// cli/program.ts
|
|
141
141
|
var blobUploadCommand = lazy(() => import("./cli-W3RG2MRI.js"), "blobUploadCommand");
|
|
142
|
-
var buildCommand = lazy(() => import("./cli-
|
|
142
|
+
var buildCommand = lazy(() => import("./cli-H6PP2MZT.js"), "buildCommand");
|
|
143
143
|
var buildEngineCommand = lazy(() => import("./cli-5EH4WTH4.js"), "buildEngineCommand");
|
|
144
144
|
var configGetCommand = lazy(() => import("./cli-OXLOGXT3.js"), "configGetCommand");
|
|
145
145
|
var configPathCommand = lazy(() => import("./cli-OXLOGXT3.js"), "configPathCommand");
|
|
146
146
|
var configSetCommand = lazy(() => import("./cli-OXLOGXT3.js"), "configSetCommand");
|
|
147
147
|
var configureCommand = lazy(() => import("./cli-XKAIDYIE.js"), "configureCommand");
|
|
148
|
-
var deleteCommand = lazy(() => import("./cli-
|
|
149
|
-
var devCommand = lazy(() => import("./cli-
|
|
148
|
+
var deleteCommand = lazy(() => import("./cli-6AMK3DYS.js"), "deleteCommand");
|
|
149
|
+
var devCommand = lazy(() => import("./cli-UVIURDZC.js"), "devCommand");
|
|
150
150
|
var devStatusCommand = lazy(() => import("./cli-5Z4D3F6Y.js"), "devStatusCommand");
|
|
151
151
|
var devStopCommand = lazy(() => import("./cli-5Z4D3F6Y.js"), "devStopCommand");
|
|
152
152
|
var docsCommand = lazy(() => import("./cli-44CM2AH2.js"), "docsCommand");
|
|
@@ -159,7 +159,7 @@ var endpointCallCommand = lazy(() => import("./cli-JHLWBRXB.js"), "endpointCallC
|
|
|
159
159
|
var endpointListCommand = lazy(() => import("./cli-HGCOEL5T.js"), "endpointListCommand");
|
|
160
160
|
var generateCommand = lazy(() => import("./cli-WZNIW6ZO.js"), "generateCommand");
|
|
161
161
|
var initCommand = lazy(() => import("./cli-GSOV26O5.js"), "initCommand");
|
|
162
|
-
var newCommand = lazy(() => import("./cli-
|
|
162
|
+
var newCommand = lazy(() => import("./cli-XNOAO6DY.js"), "newCommand");
|
|
163
163
|
var packageBundleCommand = lazy(
|
|
164
164
|
() => import("./cli-BQ36DV5C.js"),
|
|
165
165
|
"packageBundleCommand"
|
|
@@ -174,29 +174,29 @@ var packageVersionCommand = lazy(
|
|
|
174
174
|
);
|
|
175
175
|
var patchCommand = lazy(() => import("./cli-KJA6GLZI.js"), "patchCommand");
|
|
176
176
|
var resolveCommand = lazy(() => import("./cli-IKSLPAZN.js"), "resolveCommand");
|
|
177
|
-
var screenshotCommand = lazy(() => import("./cli-
|
|
178
|
-
var clockAdvanceCommand = lazy(() => import("./cli-
|
|
179
|
-
var faultCommand = lazy(() => import("./cli-
|
|
180
|
-
var localeCommand = lazy(() => import("./cli-
|
|
181
|
-
var participantAddCommand = lazy(() => import("./cli-
|
|
182
|
-
var participantJoinCommand = lazy(() => import("./cli-
|
|
183
|
-
var participantMoveCommand = lazy(() => import("./cli-
|
|
177
|
+
var screenshotCommand = lazy(() => import("./cli-S3NHXAJM.js"), "screenshotCommand");
|
|
178
|
+
var clockAdvanceCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "clockAdvanceCommand");
|
|
179
|
+
var faultCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "faultCommand");
|
|
180
|
+
var localeCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "localeCommand");
|
|
181
|
+
var participantAddCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "participantAddCommand");
|
|
182
|
+
var participantJoinCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "participantJoinCommand");
|
|
183
|
+
var participantMoveCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "participantMoveCommand");
|
|
184
184
|
var participantRenameCommand = lazy(
|
|
185
|
-
() => import("./cli-
|
|
185
|
+
() => import("./cli-D3S7NJZ3.js"),
|
|
186
186
|
"participantRenameCommand"
|
|
187
187
|
);
|
|
188
|
-
var playCommand = lazy(() => import("./cli-
|
|
189
|
-
var reconfigureCommand = lazy(() => import("./cli-
|
|
190
|
-
var resetCommand = lazy(() => import("./cli-
|
|
191
|
-
var scenarioCommand = lazy(() => import("./cli-
|
|
192
|
-
var teamAddCommand = lazy(() => import("./cli-
|
|
193
|
-
var teamRemoveCommand = lazy(() => import("./cli-
|
|
194
|
-
var teamRenameCommand = lazy(() => import("./cli-
|
|
195
|
-
var timerCommand = lazy(() => import("./cli-
|
|
196
|
-
var undoCommand = lazy(() => import("./cli-
|
|
197
|
-
var waitingRoomCommand = lazy(() => import("./cli-
|
|
188
|
+
var playCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "playCommand");
|
|
189
|
+
var reconfigureCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "reconfigureCommand");
|
|
190
|
+
var resetCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "resetCommand");
|
|
191
|
+
var scenarioCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "scenarioCommand");
|
|
192
|
+
var teamAddCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "teamAddCommand");
|
|
193
|
+
var teamRemoveCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "teamRemoveCommand");
|
|
194
|
+
var teamRenameCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "teamRenameCommand");
|
|
195
|
+
var timerCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "timerCommand");
|
|
196
|
+
var undoCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "undoCommand");
|
|
197
|
+
var waitingRoomCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "waitingRoomCommand");
|
|
198
198
|
var tickCommand = lazy(() => import("./cli-27Z5T52R.js"), "tickCommand");
|
|
199
|
-
var updateCommand = lazy(() => import("./cli-
|
|
199
|
+
var updateCommand = lazy(() => import("./cli-27TQVLVF.js"), "updateCommand");
|
|
200
200
|
var versionCommand = lazy(() => import("./cli-5M6KDNVX.js"), "versionCommand");
|
|
201
201
|
var viewCommand = lazy(() => import("./cli-MDVC5ZNM.js"), "viewCommand");
|
|
202
202
|
function commandPath(command) {
|
package/dist/client/index.d.ts
CHANGED
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
* ```
|
|
20
20
|
*/
|
|
21
21
|
export type { ContextDeletePath, ContextUpdate, SignatureCallbacks } from '@seriousgaming/sdk';
|
|
22
|
-
export { createTestSession, type TestSession, type TestSessionOptions, type TestSessionSetDataOptions, type TestSessionSetSharedDataOptions, type TestSessionState, type TestSessionTeam, type UntypedContext, } from './test-session';
|
|
22
|
+
export { createTestSession, type LogicErrorLocation, type TestMutationResult, type TestSession, type TestSessionOptions, type TestSessionSetDataOptions, type TestSessionSetSharedDataOptions, type TestSessionState, type TestSessionTeam, type UntypedContext, } from './test-session';
|
|
23
23
|
export { startDevServer, type DevServer, type DevServerOptions } from './dev-server';
|
|
24
24
|
export { buildSurfaces, type BuildSurfacesOptions, type BuiltSurfaces } from './build-surfaces';
|
|
25
25
|
export { createStubServices, stubGenerateText, type TestServices } from './stub-services';
|
|
@@ -62,6 +62,44 @@ export interface TestSessionOptions {
|
|
|
62
62
|
apiHost?: string;
|
|
63
63
|
};
|
|
64
64
|
}
|
|
65
|
+
/**
|
|
66
|
+
* Where game logic threw, read back to the file the author wrote: the resource
|
|
67
|
+
* whose logic it was, the tick and team it ran for, and the source position.
|
|
68
|
+
* `file` is relative to the package root; `line` and `column` are 1-based.
|
|
69
|
+
*/
|
|
70
|
+
export interface LogicErrorLocation {
|
|
71
|
+
resource: {
|
|
72
|
+
type: string;
|
|
73
|
+
identifier: string;
|
|
74
|
+
};
|
|
75
|
+
message: string;
|
|
76
|
+
tick?: number;
|
|
77
|
+
team?: {
|
|
78
|
+
teamId: string;
|
|
79
|
+
index: number;
|
|
80
|
+
};
|
|
81
|
+
file?: string;
|
|
82
|
+
line?: number;
|
|
83
|
+
column?: number;
|
|
84
|
+
}
|
|
85
|
+
/**
|
|
86
|
+
* What a test session answers a mutation with. A refusal that came from logic
|
|
87
|
+
* throwing (a failed tick, a hook, a validator) carries `logicError` beside
|
|
88
|
+
* its outcome, which is what `sdk tick` reports from the command line:
|
|
89
|
+
*
|
|
90
|
+
* ```ts
|
|
91
|
+
* const result = await session.tick();
|
|
92
|
+
* if (!result.ok) {
|
|
93
|
+
* const at = result.logicError;
|
|
94
|
+
* throw new Error(`${result.outcome.kind} at ${at?.file}:${at?.line} (tick ${at?.tick})`);
|
|
95
|
+
* }
|
|
96
|
+
* ```
|
|
97
|
+
*
|
|
98
|
+
* A surface never sees it: the outcome alone is what the runtime tells one.
|
|
99
|
+
*/
|
|
100
|
+
export type TestMutationResult = MutationResult & {
|
|
101
|
+
logicError?: LogicErrorLocation;
|
|
102
|
+
};
|
|
65
103
|
/** A capability context as the projection carries it, before a game's types narrow it. */
|
|
66
104
|
export type UntypedContext = Record<string, Record<string, unknown>>;
|
|
67
105
|
/** One team as {@link TestSession.state} reports it, its context typed. */
|
|
@@ -119,9 +157,9 @@ export interface TestSession<Context = UntypedContext, Shared = UntypedContext>
|
|
|
119
157
|
* `{ ok: true }` or `{ ok: false, outcome }`, and a read answers with its
|
|
120
158
|
* result. A refusal is an answer, not a throw.
|
|
121
159
|
*/
|
|
122
|
-
send(command: MutationCommand): Promise<
|
|
160
|
+
send(command: MutationCommand): Promise<TestMutationResult>;
|
|
123
161
|
send(command: QueryCommand): Promise<QueryResult>;
|
|
124
|
-
send(command: Command): Promise<
|
|
162
|
+
send(command: Command): Promise<TestMutationResult | QueryResult>;
|
|
125
163
|
/** The whole session now: teams, contexts, rosters, the store, the timer. */
|
|
126
164
|
state(): TestSessionState<Context, Shared>;
|
|
127
165
|
/**
|
|
@@ -143,7 +181,7 @@ export interface TestSession<Context = UntypedContext, Shared = UntypedContext>
|
|
|
143
181
|
*/
|
|
144
182
|
tick(options?: {
|
|
145
183
|
team?: number;
|
|
146
|
-
}): Promise<
|
|
184
|
+
}): Promise<TestMutationResult>;
|
|
147
185
|
/**
|
|
148
186
|
* Ask for the next tick as a participant's surface does, so the
|
|
149
187
|
* validators' `RequestTick` gates judge it. Asks as the team's first
|
|
@@ -151,14 +189,14 @@ export interface TestSession<Context = UntypedContext, Shared = UntypedContext>
|
|
|
151
189
|
*/
|
|
152
190
|
requestTick(team: number, options?: {
|
|
153
191
|
participantId?: string;
|
|
154
|
-
}): Promise<
|
|
192
|
+
}): Promise<TestMutationResult>;
|
|
155
193
|
/**
|
|
156
194
|
* Write to one team's context, by stable index. As a participant through
|
|
157
195
|
* `ui` unless `as: 'system'` (see {@link TestSessionSetDataOptions}).
|
|
158
196
|
*/
|
|
159
|
-
setData(team: number, patch: ContextUpdate<Context>, options?: TestSessionSetDataOptions): Promise<
|
|
197
|
+
setData(team: number, patch: ContextUpdate<Context>, options?: TestSessionSetDataOptions): Promise<TestMutationResult>;
|
|
160
198
|
/** Write to the shared store, as the facilitator does. */
|
|
161
|
-
setSharedData(patch: ContextUpdate<Shared>, options?: TestSessionSetSharedDataOptions): Promise<
|
|
199
|
+
setSharedData(patch: ContextUpdate<Shared>, options?: TestSessionSetSharedDataOptions): Promise<TestMutationResult>;
|
|
162
200
|
/**
|
|
163
201
|
* Resolves once everything queued has run, including a tick a timer set
|
|
164
202
|
* off. `advanceClock` already waits; this is for a timer moved by hand.
|
package/dist/client.js
CHANGED
|
@@ -28030,6 +28030,7 @@ import { WebSocketServer } from "ws";
|
|
|
28030
28030
|
|
|
28031
28031
|
// cli/core/listen-with-fallback.ts
|
|
28032
28032
|
import { createServer as createSocket } from "net";
|
|
28033
|
+
var PORT_IN_USE_HINT = "`sdk dev status` says whether a dev server is already running for this package. Pass --port auto to take any free port.";
|
|
28033
28034
|
async function listenWithPortFallback(server, startPort, options = {}) {
|
|
28034
28035
|
const maxAttempts = options.maxAttempts ?? 100;
|
|
28035
28036
|
for (let attempt = 0; attempt < maxAttempts; attempt++) {
|
|
@@ -28043,7 +28044,8 @@ async function listenWithPortFallback(server, startPort, options = {}) {
|
|
|
28043
28044
|
}
|
|
28044
28045
|
throw new CliError(
|
|
28045
28046
|
"PORT_IN_USE",
|
|
28046
|
-
`Could not find available port after ${maxAttempts} attempts
|
|
28047
|
+
`Could not find available port after ${maxAttempts} attempts`,
|
|
28048
|
+
{ hint: PORT_IN_USE_HINT }
|
|
28047
28049
|
);
|
|
28048
28050
|
}
|
|
28049
28051
|
function tryListen(server, port, host) {
|
|
@@ -28081,7 +28083,8 @@ async function findFreePort(startPort, maxAttempts = 100) {
|
|
|
28081
28083
|
}
|
|
28082
28084
|
throw new CliError(
|
|
28083
28085
|
"PORT_IN_USE",
|
|
28084
|
-
`Could not find available port after ${maxAttempts} attempts
|
|
28086
|
+
`Could not find available port after ${maxAttempts} attempts`,
|
|
28087
|
+
{ hint: PORT_IN_USE_HINT }
|
|
28085
28088
|
);
|
|
28086
28089
|
}
|
|
28087
28090
|
var PROBED_ADDRESSES = [void 0, "127.0.0.1", "::1"];
|
|
@@ -33458,6 +33461,16 @@ function distPath(meta, identifier) {
|
|
|
33458
33461
|
return `${meta.pluralDir}/${identifier}`;
|
|
33459
33462
|
}
|
|
33460
33463
|
|
|
33464
|
+
// cli/vite/index.ts
|
|
33465
|
+
var REACT_CONTEXT_PACKAGES = [
|
|
33466
|
+
"react",
|
|
33467
|
+
"react-dom",
|
|
33468
|
+
"@emotion/react",
|
|
33469
|
+
"@emotion/styled",
|
|
33470
|
+
"@seriousgaming/sdk",
|
|
33471
|
+
"@seriousgaming/deck"
|
|
33472
|
+
];
|
|
33473
|
+
|
|
33461
33474
|
// cli/bundling/ui-bundler.ts
|
|
33462
33475
|
async function bundleUserInterface(ui, workingDir, buildDir, type) {
|
|
33463
33476
|
const uiOutputDir = join21(buildDir, distPath(getResourceMeta(type), ui.definition.identifier));
|
|
@@ -33483,7 +33496,7 @@ async function bundleUserInterface(ui, workingDir, buildDir, type) {
|
|
|
33483
33496
|
configFile: false,
|
|
33484
33497
|
plugins: [react2()],
|
|
33485
33498
|
resolve: {
|
|
33486
|
-
dedupe: [
|
|
33499
|
+
dedupe: [...REACT_CONTEXT_PACKAGES]
|
|
33487
33500
|
},
|
|
33488
33501
|
build: {
|
|
33489
33502
|
outDir: uiOutputDir,
|
package/dist/docs/api/index.md
CHANGED
|
@@ -14,8 +14,9 @@ Every type, function, hook and component your game imports, one page per entry p
|
|
|
14
14
|
| [`@seriousgaming/sdk/commands`](./sdk-commands.md) | 3 interfaces, 5 types |
|
|
15
15
|
| [`@seriousgaming/sdk/e2e`](./sdk-e2e.md) | 6 functions, 1 constant, 4 interfaces, 5 types |
|
|
16
16
|
| [`@seriousgaming/deck`](./deck.md) | 16 functions, 5 constants, 15 interfaces, 4 types |
|
|
17
|
-
| [`@seriousgaming/sdk-tools/client`](./sdk-tools-client.md) | 5 functions, 1 class,
|
|
17
|
+
| [`@seriousgaming/sdk-tools/client`](./sdk-tools-client.md) | 5 functions, 1 class, 13 interfaces, 12 types |
|
|
18
18
|
| [`@seriousgaming/sdk-tools/playwright`](./sdk-tools-playwright.md) | 1 function, 3 constants, 2 interfaces, 1 type |
|
|
19
|
+
| [`@seriousgaming/sdk-tools/vite`](./sdk-tools-vite.md) | 1 constant |
|
|
19
20
|
|
|
20
21
|
## Which entry point to import from
|
|
21
22
|
|
|
@@ -27,6 +28,7 @@ Every type, function, hook and component your game imports, one page per entry p
|
|
|
27
28
|
- **`@seriousgaming/sdk/commands`** and **`@seriousgaming/sdk/projection`**: the commands a client may send a session, and the shape of the state it reads back (`sdk view --json` and the dev server's `/api/state`)
|
|
28
29
|
- **`@seriousgaming/sdk-tools/client`**: `createTestSession`, which plays a whole game in-process, `startDevServer`, which starts an isolated dev server for browser tests, and `buildSurfaces`, which builds a game's surfaces for those servers to serve
|
|
29
30
|
- **`@seriousgaming/sdk-tools/playwright`**: the Playwright `test` that starts a dev server for each worker, and the `globalSetup` that builds the surfaces they serve
|
|
31
|
+
- **`@seriousgaming/sdk-tools/vite`**: `REACT_CONTEXT_PACKAGES`, the list a `vite.config.ts` and a `vitest.config.ts` pass to `resolve.dedupe`
|
|
30
32
|
- **`@seriousgaming/deck`**: the slide components and layout primitives a presentation is built from
|
|
31
33
|
|
|
32
34
|
`@seriousgaming/sdk-tools` also exports `/host` and `/runtime`. They are for people building a runtime that hosts games, not for game authors, their shapes may change in a minor release, and they are not documented here.
|
|
@@ -151,6 +151,28 @@ interface DevServerOptions {
|
|
|
151
151
|
}
|
|
152
152
|
```
|
|
153
153
|
|
|
154
|
+
### LogicErrorLocation
|
|
155
|
+
|
|
156
|
+
Where game logic threw, read back to the file the author wrote: the resource whose logic it was, the tick and team it ran for, and the source position. `file` is relative to the package root; `line` and `column` are 1-based.
|
|
157
|
+
|
|
158
|
+
```ts
|
|
159
|
+
interface LogicErrorLocation {
|
|
160
|
+
resource: {
|
|
161
|
+
type: string;
|
|
162
|
+
identifier: string;
|
|
163
|
+
};
|
|
164
|
+
message: string;
|
|
165
|
+
tick?: number;
|
|
166
|
+
team?: {
|
|
167
|
+
teamId: string;
|
|
168
|
+
index: number;
|
|
169
|
+
};
|
|
170
|
+
file?: string;
|
|
171
|
+
line?: number;
|
|
172
|
+
column?: number;
|
|
173
|
+
}
|
|
174
|
+
```
|
|
175
|
+
|
|
154
176
|
### SignatureCallbacks
|
|
155
177
|
|
|
156
178
|
Every callback a runtime may offer logic: the engine, hooks, tick controllers and endpoints.
|
|
@@ -221,30 +243,30 @@ A session to test against.
|
|
|
221
243
|
|
|
222
244
|
```ts
|
|
223
245
|
interface TestSession<Context = UntypedContext, Shared = UntypedContext> {
|
|
224
|
-
send(command: MutationCommand): Promise<
|
|
246
|
+
send(command: MutationCommand): Promise<TestMutationResult>;
|
|
225
247
|
send(command: QueryCommand): Promise<QueryResult>;
|
|
226
|
-
send(command: Command): Promise<
|
|
248
|
+
send(command: Command): Promise<TestMutationResult | QueryResult>;
|
|
227
249
|
state(): TestSessionState<Context, Shared>;
|
|
228
250
|
team(index: number): TestSessionTeam<Context>;
|
|
229
251
|
readonly shared: {
|
|
230
252
|
readonly context: Shared;
|
|
231
253
|
};
|
|
232
|
-
tick(options?: { team?: number }): Promise<
|
|
254
|
+
tick(options?: { team?: number }): Promise<TestMutationResult>;
|
|
233
255
|
requestTick(
|
|
234
256
|
team: number,
|
|
235
257
|
options?: {
|
|
236
258
|
participantId?: string;
|
|
237
259
|
}
|
|
238
|
-
): Promise<
|
|
260
|
+
): Promise<TestMutationResult>;
|
|
239
261
|
setData(
|
|
240
262
|
team: number,
|
|
241
263
|
patch: ContextUpdate<Context>,
|
|
242
264
|
options?: TestSessionSetDataOptions
|
|
243
|
-
): Promise<
|
|
265
|
+
): Promise<TestMutationResult>;
|
|
244
266
|
setSharedData(
|
|
245
267
|
patch: ContextUpdate<Shared>,
|
|
246
268
|
options?: TestSessionSetSharedDataOptions
|
|
247
|
-
): Promise<
|
|
269
|
+
): Promise<TestMutationResult>;
|
|
248
270
|
settled(): Promise<void>;
|
|
249
271
|
close(): Promise<void>;
|
|
250
272
|
}
|
|
@@ -578,6 +600,16 @@ type QueryResult =
|
|
|
578
600
|
};
|
|
579
601
|
```
|
|
580
602
|
|
|
603
|
+
### TestMutationResult
|
|
604
|
+
|
|
605
|
+
What a test session answers a mutation with. A refusal that came from logic throwing (a failed tick, a hook, a validator) carries `logicError` beside its outcome, which is what `sdk tick` reports from the command line:
|
|
606
|
+
|
|
607
|
+
```ts
|
|
608
|
+
type TestMutationResult = MutationResult & {
|
|
609
|
+
logicError?: LogicErrorLocation;
|
|
610
|
+
};
|
|
611
|
+
```
|
|
612
|
+
|
|
581
613
|
### TestServices
|
|
582
614
|
|
|
583
615
|
Where a test session's service callbacks go (`TestSessionOptions.services`).
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
<!-- Generated by `pnpm docs:generate` from the exports of `@seriousgaming/sdk-tools/vite`. Edit those, not this file. -->
|
|
2
|
+
|
|
3
|
+
# `@seriousgaming/sdk-tools/vite`
|
|
4
|
+
|
|
5
|
+
What a game's Vite and Vitest configs need from the SDK.
|
|
6
|
+
|
|
7
|
+
Imported from `@seriousgaming/sdk-tools/vite` by a `vite.config.ts` or a
|
|
8
|
+
`vitest.config.ts`, so it stays free of the CLI and the dev server: a config
|
|
9
|
+
file is loaded on every run.
|
|
10
|
+
|
|
11
|
+
Every export of `@seriousgaming/sdk-tools/vite`, with the declaration it is published with. Anything tagged `@internal` is left out: it ships in the declarations, but is not part of the supported API and may change without a major release. For how the pieces fit together, see the [API reference](./index.md) and the guides it links to.
|
|
12
|
+
|
|
13
|
+
## Constants
|
|
14
|
+
|
|
15
|
+
### REACT_CONTEXT_PACKAGES
|
|
16
|
+
|
|
17
|
+
Every package that holds React context a surface reads, for `resolve.dedupe`.
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
const REACT_CONTEXT_PACKAGES: readonly string[];
|
|
21
|
+
```
|
package/dist/docs/changelog.md
CHANGED
|
@@ -27,10 +27,49 @@ Entries are grouped into: **Breaking Changes**, **Added**, **Changed**,
|
|
|
27
27
|
**Deprecated**, **Removed**, **Fixed** and **Security**. Releases before 1.0
|
|
28
28
|
are in the [0.x changelog](changelog-0.x.md).
|
|
29
29
|
|
|
30
|
+
From 1.11, a release that changed what `sdk new package` writes, a shipped
|
|
31
|
+
`.claude/rules/` file or the agent guidance also has a **Scaffold changes**
|
|
32
|
+
section: one line per file, saying what changed, why, and after `Adopt:`
|
|
33
|
+
whether an existing package should copy the change. Nothing updates a package's
|
|
34
|
+
own copies, so read those lines for every release you cross.
|
|
35
|
+
|
|
30
36
|
---
|
|
31
37
|
|
|
32
38
|
## [Unreleased]
|
|
33
39
|
|
|
40
|
+
## [1.11.0] — 2026-11-11
|
|
41
|
+
|
|
42
|
+
### Added
|
|
43
|
+
|
|
44
|
+
- **`pnpm check` in a new package**: one script that validates the package, typechecks, lints, and runs the unit and engine tests, stopping at the first that fails. It is the package's own script, so add steps to it. The guidance now tells an agent to run it after every change. To add it to an existing package, see [Catch an older package's scaffold up](guides/upgrading.md#111-catch-an-older-packages-scaffold-up)
|
|
45
|
+
- **The lint rules for logic files ship in the SDK.** A package's `.oxlintrc.json` extends `./node_modules/@seriousgaming/sdk-tools/dist/oxlint/logic.json` (also exported as `@seriousgaming/sdk-tools/oxlint/logic.json`), which refuses the globals the production runtime lacks in engine, hook, validator, endpoint and tick controller logic, and exempts tests. A package no longer keeps its own copy of the list, so the list keeps up with the SDK
|
|
46
|
+
- **`REACT_CONTEXT_PACKAGES` from `@seriousgaming/sdk-tools/vite`**: the packages that hold React context, for `resolve.dedupe` in `vite.config.ts` and `vitest.config.ts`. `sdk build` dedupes the same list itself, which now includes `@seriousgaming/sdk` and `@seriousgaming/deck`
|
|
47
|
+
- **An engine test sees where logic threw.** A `createTestSession` result that was refused because logic threw carries `logicError`: the resource, the message, the tick and team, and the `file`, `line` and `column` of the source, as `sdk tick` reports them. It was already there at run time; it is now typed, as `TestMutationResult` and `LogicErrorLocation` from `@seriousgaming/sdk-tools/client`, and documented in [Engine testing](guides/engine-testing.md#ticking-and-asserting)
|
|
48
|
+
- **A hint on three more failures.** `RESOURCE_NOT_FOUND` from `update` names the resources of that type the package holds, `MANIFEST_NOT_FOUND` says where to run the command, and `PORT_IN_USE` points at `sdk dev status` and `--port auto`
|
|
49
|
+
- **The conformance suite carries the specification and the manifest schema it was built from**, in the installed package's `dist/`, so a runtime that pins the suite gets all three at one revision. The specification's changelog now maps each SDK release to the revision it implements. See the suite's README
|
|
50
|
+
|
|
51
|
+
### Changed
|
|
52
|
+
|
|
53
|
+
- **`sdk new package --empty` writes `teams.mode` into the manifest**, as `"independent"`, which is what an absent mode already meant. A game that needs shared state now has the field in front of it to change
|
|
54
|
+
- **The starter game's engine test is typed and plays every scenario.** It passes the engine's generated `Context` to `createTestSession`, so it reads `team.context.results.Day` without a cast, and ends with a test that starts each scenario on disk and plays a day
|
|
55
|
+
|
|
56
|
+
### Fixed
|
|
57
|
+
|
|
58
|
+
- **The guides agree on what leaving a key out does.** A variable logic returns replaces the old one whole, so an entry of a map is gone if the returned map leaves it out. The engine guide and the agent guidance both said it never was. `deletes` is still the way to remove one: it works however the map was built
|
|
59
|
+
- **Every documented `--json` command uses `pnpm run --silent`**, so no pnpm banner precedes the JSON. Two examples did not
|
|
60
|
+
|
|
61
|
+
### Scaffold changes
|
|
62
|
+
|
|
63
|
+
- `package.json`: gains a `check` script that runs `sdk build --validate-only`, `typecheck`, `lint`, `test:run` and `test:engine` in order. It gives an agent one command to run after every change. Adopt: yes, copy the script, and drop its last step if the package has no engine tests
|
|
64
|
+
- `.oxlintrc.json` (`oxlintrc.json.template`): extends `./node_modules/@seriousgaming/sdk-tools/dist/oxlint/logic.json` in place of its own `no-restricted-globals` override and the override that turned it off for tests. The list of globals the production runtime lacks now comes from the installed SDK. Adopt: yes, add the `extends` line and delete the two overrides
|
|
65
|
+
- `vite.config.ts` and `vitest.config.ts`: `resolve.dedupe` is `[...REACT_CONTEXT_PACKAGES]`, imported from `@seriousgaming/sdk-tools/vite`, in place of a written-out list. Adopt: optional, and keep any package of your own after the spread
|
|
66
|
+
- `.oxfmtrc.json` (`oxfmtrc.json.template`): `ignorePatterns` gains `lib/`, `test-results/` and `playwright-report/`, so the formatter stops rewriting build output and test reports. Adopt: yes
|
|
67
|
+
- `.claude/settings.json` (`settings.json.template`): allows `pnpm check` without a prompt, beside the steps it runs. Adopt: yes, add the line
|
|
68
|
+
- `README.md`: lists `pnpm check` under 'Running the tests'. Adopt: no
|
|
69
|
+
- `guidance.md`: the loop is `pnpm check`; `tick --no-server` is a smoke test, since engine tests run in the same restricted runtime; session examples pass `--summary`; `cli-reference.md`, `changelog.md` and `guides/upgrading.md` are never to be read whole; and removing a key is described as it behaves. Adopt: no, it updates with the installed version
|
|
70
|
+
- `.claude/rules/workflow-update-sdk-version.md`: step 7 reads this section of every release crossed, oldest first, and step 6 runs `pnpm check`. Adopt: yes, replace the file, so later upgrades find these lines
|
|
71
|
+
- `.claude/rules/workflow-create-engine.md`, `workflow-create-user-interface.md` and `workflow-test-engine-or-ui.md`: the verify step is `pnpm check`. Adopt: optional
|
|
72
|
+
|
|
34
73
|
## [1.10.0] — 2026-11-07
|
|
35
74
|
|
|
36
75
|
### Added
|
|
@@ -344,7 +344,7 @@ An internal endpoint's request may take any shape. Which outside callers may use
|
|
|
344
344
|
|
|
345
345
|
## When a call fails
|
|
346
346
|
|
|
347
|
-
A failed call is never a bare message, because a caller has to tell a call that changed nothing from one whose writes landed before an action failed. A UI's call rejects with an [`EndpointError`](../api/sdk-ui.md#endpointerror), `pnpm run sdk endpoint call --json` prints the same thing, and a `createTestSession` call answers `{ type: 'endpointFailure', failure }`. Each carries:
|
|
347
|
+
A failed call is never a bare message, because a caller has to tell a call that changed nothing from one whose writes landed before an action failed. A UI's call rejects with an [`EndpointError`](../api/sdk-ui.md#endpointerror), `pnpm run --silent sdk endpoint call --json` prints the same thing, and a `createTestSession` call answers `{ type: 'endpointFailure', failure }`. Each carries:
|
|
348
348
|
|
|
349
349
|
- `outcome`: why, as `outcome.kind` and usually `outcome.message`. The kinds are those of a refused write (`denied`, `conflict`, `tick-failed` and the rest) plus three only an endpoint has: `invalid-request` (the request failed `requestSchema`, so the handler did not run), `handler-error` (the handler threw or overran its time limit), and `invalid-response` (what it returned broke its declaration)
|
|
350
350
|
- `applied`: the steps that committed before the failure, in order: `{ kind: 'capabilities' }`, `{ kind: 'teams', teamId }`, or `{ kind: 'action', index, type }`. Empty when nothing changed
|
|
@@ -116,6 +116,16 @@ it('adds Delta to Total on each tick', async () => {
|
|
|
116
116
|
});
|
|
117
117
|
```
|
|
118
118
|
|
|
119
|
+
When the refusal came from logic that threw, the result also carries `logicError`: the resource whose logic it was, the message, the tick and team it ran for, and the `file`, `line` and `column` of the source, which is what `sdk tick` reports from the command line. Put it in the failure message and a failing test says where to look:
|
|
120
|
+
|
|
121
|
+
```typescript
|
|
122
|
+
const result = await session.tick();
|
|
123
|
+
if (!result.ok) {
|
|
124
|
+
const at = result.logicError;
|
|
125
|
+
throw new Error(`${result.outcome.kind} at ${at?.file}:${at?.line} (tick ${at?.tick})`);
|
|
126
|
+
}
|
|
127
|
+
```
|
|
128
|
+
|
|
119
129
|
Every helper is a command underneath, and `send` takes any command directly: `session.tick()` is `session.send({ type: 'tick' })`.
|
|
120
130
|
|
|
121
131
|
`state()` is the whole session: `session.completedTicks`, `session.complete`, every team with its `context`, `completedTicks` and `participants`, the shared store, the timer and `settings`, every settings resource's resolved values keyed by identifier.
|
|
@@ -278,6 +288,27 @@ await createTestSession({ packagePath: PACKAGE_PATH, scenarioId: null });
|
|
|
278
288
|
|
|
279
289
|
A game that marks a default scenario never runs on none, so `scenarioId: null` is refused for it, naming the default. Pin one of its scenarios instead.
|
|
280
290
|
|
|
291
|
+
### Playing every scenario
|
|
292
|
+
|
|
293
|
+
A scenario overrides settings, and a value the engine cannot work with only shows when the game is played on it. Start every scenario and play a tick, reading the list from disk so a new scenario is covered the day it is added:
|
|
294
|
+
|
|
295
|
+
```typescript
|
|
296
|
+
const scenarios = readdirSync(join(PACKAGE_PATH, 'scenarios'), { withFileTypes: true })
|
|
297
|
+
.filter((entry) => entry.isDirectory())
|
|
298
|
+
.map((entry) => entry.name);
|
|
299
|
+
|
|
300
|
+
it.each(scenarios)('%s starts and plays a tick', async (scenarioId) => {
|
|
301
|
+
const session = await createTestSession<Context>({ packagePath: PACKAGE_PATH, scenarioId });
|
|
302
|
+
try {
|
|
303
|
+
expect(await session.tick()).toMatchObject({ ok: true });
|
|
304
|
+
} finally {
|
|
305
|
+
await session.close();
|
|
306
|
+
}
|
|
307
|
+
});
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
The starter game's `testing/engine/game.engine.test.ts` ends with this test.
|
|
311
|
+
|
|
281
312
|
### The configuration step
|
|
282
313
|
|
|
283
314
|
A game with a `setup` slot starts at its configuration step. `createTestSession` presses Play for you, so a tick has a game to run. Pass `play: false` to test the step itself, then send `updateSettings` (keyed by settings identifier, for example `{ type: 'updateSettings', payload: { engine: { BaseDemand: 200 } } }`) and `play` as the setup screen would. Settings are fixed from Play onwards, so `state().settings` after `play` is what every tick reads.
|
|
@@ -383,6 +414,10 @@ pnpm exec vitest --config vitest.engine.config.ts testing/engine/game.engine.tes
|
|
|
383
414
|
|
|
384
415
|
Engine tests run in milliseconds per test because there are no subprocesses, no HTTP, and no browser startup.
|
|
385
416
|
|
|
417
|
+
They run logic in the same restricted runtime as `sdk tick` and the dev server, which exposes only the ECMAScript intrinsics. A host global the production runtime lacks, such as `structuredClone` or `fetch`, fails an engine test with a `ReferenceError`, where a unit test calling `Run` directly runs in Node and passes.
|
|
418
|
+
|
|
419
|
+
`pnpm check` runs them last, after validating the package, typechecking, linting and the unit tests. Run it after every change.
|
|
420
|
+
|
|
386
421
|
## CI integration
|
|
387
422
|
|
|
388
423
|
Engine tests require nothing beyond Node.js: no dev server, no browser, and no platform API key, because the service callbacks are stubbed unless a test asks for the platform. Add them to your CI pipeline alongside unit tests:
|
|
@@ -418,20 +453,20 @@ Run Playwright tests in a separate job or stage, since they need a browser and t
|
|
|
418
453
|
|
|
419
454
|
### `TestSession`
|
|
420
455
|
|
|
421
|
-
| Member | Returns
|
|
422
|
-
| -------------------------------- |
|
|
423
|
-
| `send(command)` | `Promise<
|
|
424
|
-
| `state()` | `TestSessionState<Context, Shared>`
|
|
425
|
-
| `team(index)` | `TestSessionTeam<Context>`
|
|
426
|
-
| `shared` | `{ context: Shared }`
|
|
427
|
-
| `tick(options?)` | `Promise<
|
|
428
|
-
| `requestTick(team, options?)` | `Promise<
|
|
429
|
-
| `setData(team, patch, options?)` | `Promise<
|
|
430
|
-
| `setSharedData(patch, options?)` | `Promise<
|
|
431
|
-
| `settled()` | `Promise<void>`
|
|
432
|
-
| `close()` | `Promise<void>`
|
|
433
|
-
|
|
434
|
-
`Command`, `MutationCommand`, `QueryCommand`, `QueryResult`, `MutationResult`, `StateProjection`, `TestSessionState`, `TestSessionTeam`, `TestSessionSetDataOptions`, `TestSessionSetSharedDataOptions`, `ContextUpdate`, `ContextDeletePath`, `FakeClock`, `ParticipantCounts`, `TestServices`, `createStubServices` and `stubGenerateText` are exported from the same module.
|
|
456
|
+
| Member | Returns | Description |
|
|
457
|
+
| -------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
|
|
458
|
+
| `send(command)` | `Promise<TestMutationResult>` or `Promise<QueryResult>` | Run a command as the dev server would. A refusal is an answer, not a throw |
|
|
459
|
+
| `state()` | `TestSessionState<Context, Shared>` | The whole session now, each team's context typed |
|
|
460
|
+
| `team(index)` | `TestSessionTeam<Context>` | One team by stable index: `context`, `participants`, `completedTicks` and the rest. Throws for an unknown one |
|
|
461
|
+
| `shared` | `{ context: Shared }` | The shared store now, under `context` as a session surface's `sessionData.shared` holds it |
|
|
462
|
+
| `tick(options?)` | `Promise<TestMutationResult>` | A facilitator's tick. `{ team }` ticks one team in independent mode |
|
|
463
|
+
| `requestTick(team, options?)` | `Promise<TestMutationResult>` | A participant's request, which `RequestTick` gates judge. `{ participantId }` to choose who asks |
|
|
464
|
+
| `setData(team, patch, options?)` | `Promise<TestMutationResult>` | A participant's write through `ui`, or `{ as: 'system' }` for a trusted one. Also `deletes`, `participantId`, `ui` |
|
|
465
|
+
| `setSharedData(patch, options?)` | `Promise<TestMutationResult>` | A write to the shared store. `{ ui }` holds it to that session surface's `writes`; also `deletes` |
|
|
466
|
+
| `settled()` | `Promise<void>` | Resolves once everything queued has run, including a timer's tick |
|
|
467
|
+
| `close()` | `Promise<void>` | Stop the session's timers. Call it in `afterEach` |
|
|
468
|
+
|
|
469
|
+
A `TestMutationResult` is a `MutationResult` that may carry `logicError`, a `LogicErrorLocation`. `Command`, `MutationCommand`, `QueryCommand`, `QueryResult`, `MutationResult`, `TestMutationResult`, `LogicErrorLocation`, `StateProjection`, `TestSessionState`, `TestSessionTeam`, `TestSessionSetDataOptions`, `TestSessionSetSharedDataOptions`, `ContextUpdate`, `ContextDeletePath`, `FakeClock`, `ParticipantCounts`, `TestServices`, `createStubServices` and `stubGenerateText` are exported from the same module.
|
|
435
470
|
|
|
436
471
|
To call one logic function directly instead, with no session, build its arguments with `logicArgs` from `@seriousgaming/sdk/testing` (see [Testing](./testing.md#testing-the-run-function)).
|
|
437
472
|
|
|
@@ -201,7 +201,7 @@ This is not how a UI's `setData` behaves. A UI deep-merges its patch, because it
|
|
|
201
201
|
|
|
202
202
|
### Removing a key
|
|
203
203
|
|
|
204
|
-
A variable you
|
|
204
|
+
A variable you return replaces the old one whole, so an entry of a map is gone only if the map you return leaves it out. The usual way to build that map spreads the old one (`{ ...context.orders.Open, [id]: order }`), which carries every entry forward, the one you meant to remove included. Rather than rebuild the map without it, name the entry in `deletes`:
|
|
205
205
|
|
|
206
206
|
```typescript
|
|
207
207
|
return {
|
|
@@ -305,7 +305,7 @@ Engine logic runs in a **bare V8 isolate**. The runtime provides the ECMAScript
|
|
|
305
305
|
Referencing one throws `ReferenceError` at tick time. Two things protect you:
|
|
306
306
|
|
|
307
307
|
- **The dev server and CLI enforce it.** `sdk dev` and `tick` run your logic in the same restricted environment, so the failure surfaces locally rather than on deploy
|
|
308
|
-
- **Lint catches it before you run anything.** A scaffolded package restricts these globals in `engine/`, `tick_controller/`, `hooks/*/logic/`, `validators/*/logic/` and `endpoints/*/logic/`, so `pnpm run lint` (and your editor) flags the reference with the replacement to use. The UI slots are deliberately out of scope: `ui/`, `session/` and `waiting_room/` run in a browser, where these globals exist
|
|
308
|
+
- **Lint catches it before you run anything.** A scaffolded package restricts these globals in `engine/`, `tick_controller/`, `hooks/*/logic/`, `validators/*/logic/` and `endpoints/*/logic/`, so `pnpm run lint` (and your editor) flags the reference with the replacement to use. The rules ship in the SDK, and the package's `.oxlintrc.json` extends them (`./node_modules/@seriousgaming/sdk-tools/dist/oxlint/logic.json`), so the list keeps up with the runtime. The UI slots are deliberately out of scope: `ui/`, `session/` and `waiting_room/` run in a browser, where these globals exist
|
|
309
309
|
|
|
310
310
|
### What to use instead
|
|
311
311
|
|
|
@@ -412,16 +412,11 @@ setData({}, { deletes: ['pinboard.Notes.p1'] }); // the note's key is gone, not
|
|
|
412
412
|
Two copies of React are loaded: one from your package and one from the `file://` SDK dependency. Add `resolve.dedupe` to your `vitest.config.ts`, with the SDK packages beside React so a second copy of the SDK cannot hide the providers either:
|
|
413
413
|
|
|
414
414
|
```typescript
|
|
415
|
+
import { REACT_CONTEXT_PACKAGES } from '@seriousgaming/sdk-tools/vite';
|
|
416
|
+
|
|
415
417
|
export default defineConfig({
|
|
416
418
|
resolve: {
|
|
417
|
-
dedupe: [
|
|
418
|
-
'react',
|
|
419
|
-
'react-dom',
|
|
420
|
-
'@emotion/react',
|
|
421
|
-
'@emotion/styled',
|
|
422
|
-
'@seriousgaming/sdk',
|
|
423
|
-
'@seriousgaming/deck',
|
|
424
|
-
],
|
|
419
|
+
dedupe: [...REACT_CONTEXT_PACKAGES],
|
|
425
420
|
},
|
|
426
421
|
// ...
|
|
427
422
|
});
|
|
@@ -700,6 +700,21 @@ A host may now offer one join link for the whole session and put each person who
|
|
|
700
700
|
|
|
701
701
|
A game whose teams are interchangeable needs nothing. A test that builds the `game` settings by hand, rather than spreading the generated `defaultSettings`, adds `sessionJoin` to `teams`.
|
|
702
702
|
|
|
703
|
+
### 1.11: catch an older package's scaffold up
|
|
704
|
+
|
|
705
|
+
Nothing here is required. A package made by `sdk new package` at 1.11 has all of it, and from 1.11 each release's changelog lists what changed in the scaffold under **Scaffold changes**, one line per file, so a later upgrade only has to read those lines. An older package copies from `node_modules/@seriousgaming/sdk-tools/dist/templates/package/`, in this order:
|
|
706
|
+
|
|
707
|
+
1. **Replace `playwright.config.ts` first**, if it still names a port. Copy `global-setup.ts.template` to `testing/e2e/global-setup.ts` and replace `playwright.config.ts` from `playwright.config.ts.liquid`: and import `test` and `expect` from `@seriousgaming/sdk-tools/playwright` in each spec. Every worker then starts an isolated dev server on free ports, so two packages, or two checkouts of one, can run their browser tests at once
|
|
708
|
+
2. **Add the `check` script** to `package.json`, from `package.json.liquid`. It validates the package, typechecks, lints, and runs the unit and engine tests, stopping at the first that fails. Drop the `test:engine` step from it if the package has no engine tests
|
|
709
|
+
3. **Add an engine test that plays every scenario**, as [Playing every scenario](./engine-testing.md#playing-every-scenario) shows. Engine tests run logic in the restricted runtime, so this is what catches a scenario the engine cannot play
|
|
710
|
+
4. **Extend the SDK's lint rules for logic** in place of your copy. In `.oxlintrc.json`, add `"extends": ["./node_modules/@seriousgaming/sdk-tools/dist/oxlint/logic.json"]` and delete the override that lists `no-restricted-globals`, and the one that turns it off for tests. The list of globals the production runtime lacks then comes from the installed SDK
|
|
711
|
+
5. **Read the dedupe list from the SDK** in `vite.config.ts` and `vitest.config.ts`: `import { REACT_CONTEXT_PACKAGES } from '@seriousgaming/sdk-tools/vite'` and set `resolve.dedupe` to `[...REACT_CONTEXT_PACKAGES]`, followed by any package of your own that holds React context
|
|
712
|
+
6. **Keep build output out of the formatter.** Add `lib/`, `test-results/` and `playwright-report/` to `ignorePatterns` in `.oxfmtrc.json`
|
|
713
|
+
7. **Write the team mode down.** If `seriousgaming.sdk.json` has no `teams.mode`, add `"teams": { "mode": "independent" }`, which is what it has been running as, or `"shared-state"` if that is what the game needs
|
|
714
|
+
8. **Refresh the upgrade rule itself.** Replace `.claude/rules/workflow-update-sdk-version.md` from `claude/rules/`: the new one reads the **Scaffold changes** sections on every later upgrade
|
|
715
|
+
|
|
716
|
+
A workspace of several games applies each step to every game. The copies stay the game's own, so keep any local edit a template does not have.
|
|
717
|
+
|
|
703
718
|
### Optional: import the SDK's agent guidance in `CLAUDE.md`
|
|
704
719
|
|
|
705
720
|
A new package's `CLAUDE.md` no longer holds a copy of the SDK's guidance. Its first line imports the copy that ships with `@seriousgaming/sdk-tools`, so the guidance always matches the installed version, and the rest of the file is the package's own. An older package keeps the copy it was scaffolded with, which goes stale with every upgrade and, in a package that began as the starter game, describes the lemonade stand after a reskin.
|
package/dist/docs/page-index.md
CHANGED
|
@@ -45,7 +45,7 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
|
|
|
45
45
|
- [`guides/designing-a-game.md`](guides/designing-a-game.md), about 13k characters: A serious game teaches by letting people act and then see what their actions caused.
|
|
46
46
|
- [`guides/designing-screens.md`](guides/designing-screens.md), about 12k characters: What a good simulation screen looks like, whatever the brand: how to decide what a screen should be before you build it, and how to check it afterwards.
|
|
47
47
|
- [`guides/endpoints.md`](guides/endpoints.md), about 29k characters: An endpoint is a named, server-side handler that a caller invokes by identifier: one of the game's own user interfaces, or a caller outside the game, such as a facilitator's AI agent or a platform API, when the endpoint allows it.
|
|
48
|
-
- [`guides/engine-testing.md`](guides/engine-testing.md), about
|
|
48
|
+
- [`guides/engine-testing.md`](guides/engine-testing.md), about 30k characters: Test your whole game in-process: no dev server, no browser, and no LLM API key required, because service callbacks are stubbed by default.
|
|
49
49
|
- [`guides/engine.md`](guides/engine.md), about 33k characters: The engine is the logic that moves your game forward: it sets up the board, then plays one round each tick.
|
|
50
50
|
- [`guides/file-handling.md`](guides/file-handling.md), about 28k characters: Ship files with your game or let participants upload them, then show them in any UI and read them in logic, all through one reference scheme.
|
|
51
51
|
- [`guides/games.md`](guides/games.md), about 7k characters: Shape the game as a whole: how many rounds it runs, how teams form, which languages it speaks, and where participants wait.
|
|
@@ -76,7 +76,7 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
|
|
|
76
76
|
- [`guides/ui-styling.md`](guides/ui-styling.md), about 11k characters: How a game UI handles language, theme, and screen size, and how to customise the Vite build that serves and bundles it.
|
|
77
77
|
- [`guides/ui-ticks.md`](guides/ui-ticks.md), about 15k characters: How a game UI ends a round and shows the time left: requesting a tick, awaiting a write or tick and handling a `MutationError`, and driving a countdown from the tick timer.
|
|
78
78
|
- [`guides/ui.md`](guides/ui.md), about 17k characters: The game UI is what each participant sees and plays: where they read the situation, make decisions, and see what those decisions caused.
|
|
79
|
-
- [`guides/upgrading.md`](guides/upgrading.md), about
|
|
79
|
+
- [`guides/upgrading.md`](guides/upgrading.md), about 71k characters: This guide takes a game package on 0.6 to 1.0, in 13 steps.
|
|
80
80
|
- [`guides/validators.md`](guides/validators.md), about 25k characters: A validator is a read-only gate on what a participant does: a context write before it is applied, and a request for the next tick before it runs.
|
|
81
81
|
- [`guides/waiting-room.md`](guides/waiting-room.md), about 14k characters: 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.
|
|
82
82
|
|
|
@@ -142,8 +142,9 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
|
|
|
142
142
|
- [`api/sdk-e2e.md`](api/sdk-e2e.md), about 11k characters: End-to-end testing helpers for Serious Gaming SDK consumers.
|
|
143
143
|
- [`api/sdk-projection.md`](api/sdk-projection.md), about 5k characters: The one documented shape of a session's observable state.
|
|
144
144
|
- [`api/sdk-testing.md`](api/sdk-testing.md), about 7k characters: Helpers for unit-testing a game's logic without a runtime.
|
|
145
|
-
- [`api/sdk-tools-client.md`](api/sdk-tools-client.md), about
|
|
145
|
+
- [`api/sdk-tools-client.md`](api/sdk-tools-client.md), about 15k characters: Programmatic API for testing a game in-process.
|
|
146
146
|
- [`api/sdk-tools-playwright.md`](api/sdk-tools-playwright.md), about 3k characters: Playwright for a game's browser tests: a dev server for each worker.
|
|
147
|
+
- [`api/sdk-tools-vite.md`](api/sdk-tools-vite.md), under 1k characters: What a game's Vite and Vitest configs need from the SDK.
|
|
147
148
|
- [`api/sdk-ui-testing.md`](api/sdk-ui-testing.md), about 8k characters: Every export of `@seriousgaming/sdk/ui/testing`, with the declaration it is published with.
|
|
148
149
|
- [`api/sdk-ui.md`](api/sdk-ui.md), about 36k characters: Every export of `@seriousgaming/sdk/ui`, with the declaration it is published with.
|
|
149
150
|
- [`api/sdk.md`](api/sdk.md), about 59k characters: Every export of `@seriousgaming/sdk`, with the declaration it is published with.
|