@masonf539/egyptian-war 0.0.0-stage → 1.0.1-beta.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,68 @@
-# Temporary Holding Version
+# Egyptian War for GameHub
 
-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.
+This repository contains the server-authoritative Egyptian War game plugin
+for GameHub.
+
+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 prevents them from slapping the unchanged pile
+again. The cooldown clears when the next card is played, allowing that card to
+be slapped and the eliminated player to re-enter immediately.
+Invalid reentry attempts use the same visible one-hand slap animation as other
+false slaps; additional attempts during the cooldown do not create extra hands.
+
+## Installation preparation
+
+The repository includes its own README, license, TypeScript settings, tests,
+public assets, package metadata, and ignore rules. Its only GameHub code
+dependency is the exact `@masonf539/game-sdk` version declared in `package.json`.
+A lockfile will be generated after that SDK version is published so it records
+the registry artifact rather than the former 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 wait for another card before slapping again. 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 cannot slap the unchanged pile again, but may slap as soon as the next card is played.",
+        "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 and must wait for another card before trying 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 and must wait for another card before slapping again.",
+            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";
+/** Prevent repeated free slaps until one more card has been played. */
+export declare function startEgyptianWarSlapCooldown(state: EgyptianWarState, playerId: string): void;
+/**
+ * Returns the status of an eliminated player's slap cooldown. Once another
+ * card has been played, the cooldown clears and that new card may be slapped.
+ */
+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;