alee/golfgame
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

v3.0.0: V3 features, server refactoring, and documentation overhaul

Browse Source 
- Extract WebSocket handlers from main.py into handlers.py
- Add V3 feature docs (dealer rotation, dealing animation, round end reveal,
  column pair celebration, final turn urgency, opponent thinking, score tallying,
  card hover/selection, knock early drama, column pair indicator, swap animation
  improvements, draw source distinction, card value tooltips, active rules context,
  discard pile history, realistic card sounds)
- Add V3 refactoring docs (ai.py, main.py/game.py, misc improvements)
- Add installation guide with Docker, systemd, and nginx setup
- Add helper scripts (install.sh, dev-server.sh, docker-build.sh)
- Add animation flow diagrams documentation
- Add test files for handlers, rooms, and V3 features
- Add e2e test specs for V3 features
- Update README with complete project structure and current tech stack
- Update CLAUDE.md with full architecture tree and server layer descriptions
- Update .env.example to reflect PostgreSQL (remove SQLite references)
- Update .gitignore to exclude virtualenv files, .claude/, and .db files
- Remove tracked virtualenv files (bin/, lib64, pyvenv.cfg)
- Remove obsolete game_log.py (SQLite) and games.db

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
adlee-was-taken
2026-02-14 10:03:45 -05:00
parent 13ab5b9017
commit 9fc6b83bba
60 changed files with 11791 additions and 1639 deletions
Download Patch File Download Diff File Expand all files Collapse all files

173
README.md
View File

@@ -1,40 +1,39 @@
# Golf Card Game
A multiplayer online 6-card Golf card game with AI opponents and extensive house rules support.
A real-time multiplayer 6-card Golf card game with AI opponents, smooth anime.js animations, and extensive house rules support.
## Features
- **Multiplayer:** 2-6 players via WebSocket
- **Real-time 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
- **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
### 1. Install Dependencies
```bash
cd server
pip install -r requirements.txt
# Install dependencies
pip install -r server/requirements.txt
# Run the server
python server/main.py
# Visit http://localhost:8000
```
### 2. Start the Server
```bash
cd server
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```
### 3. Open the Game
Open `http://localhost:8000` in your browser.
For full installation instructions (Docker, production deployment, etc.), see [INSTALL.md](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 2×3 grid (most start face-down)
- 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
@@ -61,7 +60,7 @@ 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)
- **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](server/RULES.md) for complete explanations.
@@ -72,51 +71,117 @@ See the in-game Rules page or [server/RULES.md](server/RULES.md) for complete ex
```
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
├── 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
```bash
cd server
pytest test_game.py test_analyzer.py test_maya_bug.py -v
# 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
```bash
# Run 50 games with 4 AI players
python simulate.py 50 4
# Run 500 games and check dumb move rate
python server/simulate.py 500
# Run detailed single game
python simulate.py detail 4
# 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 game_analyzer.py blunders
python server/game_analyzer.py blunders
# Score distribution analysis
python score_analysis.py 100 4
# Test all house rules
python test_house_rules.py 40
python server/score_analysis.py 100
```
### AI Performance
@@ -129,10 +194,12 @@ From testing (1000+ games):
## Technology Stack
- **Backend:** Python 3.12+, FastAPI, WebSockets
- **Frontend:** Vanilla HTML/CSS/JavaScript
- **Database:** SQLite (optional, for game logging)
- **Testing:** pytest
- **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