@masonf539/game-sdk 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,25 @@
+GameHub SDK License
+
+Copyright (c) 2026 Mason Fong
+
+Required Notice: Copyright (c) 2026 Mason Fong
+Required Notice: The GameHub SDK is licensed under the PolyForm Noncommercial License 1.0.0.
+
+The GameHub SDK, including its source code, compiled forms, documentation,
+examples, tests, and associated files, is licensed under the PolyForm
+Noncommercial License 1.0.0.
+
+The complete license terms are available at:
+
+https://polyformproject.org/licenses/noncommercial/1.0.0
+
+You may use, copy, modify, and distribute the GameHub SDK only for purposes
+permitted by the PolyForm Noncommercial License 1.0.0.
+
+Commercial use requires a separate written license from the copyright holder.
+
+Third-party dependencies and materials remain governed by their respective
+licenses.
+
+THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OR CONDITION, TO THE EXTENT
+PERMITTED BY LAW.

package/README.md

@@ -1,3 +1,30 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# GameHub Game SDK
+
+Versioned TypeScript contracts used by GameHub and its trusted game packages.
+Game packages depend on this package instead of importing GameHub's private
+server source.
+
+This package is reusable GameHub platform infrastructure, not a playable game.
+It lives under `packages/` and remains owned by the GameHub repository when
+individual games move into their own repositories. Egyptian War and future
+games consume an exact SDK release from the public npm registry.
+
+The SDK defines package manifests, authoritative `GameSession` lifecycle
+hooks, viewer-safe state and event envelopes, browser-module platform
+services, and optional named keybind actions. A game declares stable action
+IDs and defaults; GameHub owns the remapping UI, local persistence, and input
+routing through `GameClientContext.input`. GameHub treats installed packages
+as trusted code and does not expose its private room implementation through
+these contracts.
+
+## Releasing
+
+The package is configured for public npm publication. From the repository
+root, first update its semantic version and verify the full suite, then run:
+
+```powershell
+npm publish --workspace @masonf539/game-sdk
+```
+
+Publishing requires npm access to the `@masonf539` scope. Game packages should
+pin a released SDK version so their supported GameHub API is reproducible.

package/dist/gameDefinition.d.ts

@@ -0,0 +1,57 @@
+export type BooleanGameSetting = {
+    type?: "boolean";
+    key: string;
+    label: string;
+    description: string;
+    defaultValue: boolean;
+};
+export type SelectNumberGameSetting = {
+    type: "number";
+    control?: "select";
+    key: string;
+    label: string;
+    description: string;
+    defaultValue: number;
+    options: number[];
+    unit?: string;
+};
+export type RangeNumberGameSetting = {
+    type: "number";
+    control: "range";
+    key: string;
+    label: string;
+    description: string;
+    defaultValue: number;
+    min: number;
+    max: number;
+    step: number;
+    unit?: string;
+};
+export type NumberGameSetting = SelectNumberGameSetting | RangeNumberGameSetting;
+export type GameSetting = BooleanGameSetting | NumberGameSetting;
+export type GameSettingValue = boolean | number;
+export type GamePreview = {
+    videoPath: string;
+    posterPath: string;
+};
+export type GameKeybind = {
+    /** Stable action id used by the game client, such as "play-card". */
+    id: string;
+    label: string;
+    description?: string;
+    /** KeyboardEvent.code value, so defaults follow physical key positions. */
+    defaultKey: string;
+};
+export type GameDefinition = {
+    id: string;
+    name: string;
+    description: string;
+    isPlayable: boolean;
+    chatEnabled: boolean;
+    rules: string[];
+    minPlayers: number;
+    maxPlayers: number;
+    settings: GameSetting[];
+    keybinds?: GameKeybind[];
+    preview?: GamePreview;
+};

