Golf Card Game

A real-time multiplayer 6-card Golf card game with AI opponents, smooth anime.js animations, and extensive house rules support.

Features

• Real-time Multiplayer: 2-6 players via WebSocket
• AI Opponents: 8 unique CPU personalities with distinct play styles
• House Rules: 15+ optional rule variants
• Smooth Animations: Anime.js-powered card dealing, drawing, swapping, and flipping
• User Accounts: Registration, login, email verification
• Stats & Leaderboards: Player statistics, win rates, and rankings
• Game Replay: Review completed games with full playback
• Admin Tools: User management, game moderation, system monitoring
• Event Sourcing: Full game history stored for replay and analysis
• Production Ready: Docker, systemd, nginx, rate limiting, Sentry integration

Quick Start

# Install dependencies
pip install -r server/requirements.txt

# Run the server
python server/main.py

# Visit http://localhost:8000

For full installation instructions (Docker, production deployment, etc.), see INSTALL.md.

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 2x3 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/                        # Python FastAPI backend
│   ├── main.py                    # HTTP routes, WebSocket server, lifespan
│   ├── game.py                    # Core game logic, state machine
│   ├── ai.py                      # CPU opponent AI with timing/personality
│   ├── handlers.py                # WebSocket message handlers
│   ├── room.py                    # Room/lobby management
│   ├── config.py                  # Environment configuration (pydantic)
│   ├── constants.py               # Card values, game constants
│   ├── auth.py                    # Authentication (JWT, passwords)
│   ├── logging_config.py          # Structured logging setup
│   ├── simulate.py                # AI-vs-AI simulation runner
│   ├── game_analyzer.py           # Decision analysis CLI
│   ├── score_analysis.py          # Score distribution analysis
│   ├── routers/                   # FastAPI route modules
│   │   ├── auth.py                # Login, signup, verify endpoints
│   │   ├── admin.py               # Admin management endpoints
│   │   ├── stats.py               # Statistics & leaderboard endpoints
│   │   ├── replay.py              # Game replay endpoints
│   │   └── health.py              # Health check endpoints
│   ├── services/                  # Business logic layer
│   │   ├── auth_service.py        # User authentication
│   │   ├── admin_service.py       # Admin tools
│   │   ├── stats_service.py       # Player statistics & leaderboards
│   │   ├── replay_service.py      # Game replay functionality
│   │   ├── game_logger.py         # PostgreSQL game move logging
│   │   ├── spectator.py           # Spectator mode
│   │   ├── email_service.py       # Email notifications (Resend)
│   │   ├── recovery_service.py    # Account recovery
│   │   └── ratelimit.py           # Rate limiting
│   ├── stores/                    # Data persistence layer
│   │   ├── event_store.py         # PostgreSQL event sourcing
│   │   ├── user_store.py          # User persistence
│   │   ├── state_cache.py         # Redis state caching
│   │   └── pubsub.py              # Pub/sub messaging
│   ├── models/                    # Data models
│   │   ├── events.py              # Event types for event sourcing
│   │   ├── game_state.py          # Game state representation
│   │   └── user.py                # User data model
│   ├── middleware/                 # Request middleware
│   │   ├── security.py            # CORS, CSP, security headers
│   │   ├── request_id.py          # Request ID tracking
│   │   └── ratelimit.py           # Rate limiting middleware
│   ├── RULES.md                   # Rules documentation
│   └── test_*.py                  # Test files
│
├── client/                        # Vanilla JS frontend
│   ├── index.html                 # Main game page
│   ├── app.js                     # Main game controller
│   ├── card-animations.js         # Unified anime.js animation system
│   ├── card-manager.js            # DOM management for cards
│   ├── animation-queue.js         # Animation sequencing
│   ├── timing-config.js           # Centralized timing configuration
│   ├── state-differ.js            # Diff game state for animations
│   ├── style.css                  # Styles (NO card transitions)
│   ├── admin.html                 # Admin panel
│   ├── admin.js                   # Admin panel interface
│   ├── admin.css                  # Admin panel styles
│   ├── replay.js                  # Game replay viewer
│   ├── leaderboard.js             # Leaderboard display
│   └── ANIMATIONS.md              # Animation system documentation
│
├── scripts/                       # Helper scripts
│   ├── install.sh                 # Interactive installer
│   ├── dev-server.sh              # Development server launcher
│   └── docker-build.sh            # Docker image builder
│
├── docs/                          # Architecture documentation
│   ├── ANIMATION-FLOWS.md         # Animation flow diagrams
│   ├── v2/                        # V2 architecture docs
│   └── v3/                        # V3 feature & refactoring docs
│
├── tests/e2e/                     # End-to-end tests (Playwright)
├── docker-compose.dev.yml         # Dev Docker services (PostgreSQL + Redis)
├── docker-compose.prod.yml        # Production Docker setup
├── Dockerfile                     # Container definition
├── pyproject.toml                 # Python project metadata
├── INSTALL.md                     # Installation & deployment guide
├── CLAUDE.md                      # Project context for AI assistants
└── README.md

Running Tests

# All server tests
cd server && pytest -v

# Specific test files
pytest test_game.py test_ai_decisions.py test_handlers.py test_room.py -v

# With coverage
pytest --cov=. --cov-report=term-missing

AI Simulation

# Run 500 games and check dumb move rate
python server/simulate.py 500

# Detailed single game output
python server/simulate.py 1 --detailed

# Compare rule presets
python server/simulate.py 100 --compare

# Analyze AI decisions for blunders
python server/game_analyzer.py blunders

# Score distribution analysis
python server/score_analysis.py 100

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.11+, FastAPI, WebSockets
• Frontend: Vanilla HTML/CSS/JavaScript, anime.js (animations)
• Database: PostgreSQL (event sourcing, auth, stats, game logs)
• Cache: Redis (state caching, pub/sub)
• Testing: pytest, Playwright (e2e)
• Deployment: Docker, systemd, nginx

License

GPL-3.0-or-later — see LICENSE for the full text.