golfgame/CLAUDE.md

Golf Card Game - Project Context

A real-time multiplayer 6-card Golf card game with CPU opponents and smooth anime.js animations.

Quick Start

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

# Run the server
python server/main.py

# Visit http://localhost:5000

Architecture

golfgame/
├── server/           # Python FastAPI backend
│   ├── main.py       # HTTP routes, WebSocket handling
│   ├── game.py       # Game logic, state machine
│   └── ai.py         # CPU opponent AI with timing/personality
│
├── client/           # Vanilla JS frontend
│   ├── 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)
│   └── ANIMATIONS.md       # Animation system documentation
│
└── docs/v3/          # Feature planning documents

Key Technical Decisions

Animation System

All card animations use anime.js. No CSS transitions on card elements.

• See client/ANIMATIONS.md for full documentation
• CardAnimations class in card-animations.js handles everything
• Timing configured in timing-config.js

State Management

• Server is source of truth
• Client receives full game state on each update
• state-differ.js computes diffs to trigger appropriate animations
• isDrawAnimating flag prevents UI updates during animations

CPU Players

• AI logic in server/ai.py
• Configurable timing delays for natural feel
• Multiple personality types affect decision-making

Common Development Tasks

Adjusting Animation Speed

Edit timing-config.js - all timings are centralized there.

Adding New Animations

1. Add method to CardAnimations class in card-animations.js
2. Use anime.js, not CSS transitions
3. Track in activeAnimations Map for cancellation support
4. Add timing config to timing-config.js if needed

Debugging Animations

// Check what's animating
console.log(window.cardAnimations.activeAnimations);

// Force cleanup
window.cardAnimations.cancelAll();

// Check timing config
console.log(window.TIMING);

Testing CPU Behavior

Adjust delays in server/ai.py CPU_TIMING dict.

Important Patterns

No CSS Transitions on Cards

Cards animate via anime.js only. The following should NOT have transition:

• .card, .card-inner
• .real-card, .swap-card
• .held-card-floating

Animation Overlays

Complex animations create temporary overlay elements:

1. Create .draw-anim-card positioned over source
2. Hide original card
3. Animate overlay
4. Remove overlay, reveal updated card

Fire-and-Forget for Opponents

Opponent animations don't block - no callbacks needed:

cardAnimations.animateOpponentFlip(cardElement, cardData);

Dependencies

Server

• FastAPI
• uvicorn
• websockets

Client

• anime.js (animations)
• No other frameworks

Game Rules Reference

• 6 cards per player in 2x3 grid
• Lower score wins
• Matching columns cancel out (0 points)
• Jokers are -2 points
• Kings are 0 points
• Game ends when a player flips all cards