@masonf539/egyptian-war 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,27 @@
+Egyptian War License
+
+Copyright (c) 2026 Mason Fong
+
+Required Notice: Copyright (c) 2026 Mason Fong
+Required Notice: Egyptian War source code is licensed under the PolyForm Noncommercial License 1.0.0.
+
+The Egyptian War software, including its source code, browser code, styles,
+templates, tests, documentation, rules engine, and networking implementation,
+is licensed under the PolyForm Noncommercial License 1.0.0.
+
+You may use, copy, modify, and distribute the Egyptian War software only for
+purposes permitted by that license. Commercial use requires a separate written
+license from the copyright holder.
+
+The complete PolyForm Noncommercial License 1.0.0 is available at:
+
+https://polyformproject.org/licenses/noncommercial/1.0.0
+
+The creative assets located in public/assets are part of the Egyptian War software 
+and are licensed under the PolyForm Noncommercial License 1.0.0, like the rest of this package.
+
+Third-party dependencies and separately identified third-party 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,66 @@
-# 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.
+# Egyptian War for GameHub
+
+This directory contains the server-authoritative Egyptian War game plugin for
+GameHub and is exported to the `egyptian-war-standalone` branch for release.
+
+Egyptian War is designed to be installed and run by GameHub through the
+`@masonf539/game-sdk` contracts. It is independently versioned, but it is not a
+standalone web application and depends on GameHub for rooms, networking, the
+lobby, shared settings, and browser hosting.
+
+The package owns its rules, state engine, slap arbitration, tests, browser
+presentation, game-specific audio, preview media, and design documentation.
+GameHub supplies rooms, members, spectators, transport, and shared services.
+
+`src/session.ts` owns the authoritative runtime lifecycle, including turn
+timers, slap collection, pause/disconnect recovery, animations, member
+removal, and completion. `public/client.js` owns the browser controller and
+registers it with GameHub's generic client host.
+
+Game-specific music, effects, and picker previews live under `public/assets`
+and are served by GameHub from `/games/egyptian-war`.
+The package-owned `public/register.js` registers those sounds with GameHub's
+shared audio service.
+The game board lives in `public/template.html`, and its presentation lives in
+`public/style.css`. GameHub injects the fragment into a package-specific root;
+the browser controller scopes its element lookups to that root.
+During active play, the stylesheet fixes the board to the available viewport,
+accounts for mobile safe areas, and keeps its compact Pause/connection row
+below GameHub's Settings shortcut. Full Screen and confirmed Exit/Leave
+actions remain platform-owned controls in GameHub's reusable Game tab. The
+shortcut is mounted inside the active game viewport, while the Settings tabs
+move into one horizontal row at medium and small widths.
+Egyptian War declares `play-card` and `slap` input actions for GameHub's
+package-aware Keybinds tab. Their defaults are E and Space respectively, and
+the game subscribes through the shared input service so remapping remains a
+personal GameHub preference.
+The package's public state also states whether the current player may legally
+play a card, keeping the action disabled during the final slap window after a
+failed challenge. Its numeric countdown stays fixed at the right edge inside
+the full-width timer track while the yellow fill passes beneath it, and the
+complete timer scales with the action controls on narrow screens.
+
+The package consumes an exact `@masonf539/game-sdk` release. Once both packages
+are published, GameHub installs an exact Egyptian War version and enables it
+through `gamehub.config.json`. GameHub's `npm run verify:packages` command
+currently verifies that both packed artifacts work without monorepo source.
+
+## Slap rules and penalties
+
+Slap patterns are validated by the server and configured in the lobby. The
+"Three in a Row" pattern checks the latest three cards for an ascending or
+descending rank sequence, including Ace-low and Ace-high sequences. The
+"Tens" pattern checks only two directly adjacent number cards that total ten;
+an Ace counts as one. An active player who false-slaps forfeits the configured
+number of cards, up to the number they hold. An eliminated player has no cards
+to forfeit, so a false slap instead makes them miss the next card's slap
+opportunity. A valid slap can still let an eliminated player re-enter when
+their cooldown is clear.
+
+## Independent repository preparation
+
+The package directory includes its own README, license, TypeScript settings,
+tests, public assets, and package metadata. Its only GameHub code dependency is
+the exact `@masonf539/game-sdk` version declared in `package.json`. A standalone
+lockfile will be generated after that SDK version is published so it records
+the registry artifact rather than the monorepo workspace link.

