chore: initialize project structure with empty repository scaffold

2025-10-04 18:40:44 +00:00
commit 0eee70cdb9
24 changed files with 2893 additions and 0 deletions
@@ -0,0 +1,324 @@
+# 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
+
+```bash
+# 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!