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

package/dist/templates/setup/src/App.tsx.liquid

@@ -0,0 +1,102 @@
+import { Box, Button, CssBaseline, GlobalStyles, ThemeProvider, Typography } from '@mui/material';
+import { useSettingsEditor, useSettingsEditorCallbacks } from '@seriousgaming/sdk/ui';
+import React, { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { Settings } from '../types';
+import { useAppTheme } from './theme';
+
+/*
+This UI requires the following dependencies:
+- @mui/material
+- @emotion/react
+- @emotion/styled
+- stylis
+- @mui/stylis-plugin-rtl
+- @fontsource-variable/roboto-mono
+- @fontsource-variable/work-sans
+- i18next
+- react-i18next
+
+Make sure to install them in your project, e.g.:
+pnpm add @mui/material @emotion/react @emotion/styled stylis @mui/stylis-plugin-rtl @fontsource-variable/roboto-mono @fontsource-variable/work-sans i18next react-i18next
+*/
+
+/*
+This is the game's setup screen: a small form the facilitator fills in when
+they create a session. What it changes applies to that session only. It
+includes an example counter that uses local component state. To connect it to
+the game's settings:
+
+1. In setup/setup.sdk.json, list the settings resources this screen edits in
+   `configures`, e.g. "configures": ["demand"]. The settings it reads and
+   writes are keyed by those identifiers.
+
+2. In this file (App.tsx), uncomment the lines related to `useSettingsEditor`.
+*/
+
+/**
+ * This surface is embedded in the host's page, so it leaves the ground to the
+ * host: a surface painting its own background reads as a panel bolted on rather
+ * than part of the page, and never quite matches. Paint cards and panels, which
+ * are meant to look raised, not the page.
+ */
+const TRANSPARENT_BODY = { body: { backgroundColor: 'transparent' } };
+
+const BUTTON_ROW = { display: 'flex', gap: 1 };
+
+function App() {
+    // const { settings, updateSettings } = useSettingsEditor<Settings>();
+    const { requestPlay } = useSettingsEditorCallbacks();
+    const { t } = useTranslation();
+    const theme = useAppTheme();
+    const [localCounter, setLocalCounter] = useState(0);
+
+    // This is a local state example.
+    // To connect to the settings, comment out the local state above and
+    // uncomment the `useSettingsEditor` hook and the `counterValue` line below.
+    const counterValue = localCounter;
+    // const counterValue = settings.demand?.someField;
+
+    const handleIncrement = () => {
+        // This is a local state update example.
+        setLocalCounter((c) => c + 1);
+
+        // To change a setting, uncomment the `updateSettings` call below. Only
+        // what changed reaches the host.
+        // void updateSettings({
+        //     demand: {
+        //         ...settings.demand,
+        //         someField: (settings.demand?.someField ?? 0) + 1,
+        //     },
+        // });
+    };
+
+    return (
+        <ThemeProvider theme={theme}>
+            <CssBaseline enableColorScheme />
+            <GlobalStyles styles={TRANSPARENT_BODY} />
+            <Box>
+                <Typography variant="body1">{t('welcomeMessage')}</Typography>
+                <Typography variant="body2" color="text.secondary">
+                    {t('dataExample')}
+                </Typography>
+                <Typography variant="h6" component="p">
+                    {t('currentValue', { value: counterValue })}
+                </Typography>
+                <Box sx={BUTTON_ROW}>
+                    <Button variant="outlined" onClick={handleIncrement}>
+                        {t('updateButton')}
+                    </Button>
+                    {/* The host always shows its own Play control as well, so
+                        this is a convenience, never the only way out. */}
+                    <Button variant="contained" onClick={() => requestPlay()}>
+                        {t('startButton')}
+                    </Button>
+                </Box>
+            </Box>
+        </ThemeProvider>
+    );
+}
+
+export default App;

package/dist/templates/setup/src/i18n.ts.liquid

@@ -0,0 +1,47 @@
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+
+// Translation resources
+const resources = {
+    en: {
+        translation: {
+            greeting: 'Hello, World!',
+            welcomeMessage: 'Welcome to the setup for this game.',
+            dataExample: 'Choose the settings this session plays with.',
+            currentValue: 'Current value: {% raw %}{{value}}{% endraw %}',
+            updateButton: 'Increment Value',
+            startButton: 'Start',
+        },
+    },
+    it: {
+        translation: {
+            greeting: 'Ciao, mondo!',
+            welcomeMessage: 'Benvenuto nella configurazione di questo gioco.',
+            dataExample: 'Scegli le impostazioni di questa sessione.',
+            currentValue: 'Valore corrente: {% raw %}{{value}}{% endraw %}',
+            updateButton: 'Incrementa valore',
+            startButton: 'Inizia',
+        },
+    },
+    ar: {
+        translation: {
+            greeting: 'أهلاً بالعالم!',
+            welcomeMessage: 'مرحبًا بك في إعداد هذه اللعبة.',
+            dataExample: 'اختر إعدادات هذه الجلسة.',
+            currentValue: 'القيمة الحالية: {% raw %}{{value}}{% endraw %}',
+            updateButton: 'زيادة القيمة',
+            startButton: 'ابدأ',
+        },
+    },
+};
+
+i18n.use(initReactI18next).init({
+    resources,
+    lng: 'en', // default language
+    fallbackLng: 'en',
+    interpolation: {
+        escapeValue: false, // React already escapes
+    },
+});
+
+export default i18n;

package/dist/templates/starter-game/capabilities/briefing/capability.sdk.json

@@ -0,0 +1,18 @@
+{
+    "definition": {
+        "scope": "shared",
+        "lifetime": "session",
+        "variablesSchema": {
+            "type": "object",
+            "properties": {
+                "Message": {
+                    "type": "string",
+                    "description": "Facilitator note shown on every team's screen. Shared scope: one value for the whole session, written only from the session surface. Session lifetime: an undo or a reset leaves it as the facilitator last wrote it.",
+                    "default": ""
+                }
+            },
+            "required": ["Message"],
+            "additionalProperties": false
+        }
+    }
+}

package/dist/templates/starter-game/capabilities/plan/capability.sdk.json

@@ -0,0 +1,17 @@
+{
+    "definition": {
+        "variablesSchema": {
+            "type": "object",
+            "properties": {
+                "Make": {
+                    "type": "object",
+                    "description": "How many of each menu item to make today, keyed by item id. Keyed rather than a flat set of fields so that two people changing two different items write different keys, and the host's merge keeps both.",
+                    "default": {},
+                    "additionalProperties": { "type": "number" }
+                }
+            },
+            "required": ["Make"],
+            "additionalProperties": false
+        }
+    }
+}

package/dist/templates/starter-game/capabilities/results/capability.sdk.json

@@ -0,0 +1,61 @@
+{
+    "definition": {
+        "variablesSchema": {
+            "type": "object",
+            "properties": {
+                "Day": {
+                    "type": "number",
+                    "description": "The day these results are for",
+                    "default": 0
+                },
+                "Weather": {
+                    "type": "string",
+                    "description": "What the weather actually did",
+                    "default": "sunny"
+                },
+                "Lines": {
+                    "type": "object",
+                    "description": "What happened to each menu item, keyed by item id",
+                    "default": {},
+                    "additionalProperties": {
+                        "title": "DayLine",
+                        "type": "object",
+                        "properties": {
+                            "Made": { "type": "number" },
+                            "Wanted": {
+                                "type": "number",
+                                "description": "How many people asked for one"
+                            },
+                            "Sold": { "type": "number" },
+                            "PouredAway": { "type": "number", "description": "Made and not sold" },
+                            "TurnedAway": {
+                                "type": "number",
+                                "description": "Asked for and not available"
+                            }
+                        },
+                        "required": ["Made", "Wanted", "Sold", "PouredAway", "TurnedAway"],
+                        "additionalProperties": false
+                    }
+                },
+                "Takings": { "type": "number", "description": "Money in, in pence", "default": 0 },
+                "Spent": {
+                    "type": "number",
+                    "description": "Cost of everything made, in pence",
+                    "default": 0
+                },
+                "Profit": {
+                    "type": "number",
+                    "description": "Takings less spend, in pence",
+                    "default": 0
+                },
+                "Purse": {
+                    "type": "number",
+                    "description": "Everything made so far, in pence",
+                    "default": 0
+                }
+            },
+            "required": ["Day", "Weather", "Lines", "Takings", "Spent", "Profit", "Purse"],
+            "additionalProperties": false
+        }
+    }
+}

package/dist/templates/starter-game/capabilities/roles/capability.sdk.json

@@ -0,0 +1,17 @@
+{
+    "definition": {
+        "variablesSchema": {
+            "type": "object",
+            "properties": {
+                "LooksAfter": {
+                    "type": "object",
+                    "description": "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.",
+                    "default": {},
+                    "additionalProperties": { "type": "string" }
+                }
+            },
+            "required": ["LooksAfter"],
+            "additionalProperties": false
+        }
+    }
+}

package/dist/templates/starter-game/capabilities/weather/capability.sdk.json

@@ -0,0 +1,23 @@
+{
+    "definition": {
+        "variablesSchema": {
+            "type": "object",
+            "properties": {
+                "Today": {
+                    "type": "string",
+                    "description": "The forecast for the day about to be played",
+                    "default": "sunny",
+                    "enum": ["sunny", "cloudy", "rainy"]
+                },
+                "Expected": {
+                    "type": "object",
+                    "description": "Roughly how many of each item people will want today, keyed by item id. A forecast, not a promise: the day lands somewhere near it.",
+                    "default": {},
+                    "additionalProperties": { "type": "number" }
+                }
+            },
+            "required": ["Today", "Expected"],
+            "additionalProperties": false
+        }
+    }
+}

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

@@ -0,0 +1,81 @@
+// 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: {},
+    },
+    weather: {
+        Today: 'sunny',
+        Expected: {},
+    },
+    results: {
+        Day: 0,
+        Weather: 'sunny',
+        Lines: {},
+        Takings: 0,
+        Spent: 0,
+        Profit: 0,
+        Purse: 0,
+    },
+};
+
+export const defaultTeamContext: TeamContext = {
+    plan: {
+        Make: {},
+    },
+    weather: {
+        Today: 'sunny',
+        Expected: {},
+    },
+    results: {
+        Day: 0,
+        Weather: 'sunny',
+        Lines: {},
+        Takings: 0,
+        Spent: 0,
+        Profit: 0,
+        Purse: 0,
+    },
+};
+
+export const defaultSharedContext: SharedContext = {};
+
+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,
+            },
+        },
+    },
+    engine: {
+        UsualDemand: {
+            lemonade: 55,
+            icedtea: 30,
+            cookies: 20,
+        },
+        SunnyPull: 1.3,
+        RainyPull: 0.65,
+        Variation: 0.2,
+    },
+};

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