package/dist/definition.d.ts

@@ -0,0 +1,10 @@
+import { type GameDefinition, type GamePluginManifest } from "@masonf539/game-sdk";
+export type CardSuit = "clubs" | "diamonds" | "hearts" | "spades";
+export type CardRank = "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "10" | "jack" | "queen" | "king" | "ace" | "joker";
+export type Card = {
+    id: string;
+    suit: CardSuit | null;
+    rank: CardRank;
+};
+export declare const egyptianWar: GameDefinition;
+export declare const egyptianWarManifest: GamePluginManifest;

package/dist/definition.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.egyptianWarManifest = exports.egyptianWar = void 0;
+const game_sdk_1 = require("@masonf539/game-sdk");
+exports.egyptianWar = {
+    id: "egyptian-war",
+    name: "Egyptian War",
+    description: "Play cards into a central pile, survive face-card challenges, and race to slap enabled patterns. False slaps carry penalties, and eliminated players must skip the next card's slap opportunity after a false slap. The last player holding all the cards wins.",
+    isPlayable: true,
+    chatEnabled: true,
+    minPlayers: 2,
+    maxPlayers: 6,
+    preview: {
+        videoPath: "/games/egyptian-war/assets/game-previews/preview.mp4",
+        posterPath: "/games/egyptian-war/assets/game-previews/poster.webp"
+    },
+    keybinds: [
+        {
+            id: "play-card",
+            label: "Play a card",
+            description: "Play the top card when it is your turn.",
+            defaultKey: "KeyE"
+        },
+        {
+            id: "slap",
+            label: "Slap",
+            description: "Attempt to slap the central pile.",
+            defaultKey: "Space"
+        }
+    ],
+    rules: [
+        "The server shuffles the deck, deals every card face down, and randomly selects the first player.",
+        "Players cannot view or shuffle their decks.",
+        "Each player has the configured number of seconds to take their turn. If time expires, the server plays that player's top card automatically.",
+        "On a turn, a player flips the top card of their deck onto the central pile.",
+        "Play proceeds clockwise until someone plays a face card (Jack, Queen, or King), an Ace, or a Joker.",
+        "The next player must respond with another face card, Ace, or Joker. A Jack allows 1 attempt, a Queen 2 attempts, a King 3 attempts, an Ace 4 attempts, and a Joker 5 attempts.",
+        "If the challenged player reveals another face card, Ace, or Joker, the challenge passes to the next player with the new number of attempts.",
+        "If the challenged player uses every attempt without revealing a face card, Ace, or Joker, the player who most recently played a challenge card wins the pile unless the final card creates a valid slap combination.",
+        "When the final failed challenge card creates a valid slap combination, players get a short window of about four seconds to slap; if nobody slaps, the most recent challenge card player wins the pile.",
+        "If the challenged player runs out of cards before completing their attempts, the next player with cards inherits the challenge with the remaining attempts.",
+        "A player who runs out of cards is skipped until they reenter by winning a valid slap. An eliminated player who false-slaps must miss the next card's slap opportunity before trying again.",
+        "A player who wins the pile places all of its cards at the bottom of their deck without shuffling and begins the next pile.",
+        "When a valid slap combination appears, the first player to slap wins the central pile.",
+        "Slapping without a valid combination forfeits the configured number of cards face down to the bottom of the pile, or all remaining cards if fewer remain. Penalty cards do not create slap combinations. A player with no cards forfeits no cards for a false slap, but will miss the next card's slap opportunity before being able to try again.",
+        "When only one player still has cards, that player wins unless the current face-up pile has a valid slap that allows an eliminated player to reenter.",
+        "If several players slap at nearly the same moment, the pile goes to one of them by weighted chance that favors the earlier slap. The others forfeit nothing.",
+        "The winner is the player who collects every card."
+    ],
+    settings: [
+        {
+            type: "number",
+            key: "deckCount",
+            label: "Number of Decks",
+            description: "Choose whether the game uses one, two, or three complete decks of cards.",
+            defaultValue: 1,
+            options: [1, 2, 3],
+            unit: "deck"
+        },
+        {
+            key: "includeJokers",
+            label: "Include Jokers",
+            description: "Add two Jokers per deck. Playing a Joker starts a five-attempt challenge and makes the pile slappable.",
+            defaultValue: true
+        },
+        {
+            key: "allowDoubles",
+            label: "Doubles",
+            description: "Allow a slap when two consecutive cards have the same rank.",
+            defaultValue: true
+        },
+        {
+            key: "allowSandwiches",
+            label: "Sandwiches",
+            description: "Allow a slap when matching ranks have exactly one card between them.",
+            defaultValue: true
+        },
+        {
+            key: "allowThreeInARow",
+            label: "Three in a Row",
+            description: "Allow a slap when three cards form an ascending or descending sequence.",
+            defaultValue: true
+        },
+        {
+            key: "allowTopBottom",
+            label: "Top Bottom",
+            description: "Allow a slap when the newest card matches the first card in the pile.",
+            defaultValue: false
+        },
+        {
+            key: "allowTens",
+            label: "Tens",
+            description: "Allow a slap when the two most recent cards are adjacent number cards that total ten. An Ace counts as one.",
+            defaultValue: false
+        },
+        {
+            key: "allowMarriage",
+            label: "Marriage",
+            description: "Allow a slap when a King and Queen are played consecutively in either order.",
+            defaultValue: false
+        },
+        {
+            type: "number",
+            key: "falseSlapPenaltyCards",
+            label: "False Slap Penalty",
+            description: "Cards forfeited to the bottom of the pile for an invalid slap. An eliminated player forfeits no cards, but must miss the next card's slap opportunity.",
+            defaultValue: 2,
+            options: [1, 2, 3],
+            unit: "card"
+        },
+        {
+            type: "number",
+            control: "range",
+            key: "turnTimerSeconds",
+            label: "Player Timer",
+            description: "Seconds each player has to play a card before the server plays their top card automatically.",
+            defaultValue: 15,
+            min: 5,
+            max: 120,
+            step: 1,
+            unit: "second"
+        }
+    ]
+};
+exports.egyptianWarManifest = {
+    apiVersion: game_sdk_1.gameHubGameApiVersion,
+    packageVersion: "1.0.0",
+    definition: exports.egyptianWar,
+    client: {
+        delivery: "embedded",
+        markupPath: "template.html",
+        entryPaths: ["register.js", "client.js"],
+        stylePaths: ["style.css"]
+    }
+};

