All source listed below is under MIT license if no LICENSE file stating different is available.

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.

server
static
tests
.gitignore
Makefile
project_summary.md
pytest.ini
README.md
requirements.txt
run_tests.py
run.py
test_demo.py
TESTING_IMPROVEMENTS.md
TESTING.md
WARP.md