@magicworks/client-party-game 0.1.0-rc.0

package/dist/protocol.js

@@ -0,0 +1,232 @@
+"use strict";
+/**
+ * The party game wire protocol, shared by the server
+ * (`@magicworks/service-party-game`), the host TV (through `PartyGameClient`)
+ * and, by hand, the phone page the server hosts (`public/app.js`).
+ *
+ * Roles
+ * -----
+ * host   - the ROXi TV app. Owns the video playback and therefore owns round
+ *          timing. It tells the server when a round starts and ends.
+ * player - a phone browser. Only ever sends a join request, a ready and an
+ *          answer.
+ *
+ * The correct answer index is sent by the host at round start and never
+ * leaves the server: players receive options only, and the server is the sole
+ * authority on who scored what.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Feature = exports.PlayerRefusal = exports.HostRefusal = exports.GameStatus = exports.PlayerMessage = exports.HostMessage = exports.PlayerEvent = exports.HostEvent = exports.TimeEvent = exports.GameMessage = exports.GameEvent = exports.PARTY_REGIONS = exports.SPEEDTEST_SIZES = exports.ROUTING_QUERY_KEY = exports.CODE_PREFIX_LENGTH = exports.CODE_LENGTH = exports.CODE_ALPHABET = exports.GAME_READY_TIMEOUT_MS = exports.ROUND_LEAD_MS = exports.MAX_NAME_LENGTH = exports.TOTAL_ROUNDS = exports.REOPEN_WINDOW_MS = exports.MAX_PLAYERS = void 0;
+exports.speedtestPath = speedtestPath;
+exports.phonePageConfigScript = phonePageConfigScript;
+exports.socketUrlForCode = socketUrlForCode;
+exports.regionOfCode = regionOfCode;
+exports.normaliseCode = normaliseCode;
+exports.codePrefixOf = codePrefixOf;
+exports.scoreForAnswer = scoreForAnswer;
+exports.MAX_PLAYERS = 20;
+/**
+ * How long a finished party stays worth coming back to. Opening a lobby with
+ * the code of a room touched inside this window reopens that room - same code,
+ * same players, scores back to zero - so a second game needs a tap on each
+ * phone rather than a fresh scan and everybody's name typed again. Past it the
+ * room is left where it is and a new one is opened.
+ */
+exports.REOPEN_WINDOW_MS = 20 * 60 * 1000;
+exports.TOTAL_ROUNDS = 15;
+exports.MAX_NAME_LENGTH = 16;
+/**
+ * A round starts on the TV and the phones at once: when the host has the
+ * round's video preloaded the server picks a start time ROUND_LEAD_MS ahead -
+ * long enough for the message to reach the TV - or the host's planned start,
+ * if later. The TV plays the video at that moment by its own clock, corrected
+ * against the server's with `time:ping`, and the phones get the options then.
+ */
+exports.ROUND_LEAD_MS = 700;
+/**
+ * The countdown before round 1 runs on the TV and every phone at once, and only
+ * once everybody is there for it: starting a game asks the TV and every phone
+ * in the room whether it is ready (`game:prepare`), and the countdown goes out
+ * to all of them (`game:countdown`) once they have all said so (`game:ready`)
+ * - or this long after the start, so that one device that never answers cannot
+ * keep the rest waiting.
+ */
+exports.GAME_READY_TIMEOUT_MS = 10000;
+/** No I, O, 0 or 1 - codes are read off a TV screen and typed on a phone. */
+exports.CODE_ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
+exports.CODE_LENGTH = 6;
+/**
+ * A room's code starts with the prefix of the server that holds it, and the
+ * load balancer routes on it: every connection that knows its room carries
+ * the code in the `c` query parameter (ROUTING_QUERY_KEY), so it reaches that
+ * server whichever server it would otherwise have been handed to.
+ */
+exports.CODE_PREFIX_LENGTH = 2;
+exports.ROUTING_QUERY_KEY = 'c';
+/**
+ * The speed test a TV times in the lobby, to pick a video rendition it can
+ * load quickly all game: files of random bytes on the CDN that serves the
+ * phone page, closer to where the videos come from than the party servers
+ * are. One file per size, at `speedtestPath(size)`.
+ */
+exports.SPEEDTEST_SIZES = [
+    64 * 1024,
+    256 * 1024,
+    1024 * 1024,
+    2 * 1024 * 1024,
+    4 * 1024 * 1024,
+    8 * 1024 * 1024,
+];
+function speedtestPath(size) {
+    return `/speedtest/${size}.bin`;
+}
+/**
+ * The phone page's `config.js`: where its sockets go. Written when the page
+ * is deployed, since the party servers' names depend on where; everything
+ * else the page needs from the protocol is bundled into it.
+ */
+function phonePageConfigScript(config) {
+    return `window.PARTY_CONFIG=${JSON.stringify(config)};`;
+}
+/** The socket URL for a code, by its region. */
+function socketUrlForCode(code, config) {
+    const region = regionOfCode(code);
+    return (region && config.regionSocketUrls?.[region]) || config.socketUrl;
+}
+/**
+ * Which region's servers hand out the codes starting with which characters.
+ * A room lives on one server in one region, and the party servers' global
+ * name is latency-routed, so a TV and a phone in the same room can be sent
+ * to different regions: a code says which region it belongs to, and a
+ * client connects for it to that region's own name. Between them the
+ * regions cover every first character, so any code belongs somewhere.
+ */
+exports.PARTY_REGIONS = {
+    'us-east-1': 'ABCDEFGHJKLMNPQR',
+    'eu-west-1': 'STUVWXYZ23456789',
+};
+/** The region a code belongs to. */
+function regionOfCode(code) {
+    const first = code.charAt(0).toUpperCase();
+    return (Object.keys(exports.PARTY_REGIONS).find(region => exports.PARTY_REGIONS[region].includes(first)) ?? null);
+}
+/** `code` tidied up the way a phone types it, or null if it cannot be a code. */
+function normaliseCode(code) {
+    const clean = String(code ?? '')
+        .trim()
+        .toUpperCase();
+    if (clean.length !== exports.CODE_LENGTH) {
+        return null;
+    }
+    return [...clean].every(c => exports.CODE_ALPHABET.includes(c)) ? clean : null;
+}
+/** The server prefix a code routes by. */
+function codePrefixOf(code) {
+    return code.slice(0, exports.CODE_PREFIX_LENGTH);
+}
+/**
+ * Speed based scoring, mirroring the single player formula in GameCore:
+ * points scale with the time left on the clock, with a bonus for answering
+ * in the first half of the round.
+ */
+function scoreForAnswer(secondsLeft, totalRoundTime, modifier) {
+    const speedBonus = secondsLeft >= totalRoundTime / 2 ? 1.2 : 1.0;
+    return Math.max(1, Math.round(secondsLeft * modifier * speedBonus));
+}
+/* ------------------------------------------------------------ event names */
+/** The TV or a phone -> server: here, set up, and ready for the countdown. */
+exports.GameEvent = {
+    Ready: 'game:ready',
+};
+/** Server -> the TV and the phones */
+exports.GameMessage = {
+    /** Say when you are ready for the countdown (phones: straight away). */
+    Prepare: 'game:prepare',
+    /** Everybody is: start the countdown now. */
+    Countdown: 'game:countdown',
+};
+/** TV -> server: the server's clock, for working out the offset to it. */
+exports.TimeEvent = {
+    Ping: 'time:ping',
+};
+/** Host -> server */
+exports.HostEvent = {
+    Create: 'host:create',
+    Start: 'host:start',
+    /** The round's options and answer, sent once the host's video is preloaded. */
+    RoundStart: 'host:round-start',
+    RoundEnd: 'host:round-end',
+    GameEnd: 'host:game-end',
+    Restart: 'host:restart',
+    /** Open, here, a room handed over by a server on its way out: see HostMessage.Move. */
+    Adopt: 'host:adopt',
+    /** To the server it is leaving: the room is open again under this code. */
+    Moved: 'host:moved',
+};
+/** Player -> server */
+exports.PlayerEvent = {
+    Join: 'player:join',
+    Ready: 'player:ready',
+    Answer: 'player:answer',
+};
+/** Server -> host */
+exports.HostMessage = {
+    Players: 'players',
+    AllAnswered: 'round:all-answered',
+    GameOver: 'game:over',
+    /** Play the round at `startAt` (server time). */
+    RoundGo: 'round:go',
+    /**
+     * This server is on its way out and the game is over: take the room to
+     * another one (`host:adopt` with the token, over a connection with no room
+     * in its query), then say where it went (`host:moved`).
+     */
+    Move: 'room:move',
+};
+/** Server -> player */
+exports.PlayerMessage = {
+    State: 'state',
+    Dropped: 'dropped',
+    RoundStart: 'round:start',
+    RoundResult: 'round:result',
+    GameOver: 'game:over',
+    /** The party is open under another code: connect for it and rejoin as before. */
+    Moved: 'room:moved',
+    /** The party is waiting for its TV, which is gone for now: try again in a while. */
+    Parked: 'room:parked',
+};
+exports.GameStatus = {
+    Lobby: 'lobby',
+    Playing: 'playing',
+    Over: 'over',
+};
+/**
+ * Why a host call was refused, in its ack's `reason`.
+ */
+exports.HostRefusal = {
+    /**
+     * A server on its way out: it keeps the rooms it has, but opens no new ones
+     * (and past its drain deadline, starts no more games), so the host connects
+     * again without a room in its query - which the load balancer hands to a
+     * server still taking parties - and asks again.
+     */
+    Draining: 'draining',
+    /** The room is open under another code, `movedTo`: ask again there. */
+    Moved: 'moved',
+    /** The room is on its way to another server: ask again once it is there. */
+    Moving: 'moving',
+};
+/** Why a phone's call was refused, in its ack's `reason`. */
+exports.PlayerRefusal = {
+    /** The room is on its way to another server: ask again in a moment, or follow room:moved. */
+    Moving: 'moving',
+};
+/**
+ * What a host or a phone can do beyond the first version of the protocol,
+ * sent with `host:create` and `player:join`. A server only moves a room when
+ * its host and every phone in it can follow.
+ */
+exports.Feature = {
+    Move: 'move',
+};
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/dist/socket.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The little of a socket.io client socket this library uses.
+ *
+ * It is structural so the caller brings its own socket.io-client: the ROXi
+ * app ships 2.x (the server accepts it with `allowEIO3`), node and newer
+ * browsers 4.x, and either one's `io` can be handed to `PartyGameClient`
+ * as it is. Bundling one here would put a second copy in the app.
+ */
+export interface PartySocket {
+    readonly connected: boolean;
+    on(event: string, listener: (...args: any[]) => void): unknown;
+    emit(event: string, ...args: any[]): unknown;
+    close(): unknown;
+}
+export interface PartySocketOptions {
+    transports: string[];
+    /** What the load balancer routes on: see ROUTING_QUERY_KEY. */
+    query: Record<string, string>;
+    /** Always a connection of its own, never one shared with another socket to the same URL. */
+    forceNew: boolean;
+    reconnection: boolean;
+    reconnectionDelay: number;
+    reconnectionDelayMax: number;
+    timeout: number;
+    /** socket.io-client 2.x only: no JSONP polling fallback. */
+    jsonp?: boolean;
+}
+/** socket.io-client's `io`, of either major version. */
+export type PartySocketFactory = (url: string, options: PartySocketOptions) => PartySocket;
+//# sourceMappingURL=socket.d.ts.map

package/dist/socket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket.d.ts","sourceRoot":"","sources":["../src/socket.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC;IAC/D,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;IAC7C,KAAK,IAAI,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,4FAA4F;IAC5F,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wDAAwD;AACxD,MAAM,MAAM,kBAAkB,GAAG,CAC/B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,kBAAkB,KACxB,WAAW,CAAC"}

package/dist/socket.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=socket.js.map

package/dist/socket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket.js","sourceRoot":"","sources":["../src/socket.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@magicworks/client-party-game",
+  "version": "0.1.0-rc.0",
+  "description": "Host TV client and wire protocol for the party game server",
+  "author": "Luis Ávila <luis.avila@faststream.network>",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "run -T tsgo",
+    "build:watch": "run -T tsgo --build --watch --preserveWatchOutput --pretty",
+    "clean": "rm -rf dist",
+    "lint": "run -T biome check . && run -T sort-package-json package.json --check",
+    "lint:fix": "run -T biome check --write . && run -T sort-package-json package.json",
+    "test": "vitest --no-watch"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.4",
+    "vitest": "4.1.5"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}