package/dist/engine.d.ts

@@ -0,0 +1,94 @@
+import type { Card } from "./definition.js";
+export type EgyptianWarSettings = {
+    deckCount: number;
+    includeJokers: boolean;
+    allowDoubles: boolean;
+    allowSandwiches: boolean;
+    allowThreeInARow: boolean;
+    allowTopBottom: boolean;
+    allowTens: boolean;
+    allowMarriage: boolean;
+    falseSlapPenaltyCards: number;
+};
+export type EgyptianWarPlayerInput = {
+    id: string;
+    name: string;
+    avatar: string;
+};
+export type EgyptianWarPlayerState = EgyptianWarPlayerInput & {
+    cards: Card[];
+    isEliminated: boolean;
+    /** Card-play count at which this eliminated player may slap again. */
+    slapCooldownUntilCardPlayCount?: number | null;
+};
+export type EgyptianWarState = {
+    players: EgyptianWarPlayerState[];
+    pile: Card[];
+    deferredCards: Card[];
+    penaltyPileCardCount: number;
+    pileVersion: number;
+    /** Total cards played from players' hands during this game. */
+    cardsPlayedCount?: number;
+    currentPlayerIndex: number;
+    settings: EgyptianWarSettings;
+    challenge: {
+        challengerId: string;
+        responderId: string;
+        attemptsRemaining: number;
+    } | null;
+    pendingPileWinnerId: string | null;
+    totalCardCount: number;
+    winnerId: string | null;
+    status: "playing" | "finished";
+    activityMessage: string;
+};
+export type PublicEgyptianWarState = {
+    status: EgyptianWarState["status"];
+    currentPlayerId: string | null;
+    canPlayCard: boolean;
+    winnerId: string | null;
+    pileCardCount: number;
+    hasFaceUpCards: boolean;
+    topCard: Card | null;
+    recentCards: Card[];
+    pileVersion: number;
+    isPaused: boolean;
+    pauseMessage: string | null;
+    isAnimating: boolean;
+    turnTimerSeconds: number;
+    turnTimeRemainingMs: number | null;
+    challenge: EgyptianWarState["challenge"];
+    activityMessage: string;
+    players: Array<{
+        id: string;
+        name: string;
+        avatar: string;
+        cardCount: number;
+        isConnected: boolean;
+        isEliminated: boolean;
+        isCurrentPlayer: boolean;
+    }>;
+};
+export type EgyptianWarAction = "play-card" | "slap";
+export type RandomInteger = (maxExclusive: number) => number;
+export declare class EgyptianWarRuleError extends Error {
+    constructor(message: string);
+}
+export declare function createDeck(includeJokers: boolean, deckCount?: number): Card[];
+export declare function shuffleDeck(cards: readonly Card[], randomInteger?: RandomInteger): Card[];
+export declare function createEgyptianWarState(playerInputs: readonly EgyptianWarPlayerInput[], settings: EgyptianWarSettings, randomInteger?: RandomInteger): EgyptianWarState;
+export type EgyptianWarDeparture = "removed" | "left";
+export declare function removeEgyptianWarPlayer(state: EgyptianWarState, playerId: string, departure?: EgyptianWarDeparture): string;
+export declare function isEgyptianWarPileSlappable(pile: readonly Card[], settings: EgyptianWarSettings): boolean;
+export declare function isEgyptianWarStateSlappable(state: Pick<EgyptianWarState, "pile" | "penaltyPileCardCount" | "settings">): boolean;
+export type EgyptianWarSlapCooldownStatus = "none" | "waiting" | "blocked";
+/** Start a cooldown that lasts until one more card has been played. */
+export declare function startEgyptianWarSlapCooldown(state: EgyptianWarState, playerId: string): void;
+/**
+ * Returns the status of an eliminated player's one-card slap cooldown.
+ * The next card's opportunity is consumed the first time they try to slap on it.
+ */
+export declare function checkEgyptianWarSlapCooldown(state: EgyptianWarState, playerId: string): EgyptianWarSlapCooldownStatus;
+export declare function applyEgyptianWarAction(state: EgyptianWarState, playerId: string, action: EgyptianWarAction): string;
+export declare function resolveEgyptianWarTurnTimeout(state: EgyptianWarState): string;
+export declare function createPublicEgyptianWarState(state: EgyptianWarState, isPaused?: boolean, isAnimating?: boolean, turnTimerSeconds?: number, turnTimeRemainingMs?: number | null, pauseMessage?: string | null, connectedPlayerIds?: ReadonlySet<string>): PublicEgyptianWarState;