city/README.md

# City Builder Multiplayer Game 🎮

**STATUS: ✅ COMPLETE AND READY TO PLAY**

Transport Tycoon-style city building game with real-time multiplayer functionality.

## 🚀 Quick Start

```bash
# 1. Setup
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# 2. Run
python run.py

# 3. Play
Open http://127.0.0.1:9901 in your browser
```

## Features
- Real-time multiplayer via WebSockets
- Transport Tycoon visual style
- Persistent economy system
- 10+ building types with unique benefits
- Road connectivity system
- Player-specific colors
- Live cursor tracking
- IRC-style chat
- Offline economy processing (10% power)

## Technology Stack
- **Backend**: FastAPI, SQLite, WebSockets
- **Frontend**: Three.js (vanilla JS)
- **Server**: 127.0.0.1:9901

## Progress Tracker

### ✅ Phase 1: Project Structure
- [x] Create directory structure
- [x] Setup backend skeleton
- [x] Setup frontend skeleton
- [x] Database schema

### ✅ Phase 2: Backend Core
- [x] FastAPI server setup
- [x] WebSocket manager
- [x] Database models
- [x] Game state manager
- [x] Economy system
- [x] Player authentication (nickname-based)

### ✅ Phase 3: Frontend Core
- [x] Three.js scene setup
- [x] Tile rendering system
- [x] Camera controls (zoom, pan)
- [x] Input handling
- [x] WebSocket client

### ✅ Phase 4: Game Mechanics
- [x] Building placement
- [x] Building types implementation
- [x] Road connectivity algorithm
- [x] Economy calculations
- [x] Building interactions

### ✅ Phase 5: UI Components
- [x] Login screen
- [x] Stats display (money, population)
- [x] Building toolbox
- [x] Context menu
- [x] Chat system

### ✅ Phase 6: Multiplayer
- [x] Cursor synchronization
- [x] Building synchronization
- [x] Player colors
- [x] Chat messages

### 🚧 Phase 7: Ready for Testing
- [x] Core gameplay complete
- [x] All features implemented
- [ ] Needs real-world testing
- [ ] Performance optimization TBD
- [ ] Bug fixes as discovered

## Installation

```

## Troubleshooting

### Server won't start
- Check if port 9901 is already in use
- Ensure all dependencies are installed: `pip install -r requirements.txt`
- Make sure you're in the virtual environment

### Can't connect to WebSocket
- Verify server is running on http://127.0.0.1:9901
- Check browser console for connection errors
- Try refreshing the page

### Buildings not appearing
- Check that WebSocket connection is established
- Look for errors in browser console
- Verify server logs for any exceptions

### Performance issues
- Close other browser tabs
- Reduce browser zoom level
- The game only renders visible tiles for optimization

### Database errors
- Delete the `data/game.db` file to reset
- Ensure `data/` directory exists
- Check file permissions

## Technical Details

### Architecture
- **Backend**: FastAPI with WebSocket support
- **Frontend**: Three.js for 3D rendering (orthographic view)
- **Database**: SQLite for persistence
- **Communication**: WebSocket for real-time multiplayer

### Performance Optimizations
- Only visible tiles are rendered
- Cursor position updates are throttled (100ms)
- Database saves every 10 seconds
- Viewport culling for rendering

### Data Persistence
- Game state saved to SQLite every 10 seconds
- Players reconnect using their nickname
- Offline economy continues at 10% power
- Buildings persist across sessions

## Future Enhancements (Not Implemented)

- Sound effects
- More building types
- Advanced road types (highways, bridges)
- City happiness/satisfaction metrics
- Natural disasters or random events
- Building upgrades
- Trade system between players
- Leaderboards
- Mobile responsiveness

## License

This is an educational project created following Transport Tycoon's visual style for a multiplayer city building game.

## Credits

Created using:
- FastAPI for backend
- Three.js for 3D rendering
- WebSockets for real-time communication
- SQLite for data storagebash
# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run server (Option 1 - using run script)
python run.py

# Run server (Option 2 - direct command)
python -m uvicorn server.main:app --host 127.0.0.1 --port 9901 --reload

# Open browser and navigate to:
# http://127.0.0.1:9901
```

## Quick Start Guide

