city/WARP.md

# WARP.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

## Development Commands

### Quick Start
```bash
# Create virtual environment and install dependencies
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# Run the game server
python run.py
# Or directly:
python -m uvicorn server.main:app --host 127.0.0.1 --port 9901 --reload

# Access the game at http://127.0.0.1:9901
```

### Development Commands
```bash
# Start in development mode (auto-reload)
python -m uvicorn server.main:app --host 127.0.0.1 --port 9901 --reload

# Check database state (SQLite browser or CLI)
sqlite3 data/game.db

# Reset game state (delete database)
rm data/game.db

# Monitor logs (server runs with debug logging)
# Logs are printed to stdout
```

### Dependencies
- **Backend**: FastAPI 0.118.0, uvicorn, websockets, pydantic
- **Frontend**: Three.js (via CDN), vanilla JavaScript ES6 modules
- **Database**: SQLite (built-in Python)

## Architecture Overview

### System Architecture
This is a **real-time multiplayer city building game** with a FastAPI backend and Three.js frontend, using WebSockets for live communication.

**Key architectural patterns:**
- **Real-time multiplayer**: WebSocket-based with instant synchronization
- **Component-based UI**: Web Components extending HTMLElement
- **ES6 Module system**: No bundling required, direct module imports
- **Persistent game state**: SQLite with auto-save every 10 seconds
- **Hybrid economy system**: Instant updates on player actions + timed background processing

### Backend Architecture (`server/` directory)

**Core Components:**
- `main.py` - FastAPI app with WebSocket endpoints and game lifecycle
- `websocket_manager.py` - Connection management, broadcasting, player sessions
- `game_state.py` - Building placement, road connectivity (flood-fill), validation
- `economy.py` - Economy calculations with connectivity bonuses
- `database.py` - SQLite persistence layer
- `models.py` - Data models (13 building types, player stats)

**Key algorithms:**
- **Road connectivity**: Flood-fill algorithm to calculate connected road zones
- **Economy bonuses**: Buildings connected to roads get 5% bonus per road in the zone
- **Offline processing**: Players earn 10% income when offline

### Frontend Architecture (`static/js/` directory)

**Main Classes:**
- `App.js` - Central coordinator, manages all systems
- `GameRenderer.js` - Three.js orthographic rendering, viewport culling
- `WebSocketClient.js` - Real-time communication with auto-reconnect
- `InputHandler.js` - Mouse/keyboard input, camera controls
- `UIManager.js` - Coordinates Web Components

**UI Components** (`static/js/components/`):
- `LoginScreen.js` - Nickname entry
- `StatsDisplay.js` - Money and population
- `BuildingToolbox.js` - Building selection with affordability checks
- `ChatBox.js` - IRC-style multiplayer chat
- `ContextMenu.js` - Right-click building actions

### Game Logic

**Building System:**
- 13 building types across 5 categories (Residential, Commercial, Industrial, Infrastructure, Special)
- Complex requirement system (population, power, affordability)
- Player ownership with edit/delete permissions

**Economy System:**
- Tick-based (every 10 seconds)
- Road connectivity creates economic zones
- Offline players continue at 10% power
- Instant updates on building placement/removal

**Multiplayer Features:**
- Nickname-based authentication (no passwords)
- Real-time cursor synchronization (throttled to 100ms)
- Building synchronization across all clients
- Player-specific colors
- Live chat system

## Development Guidelines

### When modifying game mechanics:
- Update `BUILDING_CONFIGS` in `models.py` for building properties
- Modify `economy.py` for income/cost calculations
- Road connectivity logic is in `game_state.py` (`_update_connected_zones`)

### When adding UI features:
- Create new Web Components extending HTMLElement
- Register components in `UIManager.js`
- Follow the pattern of existing components for consistency

### When modifying multiplayer:
- WebSocket message types are defined in `websocket_manager.py`
- All state changes should broadcast to other players
- Client-side optimistic updates in `App.js`

### Performance considerations:
- Renderer uses viewport culling (only renders visible tiles)
- Economy calculations are batched per tick
- WebSocket messages are throttled appropriately
- Database saves every 10 seconds (not on every action)

### Database schema:
- Players: player_id, nickname, money, population, color, last_online
- Buildings: type, x, y, owner_id, name, placed_at
- Auto-migration handled in `database.py`

## Game State Management

