Projects / city / project_summary.md

git clone https://molodetz.nl/retoor/city.git

Raw source file available here . 

# City Builder - Project Summary

Project Overview

A fully functional multiplayer city building game inspired by Transport Tycoon's visual style, built with FastAPI backend and Three.js frontend.

What Was Built

Backend (Python/FastAPI)

All backend files are in the server/ directory:

  1. main.py - FastAPI application entry point

    • WebSocket endpoint for multiplayer
    • Static file serving
    • Game loop for economy ticks and persistence

  2. websocket_manager.py - WebSocket connection management

    • Player connection/disconnection
    • Message broadcasting
    • Cursor synchronization

  3. models.py - Data models

    • 13 building types with unique properties
    • Player model with economy tracking
    • Building configurations with costs and benefits

  4. game_state.py - Game state management

    • Building placement/removal logic
    • Road network connectivity (flood fill algorithm)
    • Zone size calculation for economy bonuses

  5. economy.py - Economy engine

    • Tick-based economy processing
    • Offline player support (10% power)
    • Connectivity-based income bonuses

  6. database.py - SQLite persistence

    • Auto-save every 10 seconds
    • Player data persistence
    • Building state persistence

Frontend (JavaScript/Three.js)

All frontend files are in the static/ directory:

  1. App.js - Main application controller

    • Coordinates all systems
    • Handles game state updates
    • Player action processing

  2. WebSocketClient.js - Real-time communication

    • WebSocket connection management
    • Message handling and routing
    • Auto-reconnect logic

  3. GameRenderer.js - Three.js 3D rendering

    • Orthographic camera (Transport Tycoon style)
    • Building mesh creation
    • Tile highlighting
    • Player cursor rendering

  4. InputHandler.js - User input processing

    • Mouse controls (left/right click, wheel)
    • Keyboard shortcuts
    • Camera pan and zoom
    • Tile coordinate conversion

  5. UIManager.js - UI component coordination

    • Component initialization
    • State updates
    • Event routing

UI Components (Web Components)

All components extend HTMLElement:

  1. LoginScreen.js - Nickname entry screen
  2. StatsDisplay.js - Money and population display
  3. BuildingToolbox.js - Building selection menu
  4. ChatBox.js - IRC-style chat interface
  5. ContextMenu.js - Right-click building menu

Configuration Files

  • requirements.txt - Python dependencies
  • .gitignore - Git ignore rules
  • run.py - Convenient startup script
  • README.md - Complete documentation

Key Features Implemented

Core Gameplay

  • ✅ 13 unique building types (houses, shops, factories, infrastructure, special)
  • ✅ Realistic building costs ($500 - $100,000)
  • ✅ Economic system with income/expenses per tick
  • ✅ Population management
  • ✅ Building requirements (population, power)

Road System

  • ✅ Road construction ($500 per tile)
  • ✅ Connectivity algorithm (flood fill)
  • ✅ Economy bonuses based on network size (5% per road)
  • ✅ Multiple disconnected zones support

Multiplayer

  • ✅ Real-time WebSocket communication
  • ✅ Live cursor synchronization
  • ✅ Building synchronization across clients
  • ✅ Player-specific colors
  • ✅ Join/leave notifications
  • ✅ IRC-style chat system

Persistence

  • ✅ SQLite database storage
  • ✅ Auto-save every 10 seconds
  • ✅ Nickname-based login (no passwords)
  • ✅ Offline economy processing (10%)
  • ✅ Session resumption

User Interface

  • ✅ Login screen (Enter to submit)
  • ✅ Stats display (money, population)
  • ✅ Building toolbox with prices
  • ✅ Grayed out unaffordable options
  • ✅ Context menu (Edit/Delete)
  • ✅ Chat box with timestamps
  • ✅ No buttons - keyboard shortcuts

Controls

  • ✅ Right mouse drag - Pan camera
  • ✅ Mouse wheel - Zoom in/out
  • ✅ Left click - Place building
  • ✅ Right click on building - Context menu
  • ✅ Enter - Confirm input
  • ✅ Escape - Cancel input
  • ✅ Tile highlighting on hover

Rendering Optimization

  • ✅ Viewport culling (only render visible tiles)
  • ✅ Throttled cursor updates (100ms)
  • ✅ Efficient building mesh management
  • ✅ Three.js orthographic camera for performance

Game Mechanics

Building Types & Economics

Residential (Provide Population)

  • Small House: -$50/tick, +10 pop
  • Medium House: -$120/tick, +25 pop
  • Large House: -$250/tick, +50 pop