package/dist/gameDefinition.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { BooleanGameSetting, GameDefinition, GameKeybind, GamePreview, GameSetting, GameSettingValue, NumberGameSetting, RangeNumberGameSetting, SelectNumberGameSetting } from "./gameDefinition.js";
+export { gameHubGameApiVersion, type EmbeddedGameClient, type GameClientDelivery, type GamePluginManifest, type GamePluginPackage, type ModuleGameClient } from "./manifest.js";
+export type { GameActionEnvelope, GameActionResult, GameAudioApi, GameClientContext, GameClientInstance, GameClientModule, GameCompletion, GameEvent, GameEventEnvelope, GameLifecycleState, GameMember, GameMemberRole, GameInputApi, GamePlatformEvent, GameServerPlugin, GameSession, GameSessionContext, GameStateEnvelope, GameViewer } from "./plugin.js";
+export { GamePluginRegistry, GamePluginValidationError, validateGamePluginManifest } from "./registry.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateGamePluginManifest = exports.GamePluginValidationError = exports.GamePluginRegistry = exports.gameHubGameApiVersion = void 0;
+var manifest_js_1 = require("./manifest.js");
+Object.defineProperty(exports, "gameHubGameApiVersion", { enumerable: true, get: function () { return manifest_js_1.gameHubGameApiVersion; } });
+var registry_js_1 = require("./registry.js");
+Object.defineProperty(exports, "GamePluginRegistry", { enumerable: true, get: function () { return registry_js_1.GamePluginRegistry; } });
+Object.defineProperty(exports, "GamePluginValidationError", { enumerable: true, get: function () { return registry_js_1.GamePluginValidationError; } });
+Object.defineProperty(exports, "validateGamePluginManifest", { enumerable: true, get: function () { return registry_js_1.validateGamePluginManifest; } });

package/dist/manifest.d.ts

@@ -0,0 +1,28 @@
+import type { GameDefinition } from "./gameDefinition.js";
+import type { GameServerPlugin } from "./plugin.js";
+export declare const gameHubGameApiVersion: 1;
+export type EmbeddedGameClient = {
+    delivery: "embedded";
+    markupPath?: string;
+    entryPaths?: string[];
+    stylePaths?: string[];
+};
+export type ModuleGameClient = {
+    delivery: "module";
+    entryPath: string;
+    markupPath?: string;
+    entryPaths?: string[];
+    stylePaths?: string[];
+};
+export type GameClientDelivery = EmbeddedGameClient | ModuleGameClient;
+export type GamePluginManifest = {
+    apiVersion: typeof gameHubGameApiVersion;
+    packageVersion: string;
+    definition: GameDefinition;
+    client: GameClientDelivery;
+};
+export type GamePluginPackage = {
+    manifest: GamePluginManifest;
+    publicDirectory: string;
+    server: GameServerPlugin;
+};

package/dist/manifest.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gameHubGameApiVersion = void 0;
+exports.gameHubGameApiVersion = 1;

package/dist/plugin.d.ts

