@seriousgaming/sdk-tools 0.0.0-stage → 1.0.0-alpha.2

package/dist/templates/starter-game/hooks/assignproducts/logic/logic.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest';
+
+import type { Callbacks, Settings, Context } from '../types';
+import { Run } from './logic';
+
+const callbacks = {} as Callbacks;
+const settings: Settings = {
+    menu: {
+        Capacity: 120,
+        Menu: {
+            lemonade: { Name: 'Lemonade', Order: 1, Cost: 15, Price: 50 },
+            icedtea: { Name: 'Iced tea', Order: 2, Cost: 20, Price: 60 },
+            cookies: { Name: 'Cookies', Order: 3, Cost: 25, Price: 70 },
+        },
+    },
+};
+
+const empty: Context = { roles: { LooksAfter: {} } };
+
+const join = async (context: Context, id: string, index: number, over: Settings = settings) =>
+    (
+        await Run({
+            participants: [],
+            context,
+            settings: over,
+            callbacks,
+            meta: { locale: 'en', seed: 'lemonade-test-seed', runKind: 'session', now: 0 },
+            participant: {
+                id,
+                teamId: 'team-1',
+                name: `Participant ${index + 1}`,
+                index,
+                connected: true,
+            },
+        })
+    ).capabilities;
+
+describe('Run', () => {
+    it('puts the first arrival on the first thing on the menu', async () => {
+        const result = await join(empty, 'participant-1', 0);
+
+        expect(result.roles.LooksAfter).toEqual({ 'participant-1': 'lemonade' });
+    });
+
+    it('hands the menu out in order, and starts again round a fourth person', async () => {
+        let context = empty;
+        for (const [index, id] of ['a', 'b', 'c', 'd'].entries()) {
+            context = await join(context, id, index);
+        }
+
+        expect(context.roles.LooksAfter).toEqual({
+            a: 'lemonade',
+            b: 'icedtea',
+            c: 'cookies',
+            d: 'lemonade',
+        });
+    });
+
+    it('leaves a returning participant on what they had', async () => {
+        const context: Context = {
+            ...empty,
+            roles: { LooksAfter: { 'participant-1': 'cookies' } },
+        };
+
+        const result = await join(context, 'participant-1', 0);
+
+        expect(result.roles.LooksAfter['participant-1']).toBe('cookies');
+    });
+
+    it('does nothing when the menu is empty', async () => {
+        const result = await join(empty, 'participant-1', 0, {
+            menu: { ...settings.menu, Menu: {} },
+        });
+
+        expect(result.roles.LooksAfter).toEqual({});
+    });
+});

package/dist/templates/starter-game/hooks/assignproducts/logic/logic.ts

@@ -0,0 +1,47 @@
+import type { HookFunction } from '../types';
+
+/**
+ * Puts each arriving participant in charge of one thing on the menu.
+ *
+ * This is what makes the concurrency safe in ordinary play rather than by luck:
+ * three people looking after three different items normally change three
+ * different keys, so the host's merge keeps all three. Nobody is stopped from
+ * changing somebody else's item, and the validator is what covers the day they
+ * do.
+ *
+ * It reads the menu rather than carrying a list of its own, so a fourth item
+ * added to the game is handed out without touching this file.
+ *
+ * Hooks fire out of tick, once per join, and the runtime serialises them, so
+ * reading the map and writing it back is safe here in a way the same pattern
+ * would not be in a surface.
+ */
+export const Run: HookFunction = async ({ context, settings, participant }) => {
+    const assignments = context.roles.LooksAfter;
+
+    // A reconnect re-fires the signal. Re-assigning would move somebody to a
+    // different item mid-session for no reason they could see.
+    if (assignments[participant.id]) {
+        return { capabilities: context };
+    }
+
+    const menu = Object.entries(settings.menu.Menu)
+        .sort(([, a], [, b]) => a.Order - b.Order)
+        .map(([id]) => id);
+
+    if (menu.length === 0) {
+        return { capabilities: context };
+    }
+
+    return {
+        capabilities: {
+            ...context,
+            roles: {
+                LooksAfter: {
+                    ...assignments,
+                    [participant.id]: menu[Object.keys(assignments).length % menu.length],
+                },
+            },
+        },
+    };
+};

package/dist/templates/starter-game/hooks/assignproducts/types.ts

