Golf Card Game

A multiplayer online 6-card Golf card game with AI opponents and extensive house rules support.

Features

• Multiplayer: 2-6 players via WebSocket
• AI Opponents: 8 unique CPU personalities with distinct play styles
• House Rules: 15+ optional rule variants
• Game Logging: SQLite logging for AI decision analysis
• Comprehensive Testing: 80+ tests for rules and AI behavior

Quick Start

1. Install Dependencies

cd server
pip install -r requirements.txt

2. Start the Server

cd server
uvicorn main:app --reload --host 0.0.0.0 --port 8000

3. Open the Game

Open http://localhost:8000 in your browser.

How to Play

6-Card Golf is a card game where you try to get the lowest score across multiple rounds (holes).

• Each player has 6 cards in a 2×3 grid (most start face-down)
• On your turn: draw a card, then swap it with one of yours or discard it
• Column pairs (same rank top & bottom) score 0 points — very powerful!
• When any player reveals all 6 cards, everyone else gets one final turn
• Lowest total score after all rounds wins

For detailed rules, card values, and house rule explanations, see the in-game Rules page or server/RULES.md.

AI Personalities

Name	Style	Description
Sofia	Calculated & Patient	Conservative, low risk
Maya	Aggressive Closer	Goes out early
Priya	Pair Hunter	Holds cards hoping for pairs
Marcus	Steady Eddie	Balanced, consistent
Kenji	Risk Taker	High variance plays
Diego	Chaotic Gambler	Unpredictable
River	Adaptive Strategist	Adjusts to game state
Sage	Sneaky Finisher	Aggressive end-game

House Rules

The game supports 15+ optional house rules including:

• Flip Modes - Standard, Speed Golf (must flip after discard), Suspense (optional flip near endgame)
• Point Modifiers - Super Kings (-2), Ten Penny (10=1), Lucky Swing Joker (-5)
• Bonuses & Penalties - Knock bonus/penalty, Underdog bonus, Tied Shame, Blackjack (21→0)
• Joker Variants - Standard, Eagle Eye (paired Jokers = -8)

See the in-game Rules page or server/RULES.md for complete explanations.

Development

Project Structure

golfgame/
├── server/
│   ├── main.py              # FastAPI WebSocket server
│   ├── game.py              # Core game logic
│   ├── ai.py                # AI decision making
│   ├── room.py              # Room/lobby management
│   ├── game_log.py          # SQLite logging
│   ├── game_analyzer.py     # Decision analysis CLI
│   ├── simulate.py          # AI-vs-AI simulation
│   ├── score_analysis.py    # Score distribution analysis
│   ├── test_game.py         # Game rules tests
│   ├── test_analyzer.py     # Analyzer tests
│   ├── test_maya_bug.py     # Bug regression tests
│   ├── test_house_rules.py  # House rules testing
│   └── RULES.md             # Rules documentation
├── client/
│   ├── index.html
│   ├── style.css
│   └── app.js
└── README.md

Running Tests

cd server
pytest test_game.py test_analyzer.py test_maya_bug.py -v

AI Simulation

# Run 50 games with 4 AI players
python simulate.py 50 4

# Run detailed single game
python simulate.py detail 4

# Analyze AI decisions for blunders
python game_analyzer.py blunders

# Score distribution analysis
python score_analysis.py 100 4

# Test all house rules
python test_house_rules.py 40

AI Performance

From testing (1000+ games):

• 0 blunders detected in simulation
• Median score: 12 points
• Score range: -4 to 34 (typical)
• Personalities influence style without compromising competence

Technology Stack

• Backend: Python 3.12+, FastAPI, WebSockets
• Frontend: Vanilla HTML/CSS/JavaScript
• Database: SQLite (optional, for game logging)
• Testing: pytest

License

MIT