@@ -0,0 +1,120 @@
+import type { GameSettingValue } from "./gameDefinition.js";
+import type { GamePluginManifest } from "./manifest.js";
+export type GameMemberRole = "player" | "spectator";
+export type GameMember = {
+    id: string;
+    name: string;
+    avatar: string;
+    isConnected: boolean;
+    role: GameMemberRole;
+};
+export type GameViewer = {
+    memberId: string;
+    role: GameMemberRole;
+};
+export type GameActionEnvelope = {
+    type: string;
+    payload?: unknown;
+};
+export type GameActionResult = {
+    success: boolean;
+    message?: string;
+};
+export type GameEvent = {
+    type: string;
+    payload?: unknown;
+};
+export type GameStateEnvelope = {
+    gameId: string;
+    state: unknown;
+};
+export type GameEventEnvelope = {
+    gameId: string;
+    event: GameEvent;
+};
+export type GameCompletion = {
+    winnerId: string | null;
+    reason: string;
+};
+export type GameSessionContext = {
+    roomCode: string;
+    members: () => readonly GameMember[];
+    broadcastState: () => void;
+    emitEvent: (event: GameEvent) => void;
+    finish: (completion: GameCompletion) => void;
+    now: () => number;
+    randomInteger(maxExclusive: number): number;
+};
+export type GameLifecycleState = {
+    isPaused: boolean;
+    isBusy: boolean;
+};
+export interface GameSession {
+    start?(): void;
+    getPublicState(viewer: GameViewer): unknown;
+    getLifecycleState(): GameLifecycleState;
+    handleAction(memberId: string, action: GameActionEnvelope): GameActionResult | Promise<GameActionResult>;
+    pause?(): GameActionResult;
+    resume?(): GameActionResult;
+    memberDisconnected?(memberId: string): void;
+    memberReconnected?(memberId: string, previousMemberId?: string): void;
+    /**
+     * A member is leaving the game. `voluntary` is true when they left on
+     * their own (they may still be connected) and false when the host removed
+     * a disconnected player.
+     */
+    memberRemoved?(memberId: string, options?: {
+        voluntary?: boolean;
+    }): GameActionResult;
+    dispose(): void;
+}
+export interface GameServerPlugin {
+    manifest: GamePluginManifest;
+    createSession(context: GameSessionContext, settings: Readonly<Record<string, GameSettingValue>>): GameSession;
+}
+export type GameAudioApi = {
+    playEffect(name: string): void;
+    registerEffect(name: string, options: {
+        source: string;
+        category?: "music" | "join" | "game";
+        volume?: number;
+    }): void;
+    registerMusicScene(name: string, source: string): void;
+    setScene(scene: string | null): void;
+};
+export type GameInputApi = {
+    /** Subscribe to a named action declared by this game's manifest. */
+    onAction(actionId: string, handler: () => void): () => void;
+};
+export type GameClientContext = {
+    root: HTMLElement;
+    gameId: string;
+    memberId: string;
+    role: GameMemberRole;
+    isHost: boolean;
+    launchData: unknown;
+    audio: GameAudioApi;
+    input: GameInputApi;
+    submitAction(action: GameActionEnvelope): Promise<GameActionResult>;
+    requestPause(isPaused: boolean): Promise<GameActionResult>;
+    sendChat(message: string): Promise<GameActionResult>;
+    removeMember(memberId: string): Promise<GameActionResult>;
+    /** Opens the confirmation flow for leaving the active game but staying in its room. */
+    requestLeave(): void;
+    notify(message: string): void;
+    requestExit(): void;
+};
+export type GamePlatformEvent = {
+    type: "spectators" | "chat-message";
+    payload: unknown;
+};
+export interface GameClientInstance {
+    receiveState(state: unknown): void;
+    receiveEvent(event: GameEvent): void;
+    receivePlatformEvent?(event: GamePlatformEvent): void;
+    setPaused?(isPaused: boolean): void;
+    destroy(): void;
+}
+export interface GameClientModule {
+    mount(context: GameClientContext): GameClientInstance;
+}

package/dist/plugin.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/registry.d.ts

@@ -0,0 +1,14 @@
+import type { GameDefinition } from "./gameDefinition.js";
+import { type GamePluginManifest } from "./manifest.js";
+export declare class GamePluginValidationError extends Error {
+    constructor(message: string);
+}
+export declare function validateGamePluginManifest(manifest: GamePluginManifest): void;
+export declare class GamePluginRegistry {
+    #private;
+    constructor(manifests?: Iterable<GamePluginManifest>);
+    register(manifest: GamePluginManifest): void;
+    getManifest(gameId: string): GamePluginManifest | null;
+    getDefinition(gameId: string): GameDefinition | null;
+    listDefinitions(): GameDefinition[];
+}