**Critical state synchronization points:**
1. **Building placement** - Validates requirements, deducts money, broadcasts to all clients
2. **Economy ticks** - Updates player money/population, triggers UI updates
3. **Player connections** - Manages online/offline status, session resumption
4. **Road network changes** - Recalculates connected zones for economy bonuses

**Testing multiplayer:**
1. Open multiple browser tabs with different nicknames
2. Verify building synchronization across clients  
3. Test chat functionality
4. Verify cursor movement synchronization
5. Test offline/online player transitions

## File Structure Context

```
server/           # Python FastAPI backend
├── main.py       # App entry, WebSocket endpoints, game loop
├── websocket_manager.py  # Connection management
├── game_state.py # Building logic, road connectivity
├── economy.py    # Economic calculations  
├── database.py   # SQLite persistence
└── models.py     # Data structures, building configs

static/           # Frontend (served statically)
├── index.html    # Single-page app
├── js/
│   ├── App.js           # Main coordinator
│   ├── GameRenderer.js  # Three.js rendering
│   ├── WebSocketClient.js # Real-time communication
│   ├── InputHandler.js  # Input management
│   ├── UIManager.js     # Component coordination
│   └── components/      # Web Components
└── css/style.css # Transport Tycoon-inspired styling

data/game.db      # SQLite database (auto-created)
run.py           # Convenience startup script
```

This is a **complete, production-ready multiplayer game** with persistent state, real-time communication, and sophisticated game mechanics. The codebase follows modern patterns and is well-structured for maintenance and feature additions.

## Testing Framework

### Test Commands
```bash
# Install test dependencies (if not already installed)
pip install -r requirements.txt

# Run all tests
pytest

# Run specific test categories
pytest tests/test_economy.py          # Economy system tests
pytest tests/test_multiplayer.py      # Multiplayer interaction tests  
pytest tests/test_game_state.py       # Game state and persistence tests
pytest tests/test_integration.py      # End-to-end integration tests

# Run with verbose output
pytest -v

# Run specific test
pytest tests/test_economy.py::TestEconomySystem::test_building_costs -v

# Run tests with coverage (if coverage installed)
pytest --cov=server
```

### Test Architecture

**Test Client Utility** (`tests/test_client.py`):
- `TestWebSocketClient` - Simulates real WebSocket connections
- `test_clients()` context manager for multiple simultaneous clients
- Full API coverage: building placement, chat, cursor movement, etc.

**Test Categories:**
1. **Economy Tests** (`test_economy.py`) - Building costs, income calculations, road bonuses
2. **Multiplayer Tests** (`test_multiplayer.py`) - Chat, cursor sync, building synchronization
3. **Game State Tests** (`test_game_state.py`) - Database persistence, validation, state management
4. **Integration Tests** (`test_integration.py`) - End-to-end scenarios, stress testing

### Running Tests with Game Server

**Important**: Tests require the game server to be running on `127.0.0.1:9901`.

```bash
# Terminal 1: Start the server
python run.py

# Terminal 2: Run tests (in separate terminal)
pytest
```

### Test Coverage

**WebSocket API Coverage:**
- Building placement/removal with validation
- Chat message broadcasting
- Cursor movement synchronization 
- Player join/leave notifications
- Error handling and edge cases

**Economy System Coverage:**
- Building cost deduction
- Income/expense calculations
- Road connectivity bonuses (5% per road in network)
- Offline player processing (10% income)
- Population and power requirements

**Multiplayer Scenarios:**
- Multiple simultaneous connections
- Real-time synchronization between clients
- Building ownership and permissions
- Competitive and collaborative gameplay

**Database Persistence:**
- Save/load complete game state
- Player reconnection with preserved data
- Building persistence across sessions

### Testing Guidelines

**When adding new features:**
1. Add unit tests for core logic
2. Add WebSocket integration tests for client interactions
3. Update integration tests for end-to-end scenarios
4. Test multiplayer synchronization

**Test Database:**
- Tests use temporary databases to avoid affecting game data
- Database operations are tested with isolated fixtures
- Game state persistence is validated through reconnection tests

**Async Test Patterns:**
- All WebSocket tests use `@pytest.mark.asyncio`
- Tests simulate real timing with `asyncio.sleep()`
- Message collection uses timeouts to handle async communication

### Stress Testing

The test suite includes stress tests for:
- Rapid building placement (20+ simultaneous actions)
- Chat message floods (30+ messages)
- Mixed action types (building + chat + cursor movement)
- Multiple player scenarios (4+ simultaneous clients)