@seriousgaming/sdk-tools 1.0.0-alpha.3 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -5
- package/dist/cli.js +30 -12
- package/dist/client/index.d.ts +2 -2
- package/dist/client/test-session.d.ts +12 -15
- package/dist/client.js +20 -11
- package/dist/docs/api/index.md +1 -1
- package/dist/docs/api/sdk-tools-client.md +40 -32
- package/dist/docs/api/sdk-ui-testing.md +4 -4
- package/dist/docs/api/sdk-ui.md +80 -20
- package/dist/docs/api/sdk.md +37 -21
- package/dist/docs/changelog.md +119 -74
- package/dist/docs/cli-and-dev-server.md +16 -15
- package/dist/docs/concepts/index.md +1 -1
- package/dist/docs/concepts/terminology.md +6 -6
- package/dist/docs/getting-started.md +4 -2
- package/dist/docs/guides/engine-testing.md +1 -1
- package/dist/docs/guides/engine.md +13 -0
- package/dist/docs/guides/file-handling.md +4 -4
- package/dist/docs/guides/internationalization.md +15 -1
- package/dist/docs/guides/llm-integration.md +2 -0
- package/dist/docs/guides/patterns.md +33 -5
- package/dist/docs/guides/presentation.md +9 -9
- package/dist/docs/guides/session.md +22 -19
- package/dist/docs/guides/testing.md +1 -1
- package/dist/docs/guides/tick-controller.md +5 -3
- package/dist/docs/guides/ui.md +5 -1
- package/dist/docs/guides/upgrading.md +40 -5
- package/dist/docs/recipes/create-endpoint.md +1 -1
- package/dist/docs/recipes/start-from-an-empty-package.md +6 -7
- package/dist/docs/recipes/use-request-tick.md +1 -1
- package/dist/docs/troubleshooting.md +6 -4
- package/dist/schema.json +6 -6
- package/dist/templates/endpoint/logic.test.ts.liquid +35 -48
- package/dist/templates/engine/logic-aggregate.test.ts.liquid +34 -53
- package/dist/templates/engine/logic.test.ts.liquid +22 -34
- package/dist/templates/hook/logic.test.ts.liquid +28 -32
- package/dist/templates/package/CLAUDE.md.template +1 -1
- package/dist/templates/package/README.md.liquid +3 -3
- package/dist/templates/package/claude/rules/workflow-create-capability.md +1 -1
- package/dist/templates/package/claude/rules/workflow-create-endpoint.md +1 -1
- package/dist/templates/presentation/src/App.tsx.liquid +1 -1
- package/dist/templates/session/src/main.tsx.liquid +3 -3
- package/dist/templates/settings-editor/src/main.tsx.liquid +3 -3
- package/dist/templates/starter-game/engine/logic.test.ts +37 -47
- package/dist/templates/starter-game/engine/test-helpers.ts +13 -65
- package/dist/templates/starter-game/hooks/assignproducts/logic/logic.test.ts +24 -30
- package/dist/templates/starter-game/session/src/main.tsx +3 -3
- package/dist/templates/starter-game/ui/src/main.tsx +3 -3
- package/dist/templates/starter-game/validators/capacity/logic/logic.test.ts +12 -35
- package/dist/templates/starter-game/waiting_room/src/main.tsx +3 -3
- package/dist/templates/ui/src/App.test.tsx.liquid +2 -2
- package/dist/templates/ui/src/App.tsx.liquid +22 -11
- package/dist/templates/ui/src/i18n.ts.liquid +3 -0
- package/dist/templates/ui/src/main.tsx.liquid +3 -3
- package/dist/templates/validator/logic.test.ts.liquid +21 -30
- package/dist/templates/waiting-room/src/App.test.tsx.liquid +2 -2
- package/dist/templates/waiting-room/src/main.tsx.liquid +3 -3
- package/package.json +3 -3
|
@@ -1,58 +1,45 @@
|
|
|
1
|
+
import { logicArgs } from '@seriousgaming/sdk/testing';
|
|
1
2
|
import { describe, it, expect } from 'vitest';
|
|
3
|
+
|
|
4
|
+
import { defaultContext{% if hasSettings %}, defaultSettings{% endif %} } from '../defaults';
|
|
5
|
+
import type { Request } from '../types';
|
|
2
6
|
import { Handle } from './logic';
|
|
3
|
-
import type { Request, Response, Context, Callbacks } from '../types';
|
|
4
|
-
import type { EndpointCaller, EndpointSession, {% unless sessionScoped %}TeamInfo, {% endunless %}LogicMeta } from '@seriousgaming/sdk';
|
|
5
7
|
|
|
6
|
-
|
|
7
|
-
//
|
|
8
|
-
// the
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
//
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
// A participant's own team; a facilitator's or external call carries none.
|
|
24
|
-
teamId: 'team-1',
|
|
25
|
-
role: 'participant',
|
|
26
|
-
userInterfaceIdentifier: '{{ identifier }}',
|
|
27
|
-
};
|
|
28
|
-
{% unless sessionScoped %}// The team the call runs for, which the runtime always supplies on team scope.
|
|
29
|
-
const team: TeamInfo = { teamId: 'team-1', index: 0, name: 'Team 1' };
|
|
30
|
-
{% endunless %}
|
|
8
|
+
{% if hasSettings -%}
|
|
9
|
+
// `defaultContext` and `defaultSettings` are generated beside the types, from
|
|
10
|
+
// the very schemas they satisfy: the values a session opens with. Spread them
|
|
11
|
+
// and name only what the case is about.
|
|
12
|
+
{% else -%}
|
|
13
|
+
// `defaultContext` is generated beside the types, from the very schemas it
|
|
14
|
+
// satisfies: the values a session opens with. Spread it and name only what the
|
|
15
|
+
// case is about. Once the endpoint lists settings resources in `settings`,
|
|
16
|
+
// `defaultSettings` is generated beside it: pass `settings: { ...defaultSettings }`.
|
|
17
|
+
{% endif -%}
|
|
18
|
+
//
|
|
19
|
+
// `logicArgs.endpoint` fills everything else the runtime would supply: `meta`
|
|
20
|
+
// (a fixed locale, seed and clock), the roster, offline callback stubs, a
|
|
21
|
+
// session summary, the caller (a participant on `team-1`, through `ui`) and,
|
|
22
|
+
// on team scope, the team the call runs for. Name any of them to override it,
|
|
23
|
+
// for example `caller: { role: 'facilitator' }`.
|
|
24
|
+
|
|
31
25
|
describe('{{ identifier }}', () => {
|
|
32
26
|
describe('Handle', () => {
|
|
33
27
|
it('returns a valid response', async () => {
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
} as Request;
|
|
37
|
-
const context: Context = {
|
|
38
|
-
// TODO: populate context based on declared reads
|
|
39
|
-
} as Context;
|
|
40
|
-
|
|
41
|
-
// The settings resources this endpoint lists in `settings`, keyed by
|
|
42
|
-
// identifier. Empty until it lists some.
|
|
43
|
-
const settings = {} as Parameters<typeof Handle>[0]['settings'];
|
|
28
|
+
// TODO: populate the request fields from requestSchema, then drop the
|
|
29
|
+
// `as Request`, which is only here so the scaffold compiles before then
|
|
30
|
+
const request = {} as Request;
|
|
44
31
|
|
|
45
|
-
const result = await Handle(
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
{
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
32
|
+
const result = await Handle(
|
|
33
|
+
logicArgs.endpoint({
|
|
34
|
+
request,
|
|
35
|
+
// TODO: override the capabilities this case is about
|
|
36
|
+
context: { ...defaultContext },
|
|
37
|
+
{%- if hasSettings %}
|
|
38
|
+
// TODO: override the settings this case is about
|
|
39
|
+
settings: { ...defaultSettings },
|
|
40
|
+
{%- endif %}
|
|
41
|
+
})
|
|
42
|
+
);
|
|
56
43
|
|
|
57
44
|
// TODO: assert result matches responseSchema
|
|
58
45
|
expect(result).toBeDefined();
|
|
@@ -1,28 +1,8 @@
|
|
|
1
|
+
import { logicArgs } from '@seriousgaming/sdk/testing';
|
|
1
2
|
import { describe, it, expect } from 'vitest';
|
|
2
|
-
|
|
3
|
+
|
|
3
4
|
import { defaultSettings, defaultContext, defaultSharedContext, defaultTeamContext } from './defaults';
|
|
4
5
|
import { Init, InitAggregate, RunAggregate } from './logic';
|
|
5
|
-
import type { Context, Settings, Callbacks, TeamContext } from './types';
|
|
6
|
-
|
|
7
|
-
// `teamId` and `index` name the team whose context a per-team call receives,
|
|
8
|
-
// `seed` is the session's random seed (a fixed one here keeps an assertion on
|
|
9
|
-
// derived randomness stable), `runKind` says whether this is the game being
|
|
10
|
-
// played or a walkthrough beside it, and `now` is when the operation started
|
|
11
|
-
// (fixed here, as `seed` is, so a test asserting on it is stable). All of them come from the runtime in a
|
|
12
|
-
// real session, so a test has to state them.
|
|
13
|
-
const meta: TeamRunMeta = {
|
|
14
|
-
tick: 0,
|
|
15
|
-
locale: 'en',
|
|
16
|
-
teamId: 'team-1',
|
|
17
|
-
index: 0,
|
|
18
|
-
seed: 'test-seed',
|
|
19
|
-
runKind: 'session',
|
|
20
|
-
now: Date.UTC(2026, 0, 1),
|
|
21
|
-
};
|
|
22
|
-
// The participants on the team, taken when the operation started. Empty here;
|
|
23
|
-
// add records to test logic that reads the roster.
|
|
24
|
-
const participants: Participant[] = [];
|
|
25
|
-
const callbacks = {} as Callbacks;
|
|
26
6
|
|
|
27
7
|
// `defaultContext` and `defaultSettings` are generated beside the types, from
|
|
28
8
|
// the very schemas they satisfy: the values a session opens with. Spread
|
|
@@ -31,17 +11,23 @@ const callbacks = {} as Callbacks;
|
|
|
31
11
|
// aggregate function receives them split: the shared store once, and each
|
|
32
12
|
// team's own capabilities, so its fixtures use `defaultSharedContext` and
|
|
33
13
|
// `defaultTeamContext`.
|
|
34
|
-
|
|
14
|
+
//
|
|
15
|
+
// `logicArgs` fills everything else the runtime would supply: `meta` (tick 0
|
|
16
|
+
// for `init` and 1 for the rest, a fixed seed and clock), the roster and
|
|
17
|
+
// offline callback stubs. Name any of them to override it, for example
|
|
18
|
+
// `meta: { tick: 3 }`. A team's `teamId` follows its `index`.
|
|
35
19
|
|
|
36
20
|
describe('{{ identifier }}', () => {
|
|
37
21
|
describe('Init', () => {
|
|
38
22
|
it('should initialize each team context', async () => {
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
23
|
+
const { capabilities } = await Init(
|
|
24
|
+
logicArgs.init({
|
|
25
|
+
// TODO: override the capabilities this case is about
|
|
26
|
+
context: { ...defaultContext },
|
|
27
|
+
// TODO: override the settings this case is about
|
|
28
|
+
settings: { ...defaultSettings },
|
|
29
|
+
})
|
|
30
|
+
);
|
|
45
31
|
|
|
46
32
|
// TODO: Add assertions for initialized values
|
|
47
33
|
expect(capabilities).toBeDefined();
|
|
@@ -50,41 +36,36 @@ describe('{{ identifier }}', () => {
|
|
|
50
36
|
|
|
51
37
|
describe('InitAggregate', () => {
|
|
52
38
|
it('should seed shared state across all teams', async () => {
|
|
53
|
-
const
|
|
54
|
-
{
|
|
55
|
-
|
|
56
|
-
index: 0,
|
|
39
|
+
const result = await InitAggregate(
|
|
40
|
+
logicArgs.aggregate({
|
|
41
|
+
shared: { context: { ...defaultSharedContext } },
|
|
57
42
|
// TODO: override the capabilities this case is about
|
|
58
|
-
context: { ...defaultTeamContext }
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
const result = await InitAggregate({ shared, teams, settings, meta, participants, callbacks });
|
|
43
|
+
teams: [{ index: 0, context: { ...defaultTeamContext } }],
|
|
44
|
+
// TODO: override the settings this case is about
|
|
45
|
+
settings: { ...defaultSettings },
|
|
46
|
+
meta: { tick: 0 },
|
|
47
|
+
})
|
|
48
|
+
);
|
|
65
49
|
|
|
66
50
|
// TODO: Add assertions for shared and per-team values
|
|
67
|
-
expect(result.teams).toHaveLength(
|
|
51
|
+
expect(result.teams).toHaveLength(1);
|
|
68
52
|
});
|
|
69
53
|
});
|
|
70
54
|
|
|
71
55
|
describe('RunAggregate', () => {
|
|
72
56
|
it('should update shared state on each tick', async () => {
|
|
73
|
-
const
|
|
74
|
-
{
|
|
75
|
-
|
|
76
|
-
index: 0,
|
|
57
|
+
const result = await RunAggregate(
|
|
58
|
+
logicArgs.aggregate({
|
|
59
|
+
shared: { context: { ...defaultSharedContext } },
|
|
77
60
|
// TODO: override the capabilities this case is about
|
|
78
|
-
context: { ...defaultTeamContext }
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
const result = await RunAggregate({ shared, teams, settings, meta, participants, callbacks });
|
|
61
|
+
teams: [{ index: 0, context: { ...defaultTeamContext } }],
|
|
62
|
+
// TODO: override the settings this case is about
|
|
63
|
+
settings: { ...defaultSettings },
|
|
64
|
+
})
|
|
65
|
+
);
|
|
85
66
|
|
|
86
67
|
// TODO: Add assertions for shared and per-team values
|
|
87
|
-
expect(result.teams).toHaveLength(
|
|
68
|
+
expect(result.teams).toHaveLength(1);
|
|
88
69
|
});
|
|
89
70
|
});
|
|
90
71
|
});
|
|
@@ -1,44 +1,30 @@
|
|
|
1
|
-
import
|
|
1
|
+
import { logicArgs } from '@seriousgaming/sdk/testing';
|
|
2
2
|
import { describe, it, expect } from 'vitest';
|
|
3
3
|
|
|
4
4
|
import { defaultSettings, defaultContext } from './defaults';
|
|
5
5
|
import { Init, Run } from './logic';
|
|
6
|
-
import type { Context, Settings, Callbacks } from './types';
|
|
7
|
-
|
|
8
|
-
// `teamId` and `index` name the team whose context a per-team call receives,
|
|
9
|
-
// `seed` is the session's random seed (a fixed one here keeps an assertion on
|
|
10
|
-
// derived randomness stable), `runKind` says whether this is the game being
|
|
11
|
-
// played or a walkthrough beside it, and `now` is when the operation started
|
|
12
|
-
// (fixed here, as `seed` is, so a test asserting on it is stable). All of them come from the runtime in a
|
|
13
|
-
// real session, so a test has to state them.
|
|
14
|
-
const meta: TeamRunMeta = {
|
|
15
|
-
tick: 0,
|
|
16
|
-
locale: 'en',
|
|
17
|
-
teamId: 'team-1',
|
|
18
|
-
index: 0,
|
|
19
|
-
seed: 'test-seed',
|
|
20
|
-
runKind: 'session',
|
|
21
|
-
now: Date.UTC(2026, 0, 1),
|
|
22
|
-
};
|
|
23
|
-
// The participants on the team, taken when the operation started. Empty here;
|
|
24
|
-
// add records to test logic that reads the roster.
|
|
25
|
-
const participants: Participant[] = [];
|
|
26
|
-
const callbacks = {} as Callbacks;
|
|
27
6
|
|
|
28
7
|
// `defaultContext` and `defaultSettings` are generated beside the types, from
|
|
29
8
|
// the very schemas they satisfy: the values a session opens with. Spread
|
|
30
9
|
// them and name only what the case is about, and a capability added later
|
|
31
10
|
// arrives here already populated rather than breaking every fixture.
|
|
11
|
+
//
|
|
12
|
+
// `logicArgs` fills everything else the runtime would supply: `meta` (tick 0
|
|
13
|
+
// for `init` and 1 for `run`, team `team-1`, a fixed seed and clock), the
|
|
14
|
+
// roster and offline callback stubs. Name any of them to override it, for
|
|
15
|
+
// example `meta: { tick: 3 }`.
|
|
32
16
|
|
|
33
17
|
describe('{{ identifier }}', () => {
|
|
34
18
|
describe('Init', () => {
|
|
35
19
|
it('should initialize context variables', async () => {
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
20
|
+
const { capabilities } = await Init(
|
|
21
|
+
logicArgs.init({
|
|
22
|
+
// TODO: override the capabilities this case is about
|
|
23
|
+
context: { ...defaultContext },
|
|
24
|
+
// TODO: override the settings this case is about
|
|
25
|
+
settings: { ...defaultSettings },
|
|
26
|
+
})
|
|
27
|
+
);
|
|
42
28
|
|
|
43
29
|
// TODO: Add assertions for initialized values
|
|
44
30
|
expect(capabilities).toBeDefined();
|
|
@@ -47,12 +33,14 @@ describe('{{ identifier }}', () => {
|
|
|
47
33
|
|
|
48
34
|
describe('Run', () => {
|
|
49
35
|
it('should update context on each tick', async () => {
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
36
|
+
const { capabilities } = await Run(
|
|
37
|
+
logicArgs.run({
|
|
38
|
+
// TODO: override the capabilities this case is about
|
|
39
|
+
context: { ...defaultContext },
|
|
40
|
+
// TODO: override the settings this case is about
|
|
41
|
+
settings: { ...defaultSettings },
|
|
42
|
+
})
|
|
43
|
+
);
|
|
56
44
|
|
|
57
45
|
// TODO: Add assertions for updated values
|
|
58
46
|
expect(capabilities).toBeDefined();
|
|
@@ -1,43 +1,39 @@
|
|
|
1
|
+
import { logicArgs } from '@seriousgaming/sdk/testing';
|
|
1
2
|
import { describe, it, expect } from 'vitest';
|
|
2
|
-
import { Run } from './logic';
|
|
3
|
-
import type { Context, Settings, Callbacks } from '../types';
|
|
4
|
-
import type { LogicMeta } from '@seriousgaming/sdk';
|
|
5
3
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
// the operation started.
|
|
9
|
-
const meta: LogicMeta = { locale: 'en', seed: 'test-seed', runKind: 'session', now: Date.UTC(2026, 0, 1) };
|
|
4
|
+
import { defaultContext, defaultSettings } from '../defaults';
|
|
5
|
+
import { Run } from './logic';
|
|
10
6
|
|
|
11
|
-
|
|
7
|
+
// `defaultContext` and `defaultSettings` are generated beside the types, from
|
|
8
|
+
// the very schemas they satisfy: the values a session opens with. Spread them
|
|
9
|
+
// and name only what the case is about.
|
|
10
|
+
//
|
|
11
|
+
// `logicArgs.hook` takes the signal's payload and fills the rest the runtime
|
|
12
|
+
// would supply: `meta` (a fixed locale, seed and clock), the roster (the
|
|
13
|
+
// participant the signal concerns) and offline callback stubs.
|
|
12
14
|
|
|
13
|
-
// The participant the signal concerns
|
|
14
|
-
const participant = {
|
|
15
|
-
id: '1',
|
|
16
|
-
teamId: 'team-1',
|
|
17
|
-
name: 'Participant 1',
|
|
18
|
-
index: 0,
|
|
19
|
-
connected: true,
|
|
20
|
-
};
|
|
15
|
+
// The participant the signal concerns.
|
|
16
|
+
const participant = { id: '1', teamId: 'team-1', name: 'Participant 1', index: 0, connected: true };
|
|
21
17
|
|
|
22
18
|
describe('{{ identifier }}', () => {
|
|
23
19
|
describe('Run', () => {
|
|
24
20
|
it('should update context in response to the signal', async () => {
|
|
25
|
-
const
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
21
|
+
const { capabilities } = await Run(
|
|
22
|
+
logicArgs.hook({
|
|
23
|
+
signal: '{{ signal }}',
|
|
24
|
+
// TODO: override the capabilities this case is about
|
|
25
|
+
context: { ...defaultContext },
|
|
26
|
+
// TODO: override the settings this case is about
|
|
27
|
+
settings: { ...defaultSettings },
|
|
28
|
+
participant,
|
|
29
|
+
{%- if signal == 'participantMove' %}
|
|
30
|
+
fromTeamId: 'team-2',
|
|
31
|
+
toTeamId: 'team-1',
|
|
32
|
+
// Which team's context this call owns: 'departure' for the team left
|
|
33
|
+
phase: 'arrival',
|
|
34
|
+
{%- endif %}
|
|
35
|
+
})
|
|
36
|
+
);
|
|
41
37
|
|
|
42
38
|
// TODO: Add assertions for updated values
|
|
43
39
|
expect(capabilities).toBeDefined();
|
|
@@ -139,7 +139,7 @@ pnpm run sdk new capability '{...}' # likewise hook, validator, endpoint,
|
|
|
139
139
|
pnpm run sdk new setup '{...}' # an empty slot: setup, scenario_editor, presentation, tick_controller
|
|
140
140
|
pnpm run sdk update engine --patch '[{"op":"add","path":"/definition/writes/-","value":"results"}]'
|
|
141
141
|
pnpm run sdk update capability plan '{...}' # full replacement
|
|
142
|
-
pnpm run sdk update package --patch '[{"op":"replace","path":"/
|
|
142
|
+
pnpm run sdk update package --patch '[{"op":"replace","path":"/maxTicks","value":12}]'
|
|
143
143
|
pnpm run sdk delete capability plan --yes
|
|
144
144
|
pnpm run generate # regenerate types after a hand edit (new and update already do)
|
|
145
145
|
pnpm run build # validate, generate and bundle into dist/
|
|
@@ -39,9 +39,9 @@ them in. Press the backtick key on any page for the dev drawer: tick, undo, and
|
|
|
39
39
|
reset controls, and the state as JSON.
|
|
40
40
|
|
|
41
41
|
Edits to logic, UIs, `*.sdk.json` bundles and `seriousgaming.sdk.json` reach
|
|
42
|
-
the running game without a restart. A settings change
|
|
43
|
-
|
|
44
|
-
|
|
42
|
+
the running game without a restart. A settings change is the exception once a
|
|
43
|
+
round has been played: settings are fixed when play starts, so it waits for you
|
|
44
|
+
to re-initialise. The console says so and offers a button.
|
|
45
45
|
|
|
46
46
|
### Drive it from the CLI
|
|
47
47
|
|
|
@@ -13,7 +13,7 @@ Capabilities are the data definitions the engine and UIs read from and write to.
|
|
|
13
13
|
```bash
|
|
14
14
|
pnpm run --silent sdk docs view recipes/create-capability.md
|
|
15
15
|
```
|
|
16
|
-
2. **Create the capability** with `pnpm run sdk new capability '{ ... }'`. `definition.identifier` is a short lowercase name (`sales`), which becomes the directory `capabilities/sales/` and the key `context.sales`. The `variablesSchema` must be a full JSON Schema 7 object (`type: 'object'` + `properties` + `required` + `additionalProperties: false`), not a properties-only object.
|
|
16
|
+
2. **Create the capability** with `pnpm run sdk new capability '{ ... }'`. `definition.identifier` is a short lowercase name (`sales`), which becomes the directory `capabilities/sales/` and the key `context.sales`. The `variablesSchema` must be a full JSON Schema 7 object (`type: 'object'` + `properties` + `required` + `additionalProperties: false`), not a properties-only object. `scope` says who sees the value. Leave it out for the default, `team`: one value per team, shown on that team's screens. Set `team-readable` to let other teams' screens observe it too, `shared` for one value across the whole session, or `private` for per-team engine bookkeeping that no screen ever receives. Set `lifetime: "session"` for a value that undo and reset must leave alone, such as a facilitator's announcement; the engine cannot read or write one (see `pnpm run --silent sdk docs view guides/capabilities.md`, 'Lifetime').
|
|
17
17
|
3. **Declare it** in the `reads` or `writes` of every resource that uses it (`pnpm run sdk update engine --patch '[...]'`, and so on). A resource is handed only the capabilities it declares.
|
|
18
18
|
4. **Verify**: `pnpm run build` should pass without type errors. `new` and `update` regenerate types; run `pnpm run generate` yourself only after editing a bundle by hand.
|
|
19
19
|
|
|
@@ -16,7 +16,7 @@ Endpoints are named, server-side handlers that user interfaces (and, when its `v
|
|
|
16
16
|
2. **Decide the request and response shapes.** Each is a full JSON Schema 7 object (`type: 'object'` + `properties` + `required` + `additionalProperties: false`).
|
|
17
17
|
3. **Decide what it touches**: which capabilities it `reads`, which it `writes` (if any), which settings resources it reads (`settings`), which runtime callbacks it `uses` (`generateText`, `extractText`, `generateSpeech`, `writeBlob`), which session `actions` it may return (such as advancing a tick or closing the waiting room), whether its `session` argument needs each team's participants (`roster: true`), and its `scope`: `team` (the default: it acts on the calling team's board) or `session` (for a session UI, setup screen, or scenario editor, which has no team of its own).
|
|
18
18
|
4. **Create the endpoint** with `pnpm run sdk new endpoint '{ ... }'`, declaring `identifier`, `requestSchema`, `responseSchema`, and whichever of `reads`, `writes`, `settings`, `uses`, `actions`, `roster`, `scope`, `visibility`, and `description` apply. An outside caller, such as an AI agent, reads `description` to decide whether to call an external endpoint, so write it for that reader. An external endpoint's `requestSchema` must be `"type": "object"` at the top (`EXTERNAL_REQUEST_NOT_OBJECT`); one taking no input declares an object with no properties.
|
|
19
|
-
5. **Implement `Handle`** in `endpoints/<name>/logic/logic.ts`. It takes `{ request, context, callbacks, caller, settings, meta, session }`, plus `team` (`{ teamId, index, name }`) on a team-scoped endpoint, which is how it identifies its own team. Without `writes` or `actions` it returns the response alone; otherwise it returns `{ response, capabilities, actions }`, where `capabilities` holds only the capabilities it changed and `actions` only those it declared. To remove a key (one entry of a map), add `deletes: [['orders', 'Open', id]]` beside `capabilities`; each path must sit under a capability in `writes`. The generated `Handler` type switches shape to match, so the compiler tells you which one you owe. An endpoint whose response must describe the state its effects leave (for example the tick it just advanced) exports `Plan` and `Respond` instead of `Handle`, typed with the generated `Planner` and `Responder`: `Plan` returns the effects alone, and `Respond` receives `plan` and `outcomes` after they have landed and returns the response.
|
|
19
|
+
5. **Implement `Handle`** in `endpoints/<name>/logic/logic.ts`. It takes `{ request, context, callbacks, caller, settings, meta, participants, session }`, plus `team` (`{ teamId, index, name }`) on a team-scoped endpoint, which is how it identifies its own team, or `teams` (every team's values) on a session-scoped endpoint that declares a capability that is not shared. Without `writes` or `actions` it returns the response alone; otherwise it returns `{ response, capabilities, actions }`, where `capabilities` holds only the capabilities it changed and `actions` only those it declared. To remove a key (one entry of a map), add `deletes: [['orders', 'Open', id]]` beside `capabilities`; each path must sit under a capability in `writes`. The generated `Handler` type switches shape to match, so the compiler tells you which one you owe. An endpoint whose response must describe the state its effects leave (for example the tick it just advanced) exports `Plan` and `Respond` instead of `Handle`, typed with the generated `Planner` and `Responder`: `Plan` returns the effects alone, and `Respond` receives `plan` and `outcomes` after they have landed and returns the response.
|
|
20
20
|
6. **Allow the UI to call it.** Add the endpoint identifier to the `endpoints` array in the bundle of every UI that should be permitted to call it (`pnpm run sdk update ui --patch '[...]'`). Without this, the host rejects the call and TypeScript flags it. The UI then calls `callbacks.endpoints['<name>'](request)`.
|
|
21
21
|
7. **Add a unit test** in the scaffolded `endpoints/<name>/logic/logic.test.ts` covering the happy path and any branch in `Handle`.
|
|
22
22
|
8. **Verify**: `pnpm run sdk endpoint list` shows its scope and whether it writes; `pnpm run --silent sdk endpoint call <name> --no-server --team 1 --request '{...}'` runs it without a UI; then `pnpm run build` and `pnpm test:run`.
|
|
@@ -19,7 +19,7 @@ pick up the same primary and secondary as every other surface.
|
|
|
19
19
|
export default function App() {
|
|
20
20
|
const { game, session, theme, locale } = usePresentation<Settings, TeamContext, SharedContext>();
|
|
21
21
|
const { t, i18n } = useTranslation();
|
|
22
|
-
const language = locale.locale
|
|
22
|
+
const language = locale.locale;
|
|
23
23
|
|
|
24
24
|
useEffect(() => {
|
|
25
25
|
void i18n.changeLanguage(language);
|
|
@@ -28,11 +28,11 @@ function RootWrapper({ children }: { children: React.ReactNode }) {
|
|
|
28
28
|
const { locale } = useSessionUserInterfaceLocale();
|
|
29
29
|
|
|
30
30
|
useEffect(() => {
|
|
31
|
-
|
|
32
|
-
i18n.changeLanguage(
|
|
31
|
+
// The whole tag, so i18next falls back through it: zh-Hant-TW, zh-Hant, zh.
|
|
32
|
+
i18n.changeLanguage(locale);
|
|
33
33
|
}, [locale]);
|
|
34
34
|
|
|
35
|
-
const isRtl = i18n.dir(locale
|
|
35
|
+
const isRtl = i18n.dir(locale) === 'rtl';
|
|
36
36
|
|
|
37
37
|
return <CacheProvider value={isRtl ? cacheRtl : cacheLtr}>{children}</CacheProvider>;
|
|
38
38
|
}
|
|
@@ -28,11 +28,11 @@ function RootWrapper({ children }: { children: React.ReactNode }) {
|
|
|
28
28
|
const { locale } = useSettingsEditorLocale();
|
|
29
29
|
|
|
30
30
|
useEffect(() => {
|
|
31
|
-
|
|
32
|
-
i18n.changeLanguage(
|
|
31
|
+
// The whole tag, so i18next falls back through it: zh-Hant-TW, zh-Hant, zh.
|
|
32
|
+
i18n.changeLanguage(locale);
|
|
33
33
|
}, [locale]);
|
|
34
34
|
|
|
35
|
-
const isRtl = i18n.dir(locale
|
|
35
|
+
const isRtl = i18n.dir(locale) === 'rtl';
|
|
36
36
|
|
|
37
37
|
return <CacheProvider value={isRtl ? cacheRtl : cacheLtr}>{children}</CacheProvider>;
|
|
38
38
|
}
|
|
@@ -1,30 +1,22 @@
|
|
|
1
|
+
import type { TeamRunMeta } from '@seriousgaming/sdk';
|
|
2
|
+
import { logicArgs } from '@seriousgaming/sdk/testing';
|
|
1
3
|
import { describe, expect, it } from 'vitest';
|
|
2
4
|
|
|
5
|
+
import { defaultSettings } from './defaults';
|
|
3
6
|
import { Init, Run } from './logic';
|
|
4
|
-
import {
|
|
7
|
+
import { baseContext } from './test-helpers';
|
|
5
8
|
import type { Context } from './types';
|
|
6
9
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
const run = async (context: Context, day = 1, over: Partial<typeof baseMeta> = {}) =>
|
|
19
|
-
(
|
|
20
|
-
await Run({
|
|
21
|
-
participants: [],
|
|
22
|
-
context,
|
|
23
|
-
settings: baseSettings,
|
|
24
|
-
meta: { ...baseMeta, tick: day, ...over },
|
|
25
|
-
callbacks,
|
|
26
|
-
})
|
|
27
|
-
).capabilities;
|
|
10
|
+
// The seed is fixed (`logicArgs` supplies one), so the weather and the day's
|
|
11
|
+
// custom are the same every run: this game derives both from it rather than
|
|
12
|
+
// drawing them, which is what makes a test like this possible at all.
|
|
13
|
+
const init = async (meta: Partial<TeamRunMeta> = {}) =>
|
|
14
|
+
(await Init(logicArgs.init({ context: baseContext, settings: defaultSettings, meta })))
|
|
15
|
+
.capabilities;
|
|
16
|
+
|
|
17
|
+
const run = async (context: Context, day = 1, meta: Partial<TeamRunMeta> = {}) =>
|
|
18
|
+
(await Run(logicArgs.run({ context, settings: defaultSettings, meta: { tick: day, ...meta } })))
|
|
19
|
+
.capabilities;
|
|
28
20
|
|
|
29
21
|
const makeAll = (context: Context, counts: Record<string, number>): Context => ({
|
|
30
22
|
...context,
|
|
@@ -43,22 +35,21 @@ describe('Init', () => {
|
|
|
43
35
|
it('expects nobody for an item the demand settings say nothing about', async () => {
|
|
44
36
|
// A scenario can add to the menu without touching the engine's
|
|
45
37
|
// settings. The new item still gets a line, just an empty one.
|
|
46
|
-
const { capabilities: result } = await Init(
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
38
|
+
const { capabilities: result } = await Init(
|
|
39
|
+
logicArgs.init({
|
|
40
|
+
context: baseContext,
|
|
41
|
+
settings: {
|
|
42
|
+
...defaultSettings,
|
|
43
|
+
menu: {
|
|
44
|
+
...defaultSettings.menu,
|
|
45
|
+
Menu: {
|
|
46
|
+
...defaultSettings.menu.Menu,
|
|
47
|
+
flapjack: { Name: 'Flapjack', Order: 4, Cost: 20, Price: 80 },
|
|
48
|
+
},
|
|
56
49
|
},
|
|
57
50
|
},
|
|
58
|
-
}
|
|
59
|
-
|
|
60
|
-
callbacks,
|
|
61
|
-
});
|
|
51
|
+
})
|
|
52
|
+
);
|
|
62
53
|
|
|
63
54
|
expect(result.plan.Make.flapjack).toBe(0);
|
|
64
55
|
expect(result.weather.Expected.flapjack).toBe(0);
|
|
@@ -98,16 +89,15 @@ describe('Init', () => {
|
|
|
98
89
|
});
|
|
99
90
|
|
|
100
91
|
it('clears everything a previous session left behind', async () => {
|
|
101
|
-
const { capabilities: result } = await Init(
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
});
|
|
92
|
+
const { capabilities: result } = await Init(
|
|
93
|
+
logicArgs.init({
|
|
94
|
+
context: {
|
|
95
|
+
...baseContext,
|
|
96
|
+
results: { ...baseContext.results, Purse: 9999, Day: 7 },
|
|
97
|
+
},
|
|
98
|
+
settings: defaultSettings,
|
|
99
|
+
})
|
|
100
|
+
);
|
|
111
101
|
|
|
112
102
|
expect(result.results.Purse).toBe(0);
|
|
113
103
|
expect(result.results.Day).toBe(0);
|
|
@@ -153,7 +143,7 @@ describe('Run', () => {
|
|
|
153
143
|
it('takes the sale price for every cup it sells', async () => {
|
|
154
144
|
const result = await run(baseContext);
|
|
155
145
|
const expected = Object.entries(result.results.Lines).reduce(
|
|
156
|
-
(total, [id, line]) => total + line.Sold *
|
|
146
|
+
(total, [id, line]) => total + line.Sold * defaultSettings.menu.Menu[id]!.Price,
|
|
157
147
|
0
|
|
158
148
|
);
|
|
159
149
|
|