package/dist/registry.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GamePluginRegistry = exports.GamePluginValidationError = void 0;
+exports.validateGamePluginManifest = validateGamePluginManifest;
+const manifest_js_1 = require("./manifest.js");
+const identifierPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const settingKeyPattern = /^[A-Za-z][A-Za-z0-9]*$/;
+const actionIdPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const semanticVersionPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+class GamePluginValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GamePluginValidationError";
+    }
+}
+exports.GamePluginValidationError = GamePluginValidationError;
+function requireNonEmpty(value, field) {
+    if (value.trim().length === 0) {
+        throw new GamePluginValidationError(`${field} cannot be empty.`);
+    }
+}
+function validatePublicPath(value, field) {
+    requireNonEmpty(value, field);
+    if (!/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(value) ||
+        value.startsWith("/") ||
+        value.includes("\\") ||
+        value.split("/").includes("..")) {
+        throw new GamePluginValidationError(`${field} must be package-relative.`);
+    }
+}
+// Preview media is addressed by absolute site path inside the game's own
+// folder, e.g. /games/<id>/assets/preview.mp4. It ends up in a CSS url(), so
+// only plain path characters are allowed.
+function validatePreviewPath(value, gameId, field) {
+    requireNonEmpty(value, field);
+    const prefix = `/games/${gameId}/`;
+    if (!value.startsWith(prefix) ||
+        !/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(value.slice(prefix.length)) ||
+        value.split("/").includes("..")) {
+        throw new GamePluginValidationError(`${field} must be a path inside ${prefix}.`);
+    }
+}
+function validateSetting(setting, gameId) {
+    const settingKey = setting.key;
+    const defaultValue = setting.defaultValue;
+    if (!settingKeyPattern.test(settingKey)) {
+        throw new GamePluginValidationError(`${gameId} has an invalid setting key: ${settingKey}.`);
+    }
+    requireNonEmpty(setting.label, `${gameId}.${settingKey} label`);
+    requireNonEmpty(setting.description, `${gameId}.${settingKey} description`);
+    if (setting.type !== "number") {
+        if (typeof defaultValue !== "boolean") {
+            throw new GamePluginValidationError(`${gameId}.${settingKey} must have a boolean default.`);
+        }
+        return;
+    }
+    if (typeof defaultValue !== "number" || !Number.isFinite(defaultValue)) {
+        throw new GamePluginValidationError(`${gameId}.${settingKey} must have a finite numeric default.`);
+    }
+    if (setting.control === "range") {
+        if (!Number.isFinite(setting.min) ||
+            !Number.isFinite(setting.max) ||
+            !Number.isFinite(setting.step) ||
+            setting.min > setting.max ||
+            setting.step <= 0 ||
+            defaultValue < setting.min ||
+            defaultValue > setting.max) {
+            throw new GamePluginValidationError(`${gameId}.${settingKey} has an invalid numeric range.`);
+        }
+        return;
+    }
+    if (setting.options.length === 0 ||
+        setting.options.some((option) => !Number.isFinite(option)) ||
+        new Set(setting.options).size !== setting.options.length ||
+        !setting.options.includes(defaultValue)) {
+        throw new GamePluginValidationError(`${gameId}.${settingKey} has invalid select options.`);
+    }
+}
+function validateGamePluginManifest(manifest) {
+    if (manifest.apiVersion !== manifest_js_1.gameHubGameApiVersion) {
+        throw new GamePluginValidationError(`Unsupported GameHub game API version: ${manifest.apiVersion}.`);
+    }
+    if (!semanticVersionPattern.test(manifest.packageVersion)) {
+        throw new GamePluginValidationError(`Invalid game package version: ${manifest.packageVersion}.`);
+    }
+    const game = manifest.definition;
+    if (!identifierPattern.test(game.id)) {
+        throw new GamePluginValidationError(`Invalid game id: ${game.id}.`);
+    }
+    requireNonEmpty(game.name, `${game.id} name`);
+    requireNonEmpty(game.description, `${game.id} description`);
+    if (!Number.isInteger(game.minPlayers) ||
+        !Number.isInteger(game.maxPlayers) ||
+        game.minPlayers < 1 ||
+        game.maxPlayers < game.minPlayers) {
+        throw new GamePluginValidationError(`${game.id} has invalid player limits.`);
+    }
+    if (game.preview) {
+        validatePreviewPath(game.preview.videoPath, game.id, `${game.id} preview video path`);
+        validatePreviewPath(game.preview.posterPath, game.id, `${game.id} preview poster path`);
+    }
+    const settingKeys = new Set();
+    for (const setting of game.settings) {
+        if (settingKeys.has(setting.key)) {
+            throw new GamePluginValidationError(`${game.id} has a duplicate setting key: ${setting.key}.`);
+        }
+        settingKeys.add(setting.key);
+        validateSetting(setting, game.id);
+    }
+    const keybindIds = new Set();
+    const defaultKeys = new Set();
+    for (const keybind of game.keybinds ?? []) {
+        if (!actionIdPattern.test(keybind.id)) {
+            throw new GamePluginValidationError(`${game.id} has an invalid keybind action id: ${keybind.id}.`);
+        }
+        if (keybindIds.has(keybind.id)) {
+            throw new GamePluginValidationError(`${game.id} has a duplicate keybind action id: ${keybind.id}.`);
+        }
+        requireNonEmpty(keybind.label, `${game.id}.${keybind.id} keybind label`);
+        requireNonEmpty(keybind.defaultKey, `${game.id}.${keybind.id} default keybind`);
+        if (defaultKeys.has(keybind.defaultKey)) {
+            throw new GamePluginValidationError(`${game.id} assigns ${keybind.defaultKey} to multiple actions.`);
+        }
+        keybindIds.add(keybind.id);
+        defaultKeys.add(keybind.defaultKey);
+    }
+    if (manifest.client.delivery === "module") {
+        validatePublicPath(manifest.client.entryPath, `${game.id} module entry path`);
+    }
+    if (manifest.client.markupPath) {
+        validatePublicPath(manifest.client.markupPath, `${game.id} client markup path`);
+    }
+    for (const entryPath of manifest.client.entryPaths ?? []) {
+        validatePublicPath(entryPath, `${game.id} client entry path`);
+    }
+    for (const stylePath of manifest.client.stylePaths ?? []) {
+        validatePublicPath(stylePath, `${game.id} client style path`);
+    }
+}
+class GamePluginRegistry {
+    #manifests = new Map();
+    constructor(manifests = []) {
+        for (const manifest of manifests) {
+            this.register(manifest);
+        }
+    }
+    register(manifest) {
+        validateGamePluginManifest(manifest);
+        const gameId = manifest.definition.id;
+        if (this.#manifests.has(gameId)) {
+            throw new GamePluginValidationError(`A game with id ${gameId} is already registered.`);
+        }
+        this.#manifests.set(gameId, manifest);
+    }
+    getManifest(gameId) {
+        return this.#manifests.get(gameId) ?? null;
+    }
+    getDefinition(gameId) {
+        return this.getManifest(gameId)?.definition ?? null;
+    }
+    listDefinitions() {
+        return Array.from(this.#manifests.values(), (manifest) => manifest.definition);
+    }
+}
+exports.GamePluginRegistry = GamePluginRegistry;

package/package.json

@@ -1,6 +1,43 @@
-{
-  "name": "@masonf539/game-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@masonf539/game-sdk",
+  "version": "1.0.0",
+  "description": "Versioned contracts for GameHub game plugins.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MasonF539/GameHub.git",
+    "directory": "packages/game-sdk"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "clean:test": "node -e \"require('node:fs').rmSync('dist-test',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc",
+    "build:test": "npm run clean:test && tsc -p tsconfig.test.json",
+    "check": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+    "test": "npm run build:test && node --test dist-test/*.test.js",
+    "prepack": "npm run build"
+  },
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "type": "commonjs",
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.4",
+    "typescript": "^7.0.2"
+  }
+}