Commercial (Generate Income)

  • Small Shop: +$100/tick, -5 pop, needs 20 pop
  • Supermarket: +$300/tick, -15 pop, needs 50 pop
  • Mall: +$800/tick, -40 pop, needs 100 pop

Industrial (Generate Income)

  • Small Factory: +$200/tick, -20 pop
  • Large Factory: +$500/tick, -50 pop

Infrastructure

  • Road: Connects buildings, boosts economy
  • Park: -$20/tick, +5 pop
  • Plaza: -$40/tick, +10 pop

Special

  • Town Hall: -$100/tick, +100 pop
  • Power Plant: -$500/tick, -30 pop, enables large buildings

Economy Formula 

Building Income = Base Income × Connectivity Bonus
Connectivity Bonus = 1.0 + (Road Network Size × 0.05)

Offline Economy

When a player is offline, their economy continues at 10% power: 

Offline Income = Base Income × 0.10

Technical Specifications

Server

  • Framework : FastAPI 0.118.0
  • WebSocket : Native FastAPI WebSocket support
  • Database : SQLite3 (built-in)
  • Host : 127.0.0.1:9901
  • Game Tick : Every 10 seconds
  • Persistence : Every 10 seconds

Client

  • Renderer : Three.js r128
  • View : Orthographic camera (Transport Tycoon style)
  • Architecture : ES6 Modules
  • Components : Web Components (Custom Elements)
  • No frameworks : Pure vanilla JavaScript

Communication Protocol

All WebSocket messages are JSON with a type field:

Client → Server

  • cursor_move : {x, y}
  • place_building : {building_type, x, y}
  • remove_building : {x, y}
  • edit_building : {x, y, name}
  • chat : {message, timestamp}

Server → Client

  • init : Initial player and game state
  • game_state_update : Periodic full state sync
  • building_placed : Building added
  • building_removed : Building removed
  • building_updated : Building name changed
  • cursor_move : Player cursor moved
  • player_joined : Player connected
  • player_left : Player disconnected
  • chat : Chat message
  • error : Error message

Project Structure 

city-builder/
├── server/              # Backend Python code
│   ├── __init__.py
│   ├── main.py
│   ├── websocket_manager.py
│   ├── game_state.py
│   ├── economy.py
│   ├── database.py
│   └── models.py
├── static/              # Frontend code
│   ├── index.html
│   ├── css/
│   │   └── style.css
│   └── js/
│       ├── App.js
│       ├── WebSocketClient.js
│       ├── GameRenderer.js
│       ├── InputHandler.js
│       ├── UIManager.js
│       └── components/
│           ├── LoginScreen.js
│           ├── StatsDisplay.js
│           ├── BuildingToolbox.js
│           ├── ChatBox.js
│           └── ContextMenu.js
├── data/                # SQLite database (auto-created)
│   └── game.db
├── requirements.txt
├── .gitignore
├── run.py
├── README.md
└── PROJECT_SUMMARY.md

Development Approach

The project follows modern best practices:

  1. Separation of Concerns : Clear separation between backend, frontend, and UI
  2. Component Architecture : Each component is self-contained
  3. ES6 Modules : Modern JavaScript module system
  4. Web Components : Custom HTML elements for reusability
  5. Real-time Communication : WebSocket for instant updates
  6. Optimistic Updates : UI updates immediately, server validates
  7. Error Handling : Graceful error messages to users
  8. Performance : Only render what's visible
  9. Persistence : Auto-save prevents data loss
  10. Multiplayer : True multiplayer with shared game state

How to Run 

# Install dependencies
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Start server
python run.py

# Open in browser
http://127.0.0.1:9901

Testing the Game

  1. Open browser to http://127.0.0.1:9901
  2. Enter a nickname (press Enter)
  3. Try building:
    • Click "Small House" in the toolbox
    • Click on the map to place it
    • Build more houses to increase population
    • Build roads to connect buildings
    • Build shops once you have enough population
  4. Try multiplayer:
    • Open another browser tab/window
    • Enter a different nickname
    • See both players' cursors and buildings
  5. Try chat:
    • Type in the chat box at the bottom
    • Press Enter to send
  6. Try right-click menu:
    • Right-click your own building
    • Choose "Edit Name" or "Delete"

Completion Status

ALL REQUIREMENTS MET ✓

Every feature from the original specification has been implemented:

  • Transport Tycoon visual style with Three.js
  • Real-time multiplayer via WebSocket
  • 10+ building types with economic gameplay
  • Road connectivity system
  • Player-specific colors
  • Live cursor tracking
  • IRC-style chat
  • Nickname-based login
  • Offline economy (10% power)
  • Context menus
  • No-button inputs (Enter/Escape)
  • Performance optimizations
  • SQLite persistence

The game is fully playable and ready for deployment!