City Builder Multiplayer Game 🎮

STATUS: ✅ COMPLETE AND READY TO PLAY

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

🚀 Quick Start

# 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

• Create directory structure
• Setup backend skeleton
• Setup frontend skeleton
• Database schema

✅ Phase 2: Backend Core

• FastAPI server setup
• WebSocket manager
• Database models
• Game state manager
• Economy system
• Player authentication (nickname-based)

✅ Phase 3: Frontend Core

• Three.js scene setup
• Tile rendering system
• Camera controls (zoom, pan)
• Input handling
• WebSocket client

✅ Phase 4: Game Mechanics

• Building placement
• Building types implementation
• Road connectivity algorithm
• Economy calculations
• Building interactions

✅ Phase 5: UI Components

• Login screen
• Stats display (money, population)
• Building toolbox
• Context menu
• Chat system

✅ Phase 6: Multiplayer

• Cursor synchronization
• Building synchronization
• Player colors
• Chat messages

🚧 Phase 7: Ready for Testing

• Core gameplay complete
• 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.