PseuDos – (Pusoy Dos Variant)

A reimagined, single-player variant of the popular card-shedding game Pusoy Dos.
PseuDos combines a premium “Velvet Table” casino aesthetic with a deterministic rules engine and an optional AI opponent powered by modern LLMs (OpenAI / Anthropic).

🚀 Features

• Single-player vs AI opponent

  • Play against a computer opponent that understands Pusoy-Dos–style shedding strategy.
  • Deterministic TypeScript AI for legality and baseline strategy.
  • Optional LLM policy layer (configurable) for more human-like move selection.

• Card shedding mechanics

  • Classic objective: shed all your cards before the opponent.
  • Supports singles, pairs, and 5‑card hands (straight / triple+two variants).
  • Round flow: play to beat the previous hand or draw and reset the round.

• Velvet Table redesign

  • Dark felt background with gold accents and suit glyph decoration.
  • Custom PlayingCard and CardBack components with multiple deck themes and card-back patterns.
  • Smooth entry animations for opponent hand, table, actions, and player hand.
  • Native pointer-based free-form hand workspace (no react-dnd).

• Options & themes

  • In‑game Options overlay for:
    • Table themes (Emerald, Midnight, Burgundy).
    • Deck styles (color variants).
    • Card-back patterns.
  • Options are persisted to localStorage and restored on load.

• Stats & persistence

  • Tracks player and AI win counts.
  • Stats are persisted to localStorage.

• Win/lose UX polish

  • Win/lose overlay delayed briefly so the final play remains visible.
  • Overlay includes confetti for wins, a close “×” button, and a Play Again CTA.
  • Additional Play Again button in the main table area once a game concludes.

• Responsive layout

  • Designed for desktop first, with responsive tweaks for smaller viewports.

📖 Rules Overview

This game borrows elements from Pusoy Dos while introducing its own flavor:

1. Objective

   • Be the first player to shed all your cards.

2. Gameplay

   • Players take turns playing:
     • A single card.
     • A pair (two cards of the same rank).
     • A 5‑card hand (valid straights or triple+two).
   • To beat the previous play:
     • You must play the same type (single vs single, pair vs pair, 5‑card vs 5‑card).
     • Your play must outrank the previous one according to the game’s rank/suit rules.
   • If you cannot or do not want to beat the current play, you draw a card and the round resets.

3. Deck and suit values

   • Deck: Standard 52‑card deck.
   • Suit hierarchy (ascending): ♠ (lowest), ♣, ♦, ♥ (highest).
   • Rank hierarchy (ascending): 2, 3, …, 10, J, Q, K, A.

4. Winning a round

   • When an opponent cannot beat your play and must draw, you effectively “win” that exchange and will be able to lead the next trick once the reset occurs.

5. Winning the game

   • The first player to shed all of their cards wins immediately.

For deeper details of the rules and AI behavior, see:

• app/components/contexts/GameRules.ts
• app/components/contexts/AIGameStrategy.ts
• Docs/design/AI-implementation/AI-implementation.md

🛠️ Tech Stack

• Framework: Next.js (App Router), React 18, TypeScript.
• State management: React Context (GameContext.tsx).
• Styling:
  • Global CSS (app/globals.css) with CSS variables for felt, gold, cards, and animations.
  • Inline styles for most components (no runtime TailwindCSS; tailwind-merge only for utility helpers).
• AI opponent:
  • Deterministic engine in AIGameStrategy.ts and GameRules.ts.
  • Optional LLM policy layer via /api/ai-move using OpenAI and/or Anthropic.

📦 Installation

To run this project locally:

1. Clone the repository:

   git clone https://github.com/georgebprice/PseudosCardGame.git
   cd Pseudos-CardGame

2. Install dependencies:

   npm install

3. Run the development server:

   npm run dev

4. Open your browser and navigate to:

   http://localhost:3000
   

🎮 How to Play (In This UI)

1. Start from the Velvet Table start screen and click Start Game.
2. On your turn:
   • Click cards in your hand to move them into the staging area.
   • Use the ✕ button to clear your selection if needed.
   • Click Choose Cards / Play Single / Play Double / Play Hand to commit a valid play.
   • Or click Draw Card to draw and reset the round if you cannot (or do not want to) beat the current play.
3. The computer will “think” for a moment and then play or draw.
4. Turns alternate until one side sheds all their cards.
5. When the win/lose overlay appears, you can:
   • Inspect the final table state.
   • Close the overlay with the ×.
   • Use Play Again (overlay or table button) to start a fresh game.

🤖 AI Opponent Modes & Configuration

By default, the game can run entirely on the deterministic AI. You can optionally enable the LLM policy layer.

Modes

Set in your environment as:

NEXT_PUBLIC_AI_OPPONENT_MODE=deterministic | llm | hybrid

• deterministic:
  • Uses only the TypeScript AI (chooseBestPlay).
• llm:
  • Uses deterministic AI to enumerate legal candidates.
  • Uses the LLM to choose among them, with:
    • Strict validation.
    • Strategy guardrails (e.g. avoid burning aces early when low singles exist).
    • Deterministic fallback on any invalid/off-strategy output.
  • The first AI move in each game is deterministic for stability.
• hybrid:
  • Like llm, but the first three AI moves in each game are deterministic before the LLM is consulted.

LLM configuration

Configure your .env (see .env.example):

OPENAI_API_KEY=...
OPENAI_API_MODEL=gpt-4o-mini
ANTHROPIC_API_KEY=...
ANTHROPIC_API_MODEL=...
AI_DEFAULT_PROVIDER=openai        # or "anthropic"
AI_REQUEST_TIMEOUT_MS=8000
AI_MAX_OUTPUT_TOKENS=350
ENVIRONMENT=development           # enables detailed AI logging

The AI design and implementation are documented in more detail in:

• Docs/design/AI-implementation/AI-implementation.md

🛠️ Planned / Coming Soon

• Difficulty & personality controls:
  • Expose AI difficulty in the UI (easy/normal/hard).
  • Tweak candidate selection and sampling accordingly.
• Multiplayer mode:
  • Online and/or local hot-seat support.
• Persistent profiles & stats:
  • Move stats and options from localStorage to a backend.
  • Per-user histories and leaderboards.
• Security & robustness:
  • Server-side rate limiting and stricter guardrails for /api/ai-move.
  • Additional evaluation scenarios to tune AI behavior.

📧 Contact

For questions or suggestions, feel free to contact me:

• GitHub: GeorgeBPrice
• Email: ...