@@ -0,0 +1,12 @@
+{
+    "definition": {
+        "reads": ["plan", "weather", "results"],
+        "writes": ["plan", "weather", "results"],
+        "settings": ["menu", "engine"]
+    },
+    "logic": {
+        "directory": ".",
+        "entrypoint": "logic.ts"
+    },
+    "rootDirectory": "."
+}

package/dist/templates/starter-game/engine/logic.test.ts

@@ -0,0 +1,221 @@
+import { describe, expect, it } from 'vitest';
+
+import { Init, Run } from './logic';
+import { baseSettings, baseContext, baseMeta, callbacks } from './test-helpers';
+import type { Context } from './types';
+
+const init = async (over: Partial<typeof baseMeta> = {}) =>
+    (
+        await Init({
+            participants: [],
+            context: baseContext,
+            settings: baseSettings,
+            meta: { ...baseMeta, ...over },
+            callbacks,
+        })
+    ).capabilities;
+
+const run = async (context: Context, day = 1, over: Partial<typeof baseMeta> = {}) =>
+    (
+        await Run({
+            participants: [],
+            context,
+            settings: baseSettings,
+            meta: { ...baseMeta, tick: day, ...over },
+            callbacks,
+        })
+    ).capabilities;
+
+const makeAll = (context: Context, counts: Record<string, number>): Context => ({
+    ...context,
+    plan: { Make: counts },
+});
+
+describe('Init', () => {
+    it('starts the team somewhere obviously provisional', async () => {
+        const result = await init();
+
+        // Half of an ordinary day's custom: not nothing, which reads as a
+        // broken screen, and not the forecast, which would decide day one.
+        expect(result.plan.Make).toEqual({ lemonade: 28, icedtea: 15, cookies: 10 });
+    });
+
+    it('expects nobody for an item the demand settings say nothing about', async () => {
+        // A scenario can add to the menu without touching the engine's
+        // settings. The new item still gets a line, just an empty one.
+        const { capabilities: result } = await Init({
+            participants: [],
+            context: baseContext,
+            settings: {
+                ...baseSettings,
+                menu: {
+                    ...baseSettings.menu,
+                    Menu: {
+                        ...baseSettings.menu.Menu,
+                        flapjack: { Name: 'Flapjack', Order: 4, Cost: 20, Price: 80 },
+                    },
+                },
+            },
+            meta: baseMeta,
+            callbacks,
+        });
+
+        expect(result.plan.Make.flapjack).toBe(0);
+        expect(result.weather.Expected.flapjack).toBe(0);
+    });
+
+    it('forecasts the first day', async () => {
+        const result = await init();
+
+        expect(['sunny', 'cloudy', 'rainy']).toContain(result.weather.Today);
+        expect(Object.keys(result.weather.Expected).sort()).toEqual([
+            'cookies',
+            'icedtea',
+            'lemonade',
+        ]);
+    });
+
+    it('gives two teams different weather from the one session seed', async () => {
+        const first = await init({ index: 0 });
+        const second = await init({ index: 3 });
+
+        // Not a guarantee for any one day, so this asserts the mechanism: the
+        // team index reaches the derivation.
+        const days = [1, 2, 3, 4, 5, 6];
+        const forTeam = async (index: number) => {
+            let context = await init({ index });
+            const seen: string[] = [];
+            for (const day of days) {
+                seen.push(context.weather.Today);
+                context = await run(context, day, { index });
+            }
+            return seen.join(',');
+        };
+
+        expect(await forTeam(0)).not.toBe(await forTeam(3));
+        expect(first.weather.Today).toBeDefined();
+        expect(second.weather.Today).toBeDefined();
+    });
+
+    it('clears everything a previous session left behind', async () => {
+        const { capabilities: result } = await Init({
+            participants: [],
+            context: {
+                ...baseContext,
+                results: { ...baseContext.results, Purse: 9999, Day: 7 },
+            },
+            settings: baseSettings,
+            meta: baseMeta,
+            callbacks,
+        });
+
+        expect(result.results.Purse).toBe(0);
+        expect(result.results.Day).toBe(0);
+    });
+});
+
+describe('Run', () => {
+    it('sells what it made when people want more than that', async () => {
+        // Nothing made is nothing sold, whatever the weather does.
+        const result = await run(makeAll(baseContext, { lemonade: 0, icedtea: 0, cookies: 0 }));
+
+        expect(result.results.Lines.lemonade?.Sold).toBe(0);
+        expect(result.results.Lines.lemonade?.TurnedAway).toBe(
+            result.results.Lines.lemonade?.Wanted
+        );
+        expect(result.results.Takings).toBe(0);
+        expect(result.results.Spent).toBe(0);
+    });
+
+    it('pours away what it made and did not sell, having paid for it', async () => {
+        const result = await run(
+            makeAll(baseContext, { lemonade: 200, icedtea: 200, cookies: 200 })
+        );
+        const line = result.results.Lines.lemonade;
+
+        expect(line?.Made).toBe(200);
+        expect(line?.Sold).toBe(line?.Wanted);
+        expect(line?.PouredAway).toBe(200 - (line?.Wanted ?? 0));
+        expect(line?.TurnedAway).toBe(0);
+        // 600 items at 15p, 20p and 25p.
+        expect(result.results.Spent).toBe(200 * 15 + 200 * 20 + 200 * 25);
+        expect(result.results.Profit).toBeLessThan(0);
+    });
+
+    it('never both pours away and turns away the same item', async () => {
+        const result = await run(baseContext);
+
+        for (const line of Object.values(result.results.Lines)) {
+            expect(Math.min(line.PouredAway, line.TurnedAway)).toBe(0);
+        }
+    });
+
+    it('takes the sale price for every cup it sells', async () => {
+        const result = await run(baseContext);
+        const expected = Object.entries(result.results.Lines).reduce(
+            (total, [id, line]) => total + line.Sold * baseSettings.menu.Menu[id]!.Price,
+            0
+        );
+
+        expect(result.results.Takings).toBe(expected);
+    });
+
+    it('keeps a running purse across days', async () => {
+        const first = await run(baseContext, 1);
+        const second = await run(first, 2);
+
+        expect(second.results.Purse).toBe(first.results.Profit + second.results.Profit);
+    });
+
+    it('labels the results with the day they are for', async () => {
+        // Earlier days are read back with getPastState, so today's results
+        // are all the engine keeps, and they say which day they belong to.
+        const first = await run(baseContext, 1);
+        const second = await run(first, 2);
+
+        expect(first.results.Day).toBe(1);
+        expect(second.results.Day).toBe(2);
+    });
+
+    it('forecasts tomorrow, and tomorrow plays out as forecast', async () => {
+        const today = await run(baseContext, 1);
+        const tomorrowsForecast = today.weather.Today;
+
+        const tomorrow = await run(today, 2);
+
+        expect(tomorrow.results.Weather).toBe(tomorrowsForecast);
+    });
+
+    it('is busier on a sunny day than a rainy one', async () => {
+        // Same day number, so the same custom draw: only the weather differs.
+        const sunny = await runOnWeather('sunny');
+        const rainy = await runOnWeather('rainy');
+
+        expect(sunny).toBeGreaterThan(rainy);
+    });
+
+    it('is deterministic, so a re-run of one day gives the same answer', async () => {
+        const once = await run(baseContext, 3);
+        const twice = await run(baseContext, 3);
+
+        expect(twice).toEqual(once);
+    });
+
+    it('leaves the plan alone, so yesterday carries into today as a starting point', async () => {
+        const result = await run(makeAll(baseContext, { lemonade: 44, icedtea: 0, cookies: 0 }));
+
+        expect(result.plan.Make).toEqual({ lemonade: 44, icedtea: 0, cookies: 0 });
+    });
+});
+
+/** Total custom on a day whose weather is forced, by searching for a day with it. */
+async function runOnWeather(weather: string): Promise<number> {
+    const stocked = makeAll(baseContext, { lemonade: 500, icedtea: 500, cookies: 500 });
+    for (let day = 1; day <= 40; day += 1) {
+        const result = await run(stocked, day);
+        if (result.results.Weather === weather) {
+            return Object.values(result.results.Lines).reduce((sum, line) => sum + line.Wanted, 0);
+        }
+    }
+    throw new Error(`no ${weather} day in the first 40`);
+}