1. **Launch the game** - Start the server and open http://127.0.0.1:9901
2. **Enter nickname** - Type your nickname and press Enter
3. **Start building** - You begin with $100,000
4. **Build roads first** - Roads connect buildings and boost economy
5. **Build houses** - Houses provide population for commercial buildings
6. **Build shops** - Shops generate income but need population
7. **Expand your city** - Connect buildings with roads for economy bonuses
8. **Chat with others** - Use the chat box to communicate with other players

## Gameplay Tips

### Starting Strategy
1. Start with a few **Small Houses** to build population
2. Build a **Road** network to connect your buildings
3. Add **Small Shops** once you have 20+ population
4. Build a **Power Plant** before adding large buildings
5. Connect everything with roads for economy boosts

### Economy Optimization
- **Road connections matter!** Buildings connected to larger road networks produce more income
- Each road in a connected zone adds **5% income boost** to commercial/industrial buildings
- Balance income vs. expenses - some buildings cost money per tick
- Population affects commercial building income
- Industrial buildings provide jobs (negative population)

### Building Synergies
- **Houses + Shops**: Houses provide population, shops need population
- **Factories + Power Plants**: Large factories need power
- **Roads + Everything**: Roads boost all connected buildings
- **Parks/Plazas**: Increase population happiness (future feature potential)

### Multiplayer Strategy
- Watch other players' cities for inspiration
- Your economy runs at 10% power when offline
- Protect your buildings - only you can delete them
- Use chat to coordinate with other players
- Build near roads for maximum connectivity

## Building Types

1. **Residential**
   - Small House: +10 population, -$50/tick
   - Medium House: +25 population, -$120/tick
   - Large House: +50 population, -$250/tick

2. **Commercial**
   - Small Shop: +$100/tick, requires 20 population
   - Supermarket: +$300/tick, requires 50 population
   - Mall: +$800/tick, requires 100 population

3. **Industrial**
   - Small Factory: +$200/tick, -20 population (jobs)
   - Large Factory: +$500/tick, -50 population

4. **Infrastructure**
   - Road: Connects buildings, boosts economy
   - Park: +5 population happiness
   - Plaza: +10 population happiness

5. **Special**
   - Town Hall: Required for city, +100 max population
   - Power Plant: Required for large buildings

## Economy System

- Base tick: Every 10 seconds
- Offline processing: 10% power
- Building costs are realistic
- Income based on building type and connectivity
- Population affects commercial income
- Roads create economic zones

## Controls

- **Right Mouse**: Hold to pan camera
- **Mouse Wheel**: Zoom in/out
- **Left Click**: Place building / Select tile
- **Right Click on Building**: Context menu
- **Enter**: Send chat message / Confirm input
- **Escape**: Cancel input

## File Structure

```
city-builder/
├── server/
│   ├── main.py              # FastAPI app
│   ├── websocket_manager.py # WebSocket handling
│   ├── game_state.py        # Game state management
│   ├── economy.py           # Economy calculations
│   ├── database.py          # SQLite operations
│   └── models.py            # Data models
├── static/
│   ├── index.html           # Main HTML
│   ├── js/
│   │   ├── App.js          # Main app class
│   │   ├── GameRenderer.js # Three.js renderer
│   │   ├── InputHandler.js # Input management
│   │   ├── WebSocketClient.js # WS client
│   │   ├── UIManager.js    # UI components
│   │   └── components/
│   │       ├── LoginScreen.js
│   │       ├── StatsDisplay.js
│   │       ├── BuildingToolbox.js
│   │       ├── ContextMenu.js
│   │       └── ChatBox.js
│   └── css/
│       └── style.css        # Styling
├── data/
│   └── game.db             # SQLite database
├── requirements.txt
└── README.md
```

## Current Status
**All core features implemented and ready for testing!**

The game is fully functional with:
- ✅ Multiplayer WebSocket connections
- ✅ Real-time cursor and building synchronization
- ✅ 13 different building types with unique economics
- ✅ Road connectivity system with economy boosts
- ✅ Offline economy processing (10% power)
- ✅ IRC-style chat
- ✅ Context menus for building management
- ✅ Camera controls (pan, zoom)
- ✅ Persistent database storage

Ready to play! See installation instructions below.