@@ -0,0 +1,55 @@
+// This file is auto-generated from the hook's capability definitions.
+// Do not edit this file directly. It will be regenerated on build.
+
+export interface Context {
+    roles: {
+        /**
+         * Which menu item each participant is in charge of, keyed by participant id. Written by the participantJoin hook, and the reason two people normally edit two different keys.
+         */
+        LooksAfter: {
+            [k: string]: string;
+        };
+    };
+}
+
+export interface Settings {
+    menu: {
+        /**
+         * How many items the stall can make in a day, across the whole menu
+         */
+        Capacity: number;
+        Menu: Menu;
+    };
+}
+/**
+ * What the stall sells, keyed by item id. Money is in pence, so the sums stay in whole numbers. Read by the engine and every surface, so the price on screen and the price in the sums are the same number.
+ */
+export interface Menu {
+    [k: string]: MenuItem;
+}
+export interface MenuItem {
+    /**
+     * What the item is called on every screen
+     */
+    Name: string;
+    /**
+     * Where it sits on the menu, so every screen lists it in the same order. 1 comes first
+     */
+    Order: number;
+    /**
+     * Cost to make one, in pence
+     */
+    Cost: number;
+    /**
+     * Sale price, in pence
+     */
+    Price: number;
+}
+
+import type { LogicCallbacks } from '@seriousgaming/sdk';
+
+export type Callbacks = LogicCallbacks;
+
+import type { HookFunction as SDKHookFunction } from '@seriousgaming/sdk';
+
+export type HookFunction = SDKHookFunction<'participantJoin', Context, Settings, Callbacks>;

package/dist/templates/starter-game/package.json

@@ -0,0 +1,68 @@
+{
+    "name": "com.example.lemonade",
+    "version": "0.0.0",
+    "private": true,
+    "description": "The scaffolded starter game, kept as a worked example",
+    "license": "UNLICENSED",
+    "author": "Serious Gaming",
+    "files": [
+        "dist"
+    ],
+    "type": "module",
+    "main": "index.js",
+    "scripts": {
+        "generate": "pnpm run sdk generate",
+        "build": "pnpm run sdk build",
+        "start": "pnpm run sdk dev",
+        "test": "vitest",
+        "test:run": "vitest run",
+        "test:coverage": "vitest run --coverage",
+        "test:engine": "vitest run --config vitest.engine.config.ts",
+        "lint": "oxlint --max-warnings=0",
+        "lint:fix": "oxlint --fix",
+        "format": "oxfmt",
+        "format:check": "oxfmt --check",
+        "typecheck": "tsc --noEmit",
+        "sdk": "vite-node node_modules/@seriousgaming/sdk-tools/cli/cli.ts",
+        "test:e2e": "playwright test"
+    },
+    "dependencies": {
+        "@emotion/cache": "^11.14.0",
+        "@emotion/react": "^11.14.0",
+        "@emotion/styled": "^11.14.1",
+        "@fontsource-variable/roboto-mono": "^5.3.0",
+        "@fontsource-variable/work-sans": "^5.3.0",
+        "@mui/material": "^9.4.0",
+        "@mui/stylis-plugin-rtl": "^9.4.0",
+        "i18next": "^26.4.2",
+        "react": "^19.3.0",
+        "react-dom": "^19.3.0",
+        "react-i18next": "^17.0.16",
+        "stylis": "^4.4.0",
+        "vite": "^8.3.4"
+    },
+    "devDependencies": {
+        "@playwright/test": "^1.64.0",
+        "@seriousgaming/sdk": "workspace:*",
+        "@seriousgaming/sdk-tools": "workspace:*",
+        "@testing-library/jest-dom": "^7.0.1",
+        "@testing-library/react": "^16.3.3",
+        "@testing-library/user-event": "^14.6.7",
+        "@types/node": "^24.19.1",
+        "@types/react": "^19.3.0",
+        "@types/react-dom": "^19.3.0",
+        "@types/stylis": "^4.2.7",
+        "@vitejs/plugin-react": "^6.1.2",
+        "commander": "^15.0.0",
+        "esbuild": "^0.28.2",
+        "jsdom": "^30.1.2",
+        "json-schema-to-typescript": "^16.0.0",
+        "typescript": "^6.0.3",
+        "vite-node": "^6.0.0",
+        "vitest": "^5.0.3"
+    },
+    "peerDependencies": {
+        "@seriousgaming/sdk": "workspace:*"
+    },
+    "sdkResources": "./dist/seriousgaming.json"
+}

package/dist/templates/starter-game/playwright.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+    testDir: './testing/e2e',
+    // Starts an isolated dev server on free ports, beside any `sdk dev` you
+    // have running, and stops it when the run ends. It names the server in
+    // SERIOUSGAMING_DEV_URL, which the SDK's e2e helpers read.
+    globalSetup: './testing/e2e/global-setup.ts',
+    // One worker: these tests share a session, so a tick in one is visible to
+    // the next. Running them in parallel makes each test's starting state
+    // depend on what another happened to be doing.
+    workers: 1,
+    // A stray `test.only` passes locally and silently skips the rest on CI.
+    forbidOnly: !!process.env.CI,
+    use: {
+        // Read again in each worker, after the global setup has set it.
+        baseURL: process.env.SERIOUSGAMING_DEV_URL,
+    },
+});

package/dist/templates/starter-game/scenarios/heatwave/scenario.sdk.json

@@ -0,0 +1,20 @@
+{
+    "definition": {
+        "locales": {
+            "en": {
+                "name": "Heatwave",
+                "description": "Five hot days. The queue is longer than the stall can serve, so the only question is what to fill it with."
+            }
+        },
+        "settings": {
+            "game": {
+                "maxTicks": 5
+            },
+            "engine": {
+                "SunnyPull": 1.9,
+                "RainyPull": 1.1
+            }
+        }
+    },
+    "rootDirectory": "."
+}

package/dist/templates/starter-game/scenarios/ordinary_week/scenario.sdk.json

@@ -0,0 +1,12 @@
+{
+    "definition": {
+        "locales": {
+            "en": {
+                "name": "An ordinary week",
+                "description": "Ten days of mixed weather. The one to run first."
+            }
+        },
+        "default": true
+    },
+    "rootDirectory": "."
+}

package/dist/templates/starter-game/seriousgaming.sdk.json

@@ -0,0 +1,23 @@
+{
+    "identifier": "com.example.lemonade",
+    "supportedLocales": ["en"],
+    "locales": {
+        "en": {
+            "name": "Lemonade Stand"
+        }
+    },
+    "maxTicks": 10,
+    "teams": {
+        "mode": "independent",
+        "min": 1,
+        "max": 8,
+        "perTeam": {
+            "minParticipants": 2,
+            "maxParticipants": 5
+        }
+    },
+    "waitingRoom": {
+        "openOnStart": true
+    },
+    "scenarioFormat": 1
+}

package/dist/templates/starter-game/session/defaults.ts

@@ -0,0 +1,80 @@
+// This file is auto-generated from the schemas the resource declares: the values
+// a session starts with, for use as test fixtures.
+// Do not edit this file directly. It will be regenerated on build.
+
+import type { Context, TeamContext, SharedContext, Settings } from './types';
+
+export const defaultContext: Context = {
+    plan: {
+        Make: {},
+    },
+    results: {
+        Day: 0,
+        Weather: 'sunny',
+        Lines: {},
+        Takings: 0,
+        Spent: 0,
+        Profit: 0,
+        Purse: 0,
+    },
+    roles: {
+        LooksAfter: {},
+    },
+    briefing: {
+        Message: '',
+    },
+};
+
+export const defaultTeamContext: TeamContext = {
+    plan: {
+        Make: {},
+    },
+    results: {
+        Day: 0,
+        Weather: 'sunny',
+        Lines: {},
+        Takings: 0,
+        Spent: 0,
+        Profit: 0,
+        Purse: 0,
+    },
+    roles: {
+        LooksAfter: {},
+    },
+};
+
+export const defaultSharedContext: SharedContext = {
+    briefing: {
+        Message: '',
+    },
+};
+
+export const defaultSettings: Settings = {
+    menu: {
+        Capacity: 120,
+        Menu: {
+            lemonade: {
+                Name: 'Lemonade',
+                Order: 1,
+                Cost: 15,
+                Price: 50,
+            },
+            icedtea: {
+                Name: 'Iced tea',
+                Order: 2,
+                Cost: 20,
+                Price: 60,
+            },
+            cookies: {
+                Name: 'Cookies',
+                Order: 3,
+                Cost: 25,
+                Price: 70,
+            },
+        },
+    },
+    session: {
+        ShowJoinLinks: true,
+        CurrencySymbol: '£',
+    },
+};

package/dist/templates/starter-game/session/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>Allocation</title>
+    </head>
+    <body>
+        <div id="root"></div>
+        <script type="module" src="./src/main.tsx"></script>
+    </body>
+</html>

package/dist/templates/starter-game/session/session.sdk.json

@@ -0,0 +1,11 @@
+{
+    "definition": {
+        "reads": ["plan", "results", "roles", "briefing"],
+        "writes": ["briefing"],
+        "settings": ["menu", "session"]
+    },
+    "ui": {
+        "entrypoint": "index.html"
+    },
+    "rootDirectory": "."
+}