from_old_account

.gitattributes

@@ -1,4 +1,18 @@
 # Auto detect text files and perform LF normalization
 * text=auto
+
+# Custom for Visual Studio
+*.cs     diff=csharp
+# Standard to msysgit
+*.doc	 diff=astextplain
+*.DOC	 diff=astextplain
+*.docx diff=astextplain
+*.DOCX diff=astextplain
+*.dot  diff=astextplain
+*.DOT  diff=astextplain
+*.pdf  diff=astextplain
+*.PDF	 diff=astextplain
+*.rtf	 diff=astextplain
+*.RTF	 diff=astextplain
 examples/ai_testing/my_games/session_20260515_220558/session_summary.json filter=lfs diff=lfs merge=lfs -text
 *.wav filter=lfs diff=lfs merge=lfs -text

.github/copilot-instructions.md

@@ -0,0 +1,84 @@
+# PyCatan AI Coding Instructions
+
+## Project Overview
+PyCatan is a Python library for simulating Settlers of Catan games. 
+
+**🚀 NEW: Active Development Phase**  
+This project is being actively expanded with a complete simulation framework including GameManager, AI players, and multiple visualization interfaces.
+
+**📚 Additional Documentation:**
+- **[Architecture Overview](instructions/ARCHITECTURE.md)** - Project vision, architecture design, and component responsibilities
+- **[Build Plan](instructions/BUILD_PLAN.md)** - Development roadmap, tasks, and progress tracking
+- **[API Reference](instructions/STEP_BY_STEP_GUIDE.md)** - הסבר לאיך לתקשר עם המשתמש שאתה עובד איתו
+## Legacy Note
+The original core game logic is stable and functional. New development focuses on building a complete simulation layer on top of the existing foundation.
+
+## Core Architecture
+
+### Game Flow Model
+- **Game** (`pycatan/game.py`) orchestrates everything - manages players, board, development cards, and win conditions
+- **Board** (`pycatan/board.py`) is abstract base class; **DefaultBoard** (`pycatan/default_board.py`) implements hexagonal tile layout
+- **Player** (`pycatan/player.py`) manages individual state: cards, buildings, victory points, longest road calculation
+- **Point** and **Tile** objects form the geometric foundation with bidirectional relationships
+
+### Key Patterns
+
+#### Coordinate System
+- Board uses `[row, index]` coordinates throughout (not x,y)
+- Points are intersections where settlements/cities go; tiles are hexes that produce resources
+- Example: `game.add_settlement(player=0, point=board.points[0][0], is_starting=True)`
+
+#### Status-Based Error Handling
+All game actions return `Statuses` enum values instead of throwing exceptions:
+```python
+from pycatan.statuses import Statuses
+result = game.add_settlement(player, point)
+if result == Statuses.ERR_BLOCKED:
+    # Handle blocked building location
+```
+
+#### Starting vs Normal Phase
+Most building actions have `is_starting` parameter - starting phase bypasses card costs and connectivity rules:
+```python
+game.add_settlement(player, point, is_starting=True)  # Free during setup
+game.add_road(player, start, end, is_starting=True)   # No cards required
+```
+
+## Development Workflows
+
+### Testing
+- Use pytest: `python -m pytest tests/` (not the bash script on Windows)
+- Tests in `tests/` follow class-based pattern: `class TestGame:` with `test_*` methods
+- Mock game state by directly manipulating player cards: `player.add_cards([ResCard.Wood, ResCard.Brick])`
+
+### Building/Distribution
+- Package managed via setuptools (`setup.py`)
+- Published to PyPI as `pycatan` package
+- Version number in `setup.py` (currently 0.13)
+
+## Critical Implementation Details
+
+### Longest Road Calculation
+Complex recursive algorithm in `Player.get_longest_road()` - avoid modifying without understanding the connected road traversal logic.
+
+### Card Management
+- Resources use `ResCard` enum, development cards use `DevCard` enum
+- Player card checking with `has_cards()` handles duplicates correctly by creating temporary lists
+- Bank trading supports both 4:1 and harbor-specific rates (2:1 or 3:1)
+
+### Development Card Usage
+Different dev cards require different `args` dictionaries in `use_dev_card()`:
+- Knight: `{'robber_pos': [r, i], 'victim': player_num}`
+- Road Building: `{'road_one': {'start': point, 'end': point}, 'road_two': {...}}`
+- Monopoly: `{'card_type': ResCard.Wood}`
+
+### Import Structure
+Main module exports through `pycatan/__init__.py`:
+- Import as: `from pycatan import Game, Player, ResCard, Statuses`
+- Avoid importing submodules directly unless extending core classes
+
+## Testing Conventions
+- Create game instances with explicit player counts: `Game(num_of_players=4)`
+- Use board coordinate system: `board.points[row][index]` for settlements
+- Test error conditions by checking returned status codes, not exceptions
+- Starting phase tests should verify cards aren't consumed: `assert len(player.cards) == original_count`

.github/instructions/ARCHITECTURE.md

@@ -0,0 +1,146 @@
+# PyCatan Architecture Overview
+
+## מהות הפרויקט
+
+פרויקט PyCatan הוא הרחבה של הספרייה הקיימת למשחק Settlers of Catan, שמוסיפה שכבת סימולציה מלאה עם מנהל משחק, ממשקי משתמש, ו-AI players.
+
+### המטרה
+- יצירת פלטפורמה לסימולציות של משחק Catan
+- תמיכה בשחקנים אנושיים ו-AI בו-זמנית
+- ממשקי ויזואליזציה מרובים (קונסול, ווב)
+- ארכיטקטורה מודולרית וניתנת להרחבה
+
+## הארכיטקטורה
+
+```
+┌─────────────────────────────────────────────┐
+│                GameManager                  │  ← מנהל התורות והזרימה
+├─────────────────────────────────────────────┤
+│ • game_loop()                               │
+│ • handle_turn_rules()                       │
+│ • request_input_from_user()                 │
+│ • coordinate_interactions()                 │
+└─────────────────┬───────────────────────────┘
+                  │
+    ┌─────────────┼─────────────┐
+    │             │             │
+    ▼             ▼             ▼
+┌─────────┐  ┌─────────┐  ┌─────────────┐
+│  Game   │  │  Users  │  │Visualizations│
+│(קיים)   │  │ (חדש)   │  │   (חדש)      │
+└─────────┘  └─────────┘  └─────────────┘
+```
+
+### רכיבי המערכת
+
+#### 1. GameManager (חדש)
+**תפקיד:** מנהל את זרימת המשחק, התורות, וחוקי התורות
+- ניהול לולאת המשחק הראשית
+- תיאום בין שחקנים (מסחר, אישורים)
+- אכיפת חוקי תורות (7 = השלכת קלפים, וכו')
+- ניהול state של התור הנוכחי
+
+#### 2. Game (קיים - התאמות קלות)
+**תפקיד:** לוגיקת המשחק הבסיסית וחוקי המשחק
+- כל הפונקציונליות הקיימת (add_settlement, trade, וכו')
+- הוספת get_full_state() לויזואליזציה
+- validation של פעולות
+
+#### 3. User Hierarchy (חדש)
+```python
+User (Abstract)
+├── HumanUser    # אינטראקציה דרך טרמינל
+└── AIUser       # החלטות אלגוריתמיות
+```
+**תפקיד:** מספק אינפוט למנהל המשחק
+- get_input() מחזיר פעולות מובנות
+- כל User מנהל את הלוגיקה שלו (UI/AI)
+
+#### 4. Visualization (חדש)
+```python
+Visualization (Base)
+├── ConsoleVisualization    # הצגה בטרמינל
+├── WebVisualization        # ממשק ווב
+└── LogVisualization        # תיעוד לקובץ
+```
+**תפקיד:** הצגת מצב המשחק ופעולות
+- notify_action() - עדכון מיידי
+- update_full_state() - עדכון מלא בסוף תור
+
+#### 5. Actions & Data (חדש)
+```python
+ActionType (Enum)           # סוגי פעולות
+Action (DataClass)          # מבנה פעולה
+GameState (DataClass)       # מצב משחק
+```
+
+## זרימת המשחק
+
+### 1. אתחול
+```
+GameManager.initialize()
+├── יצירת Game instance
+├── רישום Users
+├── הגדרת Visualizations
+└── setup_phase()
+```
+
+### 2. לולאת משחק ראשית
+```
+while not game.has_ended:
+    ├── roll_dice() או request_roll()
+    ├── handle_dice_effects() (7 = robber, משאבים)
+    ├── player_action_loop()
+    │   ├── current_user.get_input()
+    │   ├── validate_action()
+    │   ├── execute_action()
+    │   └── update_visualizations()
+    └── end_turn()
+```
+
+### 3. אינטראקציות בין-שחקנים
+```
+Player A: propose_trade()
+├── GameManager validates proposal
+├── GameManager.request_input(Player B, "trade_response")
+├── Player B: accept/reject
+└── GameManager executes or cancels
+```
+
+## עקרונות עיצוב
+
+### הפרדת אחריויות
+- **Game** = מה מותר לעשות (חוקי המשחק)
+- **GameManager** = מתי ואיך לעשות (זרימת התורות)
+- **User** = מה לעשות (החלטות)
+- **Visualization** = איך להציג (ממשק)
+
+### מודולריות
+- כל רכיב עצמאי וניתן להחלפה
+- ממשקים ברורים בין הרכיבים
+- קל להוסיף סוגי Users או Visualizations חדשים
+
+### פשטות
+- זרימה ישירה וברורה
+- בלי abstractions מיותרות
+- debugging וטיפול בשגיא��ת פשוטים
+
+## התאמות לקוד הקיים
+
+המטרה היא למזער שינויים בקוד הקיים:
+- Game class נשאר כמעט זהה
+- הוספת מתודות get_state() למחלקות קיימות
+- Player class יישאר ללא שינוי
+- Board/Building/Card classes ללא שינוי
+
+## דוגמת שימוש
+
+```python
+# הגדרת המשחק
+users = [HumanUser("Alice"), AIUser("Bob"), HumanUser("Charlie")]
+visualizations = [ConsoleVisualization(), LogVisualization("game.log")]
+game_manager = GameManager(users, visualizations)
+
+# הפעלת המשחק
+game_manager.start_game()  # מפעיל את game_loop()
+```

.github/instructions/BUILD_PLAN.md

@@ -0,0 +1,179 @@
+# PyCatan - תוכנית בנייה
+
+## סקירה כללית
+
+תוכנית הבנייה מחולקת ל-6 שלבים עיקריים, כשכל שלב בונה על הקודם ומוסיף פונקציונליות חדשה.
+
+---
+
+## שלב 1: תשתית בסיסית
+**מטרה:** בניית המבנים הבסיסיים והממשקים  
+**סטטוס:** ✅ הושלם במלואו  
+**תאריך השלמה:** 10 נובמבר 2025
+
+**סיכום השלב:**
+- יצרנו את כל התשתית הבסיסית למערכת ניהול המשחק החדשה
+- 3 קבצי קוד ראשיים + 3 קבצי בדיקות
+- סה"כ 75 בדיקות יחידה - כולן עוברות בהצלחה
+- עדכון __init__.py לנגישות המודולים החדשים
+- המערכת מוכנה לשלב הבא
+
+## שלב 2: ממשק בסיסי  
+**מטרה:** יצירת ממשק שימוש בסיסי למשחק
+**סטטוס:** ✅ הושלם במלואו!
+**תאריך השלמה:** 13 נובמבר 2025
+
+**סיכום השלב:**
+- בנינו ממשק CLI מלא ומתקדם עם HumanUser class
+- 15+ סוגי פקודות עם פרסור חכם ו-error handling מקיף
+- מערכת התראות לפעולות ואירועי משחק
+- Console Visualization מתקדמת עם צבעים ומידע מפורט  
+- Web Visualization מלאה עם real-time updates
+- Game Loop פונקציונלי עם טיפול בשגיאות ומונה errors
+- 36 בדיקות יחידה חדשות + דוגמאות אינטרקטיביות
+- **המערכת מוכנה לחיבור למשחק האמיתי!**
+
+## מצב נוכחי: 🎯 שלב 3 - אינטגרציה ובדיקות - 21 נובמבר 2025
+**סטטוס:** 🟡 בתהליך מתקדם. התשתית מוכנה, מתחילים בדיקות ותיקוני באגים.
+
+### משימה 3.1: Game Class Integration
+**סטטוס:** ✅ הושלם (עם באגים ידועים לתיקון)
+
+- [x] הוספת get_full_state() ל-Game
+- [x] הוספת get_state() ל-Player, Board (מומש בתוך get_full_state)
+- [x] יצירת ActionResult objects
+- [x] mapping בין Actions לפונקציות Game (בסיסי)
+- [x] error handling משופר (בסיסי)
+
+**הערות:**
+- פונקציית `add_city` ב-Game מכילה באג (משתנים לא מוגדרים)
+- מיפוי פעולות מסחר וערים ב-GameManager עדיין לא מומש מלא
+
+### משימה 3.2: Validation & Error Handling
+**סטטוס:** 🟡 בתהליך
+
+- [x] validation בסיסי של פעולות ב-GameManager
+- [x] טיפול בשגיאות ברמת GameManager (try/catch blocks)
+- [x] הודעות שגיאה ברורות למשתמש
+- [ ] rollback mechanisms אם נדרש
+- [ ] תיקון באגים לוגיים ב-Game class
+
+### משימה 3.3: End-to-End Testing
+**סטטוס:** 🚀 מוכן להתחלה
+**זהו הפוקוס הנוכחי!**
+
+- [ ] הרצת משחק מלא עם HumanUser
+- [ ] בדיקת כל סוגי הפעולות (בנייה, גלגול קוביות)
+- [ ] זיהוי ותיקון באגים בזמן אמת
+- [ ] וידוא סנכרון בין ה-Visualizations למצב המשחק
+
+---
+
+## שלב 4: חוקי תורות
+**מטרה:** הוספת כל חוקי התורות של Catan
+
+### משימה 4.1: Dice Rolling & Resource Distribution
+**סטטוס:** ⭕ לא התחיל  
+**זמן משוער:** 2-3 שעות
+
+- [ ] מנגנון גלגול קוביות
+- [ ] חלוקת משאבים אוטומטית
+- [ ] טיפול במקרים מיוחדים
+- [ ] logging ו-visualization של גלגולים
+
+### משימה 4.2: Rule of 7 (Robber & Discard)
+**סטטוס:** ⭕ לא התחיל  
+**זמן משוער:** 3-4 שעות
+
+- [ ] השלכת קלפים עבור שחקנים עם 7+ קלפים
+- [ ] העברת הרובר
+- [ ] גנבת קלף אקראי
+- [ ] תיאום בין מספר שחקנים
+
+### משימה 4.3: Turn Phases & Flow Control
+**סטטוס:** ⭕ לא התחיל  
+**זמן משוער:** 2-3 שעות
+
+- [ ] שלבי תור: ROLL -> ACTIONS -> END
+- [ ] מגבלות על פעולות בכל שלב
+- [ ] מעבר אוטומטי בין שלבים
+- [ ] תזמונים ו-timeouts אופציונליים
+
+---
+
+## שלב 5: אינטראקציות בין-שחקנים
+**מטרה:** טיפול במסחר ואינטראקציות מורכבות
+
+### משימה 5.1: Trading System
+**סטטוס:** ⭕ לא התחיל  
+**זמן משוער:** 4-5 שעות
+
+- [ ] הצעות מסחר בין שחקנים
+- [ ] מנגנון אישור/דחייה
+- [ ] counter-offers
+- [ ] timeout למסחר
+- [ ] mסחר עם הבנק (4:1, harbors)
+
+### משימה 5.2: Robber Interactions
+**סטטוס:** ⭕ לא התחיל  
+**זמן משוער:** 2-3 שעות
+
+- [ ] בחירת מיקום רובר
+- [ ] בחירת שחקן לגניבה
+- [ ] Knight card interactions
+- [ ] ויזואליזציה של רובר
+
+### משימה 5.3: Development Cards & Special Actions
+**סטטוס:** ⭕ לא התחיל  
+**זמן משוער:** 3-4 שעות
+
+- [ ] שימוש בקלפי פיתוח
+- [ ] Road Building (שני כבישים)
+- [ ] Monopoly (איסוף קלפים)
+- [ ] Year of Plenty (קבלת משאבים)
+- [ ] Victory Point cards
+
+---
+
+## שלב 6: AI ו-Visualizations מתקדמות
+**מטרה:** השלמת המערכת עם AI ו-UI משופר
+**סטטוס:** 🟡 בתהליך (1/3 משימות הושלמה)
+
+### משימה 6.1: WebVisualization Implementation  
+**סטטוס:** ✅ הושלם במלואו
+**תאריך השלמה:** 11 נובמבר 2025
+
+- [x] יצירת `web_visualization.py`
+  - [x] Flask server מלא עם API endpoints
+  - [x] Server-Sent Events לעדכונים בזמן אמת  
+  - [x] ממשק לכל הmethods הדרושים מ-Visualization base class
+  - [x] המרה מדויקת של GameState לפורמט web
+  - [x] ניהול SSE clients ו-broadcast של עדכונים
+  - [x] Context manager support ו-lifecycle management
+- [x] העתקה ואיילפוץ של תשתית הווב הקיימת
+  - [x] HTML template עם game info panel ו-action log
+  - [x] CSS עם תמיכה בrealtime updates
+  - [x] JavaScript עם חיבור לFlask endpoints ו-SSE
+  - [x] CatanBoard class מתקדמת עם אינטראקטיביות מלאה
+- [x] בדיקות יחידה מקיפות (14 בדיקות - כולן עוברות)
+- [x] דוגמה אינטרקטיבית מלאה עם אפשרויות השוואה
+- [x] אינטגרציה מלאה עם מערכת הVisualization הקיימת
+
+**קבצים שנוצרו:**
+- `pycatan/web_visualization.py`
+- `pycatan/templates/index.html`
+- `pycatan/static/css/style.css`
+- `pycatan/static/js/main.js`
+- `pycatan/static/js/board.js`  
+- `pycatan/static/js/gameData.js`
+- `tests/test_web_visualization.py`
+- `examples/demo_web_visualization.py`
+
+**פיצ'רים מתקדמים:**
+- 🌐 Real-time board visualization בדפדפן
+- 📡 Server-Sent Events לעדכונים מיידיים
+- 🎮 לוח אינטרקטיבי עם zoom, pan, ו-vertex display
+- 📊 Panel מידע שחקנים עם נקודות זכייה וקלפים
+- 📜 Action log בזמן אמת עם הבחנה בין הצלחה לכישלון
+- 🔄 תמיכה בהתחברות מרובת clients
+- 🚀 Auto-browser opening ו-graceful shutdown

.github/instructions/STEP_BY_STEP_GUIDE.md

@@ -0,0 +1,4 @@
+הוראה חשובה!
+אחרי שאתה מסיים לבנות חלק מסויים עצור וודא שהמשתמש שמתקשר איתך מבין מה אתה עושה, קח בחשבון שהמשתמש שמתקשר איתך מבין פייתון אבל לא מאסטר בפייתון ולכן חשוב שתשקף מה אתה עושה ולמה
+
+תמצא את האיזון הנכון, בין לשקף מה אתה עושה, ללפתח

.github/instructions/WEB_VISUALIZATION_GUIDE.md

@@ -0,0 +1,336 @@
+# מדריך ה-Web Visualization של PyCatan
+
+## סקירה כללית
+
+ה-Web Visualization של PyCatan הוא מערכת visualization מתקדמת שמאפשרת צפייה במשחקי Catan בדפדפן בזמן אמת. המערכת בנויה על ארכיטקטורה client-server עם עדכונים מיידיים ואינטראקטיביות מלאה.
+
+## 🏗️ ארכיטקטורה כללית
+
+```
+┌─────────────────────┐         ┌─────────────────────┐         ┌─────────────────────┐
+│                     │  HTTP   │                     │  SSE    │                     │
+│    Browser          │◄────────┤   Flask Server      │────────►│   Game Data         │
+│    (Client)         │         │   (Backend)         │         │   (PyCatan)         │
+│                     │         │                     │         │                     │
+│  - HTML/CSS         │         │  - Web Routes       │         │  - GameState        │
+│  - JavaScript       │         │  - SSE Events       │         │  - Player Data      │
+│  - Board Display    │         │  - Data Conversion  │         │  - Board Data       │
+└─────────────────────┘         └─────────────────────┘         └─────────────────────┘
+```
+
+## 🖥️ הרכיבים העיקריים
+
+### 1. Flask Server (Backend)
+**קובץ:** `pycatan/web_visualization.py`
+
+**תפקידים:**
+- 🌍 **Web Server:** מפעיל שרת Flask על `http://localhost:5001`
+- 📁 **Static Files:** מגיש קבצי HTML, CSS, JavaScript
+- 📡 **API Endpoints:** מספק נתונים דרך HTTP
+- 🔄 **Real-time Updates:** שולח עדכונים בזמן אמת דרך SSE
+
+**המסלולים (Routes) העיקריים:**
+```python
+@self.app.route('/')                    # דף הבית - index.html
+@self.app.route('/api/game-state')      # מצב המשחק הנוכחי  
+@self.app.route('/api/events')          # עדכונים בזמן אמת (SSE)
+@self.app.route('/api/point_mapping')   # מיפוי נקודות הלוח
+```
+
+### 2. Frontend JavaScript (Client)
+**מיקום:** `pycatan/static/js/`
+
+#### **קבצי JavaScript עיקריים:**
+
+**`main.js` - המנהל הראשי:**
+- 🔌 חיבור לשרת Flask
+- 📡 ניהול Server-Sent Events
+- 🎛️ כפתורי בקרה (זום, reset וכו')
+- 🎯 ניהול state המשחק
+
+**`board.js` - מנוע הלוח:**
+- 🎲 הלוח האינטרקטיבי של Catan
+- 🔶 הצגת 19 משושי Catan עם צבעים ומספרים
+- 🏘️ הצגת settlements ו-cities של השחקנים
+- 🛣️ הצגת roads בצבעי השחקנים
+- 🔍 זום, גרירה ואינטראקטיביות מלאה
+- 📍 הצגת נקודות לבניית מבנים
+
+**`gameData.js` - נתוני דמו:**
+- 💾 נתוני fallback שמוצגים אם אין חיבור לשרת
+- 🎮 מכיל לוח Catan מלא עם שחקנים, מבנים וכבישים
+
+### 3. HTML & CSS
+**מיקום:** `pycatan/templates/` & `pycatan/static/css/`
+
+- **`index.html`** - מבנה הדף הראשי
+- **`style.css`** - עיצוב ואנימציות
+- **SVG Graphics** - לוח אינטרקטיבי מבוסס וקטורים
+
+## 📡 Server-Sent Events (SSE) - הטכנולוגיה המרכזית
+
+### מה זה SSE?
+**Server-Sent Events** מאפשר לשרת לשלוח עדכונים לדפדפן **בזמן אמת** ללא צורך בשליחת בקשות חוזרות.
+
+### איך זה עובד?
+
+**🔌 בצד הלקוח (JavaScript):**
+```javascript
+eventSource = new EventSource('/api/events');
+
+eventSource.onmessage = function(event) {
+    const data = JSON.parse(event.data);
+    if (data.type === 'game_update') {
+        updateGameState(data.payload);  // עדכן את הלוח!
+    }
+};
+```
+
+**📡 בצד השרת (Python):**
+```python
+def _broadcast_to_clients(self, event_data):
+    for client_queue in self.sse_clients:
+        client_queue.put_nowait(event_data)  # שלח לכל הלקוחות!
+```
+
+**🎯 סוגי העדכונים שנשלחים:**
+- **`game_update`** - מצב משחק מלא
+- **`action_executed`** - פעולה בוצעה  
+- **`turn_start`** - תור חדש התחיל
+- **`dice_roll`** - קוביות נגרלו
+- **`heartbeat`** - שמירה על החיבור
+
+## 🔄 זרימת הנתונים המלאה
+
+### המסלול הקלאסי:
+
+```
+1. 🎮 PyCatan Game
+   ↓ (קורא ל)
+2. 🖥️ GameManager.update_visualizations() 
+   ↓ (מעביר ל)
+3. 🌐 WebVisualization.update_full_state(game_state)
+   ↓ (ממיר ל)
+4. 📊 _convert_game_state() → web_state 
+   ↓ (שולח עם)
+5. 📡 _broadcast_to_clients({'type': 'game_update', 'payload': web_state})
+   ↓ (מגיע ל)
+6. 🌍 Browser: eventSource.onmessage() 
+   ↓ (מעדכן ל)
+7. 🎲 CatanBoard.updateFromGameState() 
+   ↓ (מציג ב)
+8. 👀 Visual Board Display
+```
+
+### המרת נתונים PyCatan ↔ Web:
+
+**🎯 דוגמה להמרה:**
+```python
+# PyCatan Format:
+GameState(
+    players_state=[PlayerState(name="Alice", cards=["wood", "brick"])],
+    board_state=BoardState(tiles=[{"type": "forest", "token": 11}])
+)
+
+# ↓ המרה ↓
+
+# Web Format:
+{
+    'players': [{'id': 0, 'name': 'Alice', 'total_cards': 2}],
+    'hexes': [{'id': 1, 'type': 'wood', 'number': 11}],
+    'current_player': 0,
+    'settlements': [],
+    'cities': [],
+    'roads': []
+}
+```
+
+## 🚀 תהליך הטעינה והאתחול
+
+### 1. טעינה ראשונית:
+```
+1. 🌍 Browser נטען → index.html
+2. 📜 main.js נטען
+3. 🗺️ loadPointMapping() - טוען מיפוי נקודות
+4. 📊 fetch('/api/game-state') - טוען מצב ראשוני  
+5. 🔌 new EventSource('/api/events') - מתחבר לעדכונים
+6. 🎲 catanBoard.createBoard() - בונה את הלוח הגרפי
+7. ✅ מוכן לעדכונים בזמן אמת!
+```
+
+### 2. החיבור לSSE:
+```python
+@self.app.route('/api/events')
+def sse_events():
+    # יוצר queue עבור הלקוח החדש
+    client_queue = Queue()
+    self.sse_clients.append(client_queue)
+    
+    # שולח מצב משחק ראשוני
+    if self.current_game_state:
+        yield f"data: {json.dumps({'type': 'game_update', 'payload': self.current_game_state})}\n\n"
+    
+    # מאזין לעדכונים חדשים
+    while True:
+        event_data = client_queue.get(timeout=30)
+        yield f"data: {json.dumps(event_data)}\n\n"
+```
+
+## 🎮 פיצ'רים ויכולות
+
+### אינטראקטיביות:
+- **🔍 זום:** גלגל העכבר או כפתורי +/-
+- **🖱️ גרירה:** לחיצה וגרירה להזזת הלוח
+- **📍 נקודות:** הצגה/הסתרה של נקודות בניה
+- **🔄 reset:** חזרה למצב ראשוני
+- **🎯 לחיצות:** על משושים להעברת השודד
+
+### תצוגה:
+- **🎨 צבעים:** כל סוג משאב בצבע שונה
+- **🏘️ מבנים:** settlements (עיגולים) ו-cities (ריבועים)
+- **🛣️ כבישים:** קווים בצבעי השחקנים
+- **🎲 מידע:** פאנל מידע שחקנים ויומן פעולות
+- **📊 Real-time:** עדכונים מיידיים
+
+### רב-משתמש:
+- **🌐 Multiple Clients:** כמה דפדפנים יכולים לצפות באותו משחק
+- **🔄 Sync:** כל הלקוחות רואים אותו דבר בו-זמנית
+- **📡 Broadcast:** עדכון אחד נשלח לכל המחוברים
+
+## 🔧 קבצי המערכת
+
+### Backend (Python):
+```
+pycatan/web_visualization.py     # השרת הראשי
+pycatan/visualization.py         # Base class
+pycatan/actions.py              # Data structures
+```
+
+### Frontend (Web):
+```
+pycatan/templates/index.html     # דף ה-HTML הראשי
+pycatan/static/css/style.css     # עיצוב CSS
+pycatan/static/js/main.js        # JavaScript ראשי
+pycatan/static/js/board.js       # לוח אינטרקטיבי
+pycatan/static/js/gameData.js    # נתוני דמו
+```
+
+### Tests & Examples:
+```
+tests/test_web_visualization.py     # בדיקות יחידה
+examples/demo_web_visualization.py  # דוגמה אינטרקטיבית
+test_web_visualization_full.py     # בדיקה מקיפה
+```
+
+## 💡 שימושים ודוגמאות
+
+### הפעלה בסיסית:
+```python
+from pycatan.web_visualization import WebVisualization
+from pycatan.actions import GameState
+
+# יצירת visualizer
+web_viz = WebVisualization(port=5001, auto_open=True)
+
+# התחלת שרת
+web_viz.start_server()
+
+# עדכון מצב משחק
+game_state = create_game_state()
+web_viz.update_full_state(game_state)
+
+# הדפדפן ייפתח אוטומטית ב-http://localhost:5001
+```
+
+### שימוש במערכת המלאה:
+```python
+from pycatan import GameManager, HumanUser
+from pycatan.web_visualization import WebVisualization
+from pycatan.console_visualization import ConsoleVisualization
+
+# יצירת משתמשים
+users = [HumanUser("Alice"), HumanUser("Bob")]
+
+# יצירת visualizations
+web_viz = WebVisualization()
+console_viz = ConsoleVisualization()
+visualizations = [web_viz, console_viz]
+
+# יצירת מנהל משחק
+game_manager = GameManager(users, visualizations)
+
+# הפעלת משחק - הוא יופיע גם בקונסול וגם בדפדפן!
+game_manager.start_game()
+```
+
+## 🎯 יתרונות המערכת
+
+### טכניים:
+- **🔄 Real-time:** עדכונים מיידיים ללא refresh
+- **📱 Cross-platform:** עובד בכל דפדפן מודרני
+- **🔌 Resilient:** fallback לנתוני דמו אם אין חיבור
+- **🎛️ Interactive:** אינטראקטיביות מלאה עם הלוח
+- **🚀 Performance:** SVG מהיר ויעיל
+
+### מבחינת משתמש:
+- **👀 Visual:** צפייה נוחה ואינטואיטיבית
+- **🎮 Multiple Viewers:** כמה אנשים יכולים לצפות
+- **📊 Rich Info:** מידע מפורט על השחקנים
+- **📜 Action Log:** מעקב אחר כל הפעולות
+- **🔍 Zoom & Pan:** ניווט חופשי בלוח
+
+## 🐛 דיבוג ופתרון בעיות
+
+### בעיות נפוצות:
+
+**1. הלוח לא נטען:**
+- בדוק שהשרת פועל על http://localhost:5001
+- בדוק את קונסול הדפדפן לשגיאות JavaScript
+- ודא שקבצי ה-static נגישים
+
+**2. אין עדכונים בזמן אמת:**
+- בדוק חיבור SSE בקונסול הדפדפן
+- ודא ש-`_broadcast_to_clients()` נקרא
+- בדוק שהלקוח רשום ב-`self.sse_clients`
+
+**3. משושים מוצגים לא נכון:**
+- בדוק את המיפוי ב-`_convert_hexes()`
+- ודא שהנתונים מגיעים בפורמט הנכון
+- בדוק את ה-`tile_type_map`
+
+### כלי דיבוג:
+- **Console Logs:** הרבה הדפסות debug במערכת
+- **Network Tab:** בדוק בקשות HTTP ו-SSE
+- **Elements Inspector:** בדוק את ה-SVG שנוצר
+- **Flask Debug:** הפעל עם `debug=True`
+
+## 🔮 עתיד והרחבות
+
+### אפשרויות הרחבה:
+- **🤖 AI Player Control:** שליטה על שחקני AI מהדפדפן
+- **💬 Chat System:** מערכת צ'אט למשחק מרובה משתתפים
+- **📊 Statistics:** סטטיסטיקות משחק מפורטות
+- **🎵 Sound Effects:** אפקטי קול לפעולות
+- **📱 Mobile Support:** תמיכה משופרת במובייל
+- **🎥 Replay System:** שמירה והשמעה של משחקים
+
+### אינטגרציה עם מערכות אחרות:
+- **🌐 Web Multiplayer:** משחק מרובה משתתפים אמיתי
+- **📡 WebSocket:** עבור אינטראקציה דו-כיוונית
+- **💾 Database:** שמירת משחקים וסטטיסטיקות
+- **🔐 Authentication:** מערכת התחברות משתמשים
+
+---
+
+## 📝 סיכום
+
+ה-Web Visualization של PyCatan הוא מערכת visualization מתקדמת ואמינה שמספקת חוויית צפייה עשירה במשחקי Catan. המערכת משלבת טכנולוגיות מודרניות כמו SSE, SVG ו-Flask ליצירת פלטפורמה אינטראקטיבית ומהירה.
+
+המערכת מספקת:
+- צפייה בזמן אמת במשחק
+- אינטראקטיביות מלאה עם הלוח
+- תמיכה במספר צופים בו-זמנית
+- fallback מחשבתי לכשלי רשת
+- ארכיטקטורה ניתנת להרחבה
+
+**זהו הבסיס המושלם לפיתוח מערכת multiplayer מלאה של Catan!** 🎉

.gitignore

@@ -0,0 +1,65 @@
+# Windows image file caches
+Thumbs.db
+ehthumbs.db
+
+# Folder config file
+Desktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk
+
+# =========================
+# Operating System Files
+# =========================
+
+# OSX
+# =========================
+
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+# Manually added stuff below this ------------------------------------------
+
+# the pychache folders
+__pycache__/
+
+# other PIP files
+pycatan.egg-info/
+
+# the virtualenv cache
+.cache
+
+# the virtualenvwrapper folders created when testing
+lib/
+bin/
+include/
+pip-selfcheck.json
+.pytest_cache/

CHANGES.txt

@@ -0,0 +1 @@
+v1.0, 2017 -- Initial Release

LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2017 Josef Waller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

MANIFEST.in

@@ -0,0 +1 @@
+include readme.md

Pipfile

@@ -0,0 +1,6 @@
+[[source]]
+verify_ssl = true
+url = "https://pypi.python.org/simple"
+
+[packages]
+pytest = "*"

Pipfile.lock

@@ -0,0 +1,45 @@
+{
+    "_meta": {
+        "hash": {
+            "sha256": "8d28e503af2a5207eb2e6fe53e8b11567cbb25cd3a16efe8370dc00cdaea7614"
+        },
+        "host-environment-markers": {
+            "implementation_name": "cpython",
+            "implementation_version": "3.5.2",
+            "os_name": "posix",
+            "platform_machine": "x86_64",
+            "platform_python_implementation": "CPython",
+            "platform_release": "4.4.0-43-Microsoft",
+            "platform_system": "Linux",
+            "platform_version": "#1-Microsoft Wed Dec 31 14:42:53 PST 2014",
+            "python_full_version": "3.5.2",
+            "python_version": "3.5",
+            "sys_platform": "linux"
+        },
+        "pipfile-spec": 3,
+        "requires": {},
+        "sources": [
+            {
+                "url": "https://pypi.python.org/simple",
+                "verify_ssl": true
+            }
+        ]
+    },
+    "default": {
+        "py": {
+            "hashes": [
+                "sha256:2ccb79b01769d99115aa600d7eed99f524bf752bba8f041dc1c184853514655a",
+                "sha256:0f2d585d22050e90c7d293b6451c83db097df77871974d90efd5a30dc12fcde3"
+            ],
+            "version": "==1.4.34"
+        },
+        "pytest": {
+            "hashes": [
+                "sha256:b84f554f8ddc23add65c411bf112b2d88e2489fd45f753b1cae5936358bdf314",
+                "sha256:f46e49e0340a532764991c498244a60e3a37d7424a532b3ff1a6a7653f1a403a"
+            ],
+            "version": "==3.2.2"
+        }
+    },
+    "develop": {}
+}

board_definition.json

@@ -0,0 +1,1435 @@
+{
+  "hexes": {
+    "1": {
+      "hex_id": 1,
+      "game_coords": [
+        0,
+        0
+      ],
+      "axial_coords": [
+        0,
+        -2
+      ],
+      "adjacent_points": [
+        1,
+        2,
+        3,
+        9,
+        10,
+        11
+      ]
+    },
+    "2": {
+      "hex_id": 2,
+      "game_coords": [
+        0,
+        1
+      ],
+      "axial_coords": [
+        1,
+        -2
+      ],
+      "adjacent_points": [
+        3,
+        4,
+        5,
+        11,
+        12,
+        13
+      ]
+    },
+    "3": {
+      "hex_id": 3,
+      "game_coords": [
+        0,
+        2
+      ],
+      "axial_coords": [
+        2,
+        -2
+      ],
+      "adjacent_points": [
+        5,
+        6,
+        7,
+        13,
+        14,
+        15
+      ]
+    },
+    "4": {
+      "hex_id": 4,
+      "game_coords": [
+        1,
+        0
+      ],
+      "axial_coords": [
+        -1,
+        -1
+      ],
+      "adjacent_points": [
+        8,
+        9,
+        10,
+        18,
+        19,
+        20
+      ]
+    },
+    "5": {
+      "hex_id": 5,
+      "game_coords": [
+        1,
+        1
+      ],
+      "axial_coords": [
+        0,
+        -1
+      ],
+      "adjacent_points": [
+        10,
+        11,
+        12,
+        20,
+        21,
+        22
+      ]
+    },
+    "6": {
+      "hex_id": 6,
+      "game_coords": [
+        1,
+        2
+      ],
+      "axial_coords": [
+        1,
+        -1
+      ],
+      "adjacent_points": [
+        12,
+        13,
+        14,
+        22,
+        23,
+        24
+      ]
+    },
+    "7": {
+      "hex_id": 7,
+      "game_coords": [
+        1,
+        3
+      ],
+      "axial_coords": [
+        2,
+        -1
+      ],
+      "adjacent_points": [
+        14,
+        15,
+        16,
+        24,
+        25,
+        26
+      ]
+    },
+    "8": {
+      "hex_id": 8,
+      "game_coords": [
+        2,
+        0
+      ],
+      "axial_coords": [
+        -2,
+        0
+      ],
+      "adjacent_points": [
+        17,
+        18,
+        19,
+        28,
+        29,
+        30
+      ]
+    },
+    "9": {
+      "hex_id": 9,
+      "game_coords": [
+        2,
+        1
+      ],
+      "axial_coords": [
+        -1,
+        0
+      ],
+      "adjacent_points": [
+        19,
+        20,
+        21,
+        30,
+        31,
+        32
+      ]
+    },
+    "10": {
+      "hex_id": 10,
+      "game_coords": [
+        2,
+        2
+      ],
+      "axial_coords": [
+        0,
+        0
+      ],
+      "adjacent_points": [
+        21,
+        22,
+        23,
+        32,
+        33,
+        34
+      ]
+    },
+    "11": {
+      "hex_id": 11,
+      "game_coords": [
+        2,
+        3
+      ],
+      "axial_coords": [
+        1,
+        0
+      ],
+      "adjacent_points": [
+        23,
+        24,
+        25,
+        34,
+        35,
+        36
+      ]
+    },
+    "12": {
+      "hex_id": 12,
+      "game_coords": [
+        2,
+        4
+      ],
+      "axial_coords": [
+        2,
+        0
+      ],
+      "adjacent_points": [
+        25,
+        26,
+        27,
+        36,
+        37,
+        38
+      ]
+    },
+    "13": {
+      "hex_id": 13,
+      "game_coords": [
+        3,
+        0
+      ],
+      "axial_coords": [
+        -2,
+        1
+      ],
+      "adjacent_points": [
+        29,
+        30,
+        31,
+        39,
+        40,
+        41
+      ]
+    },
+    "14": {
+      "hex_id": 14,
+      "game_coords": [
+        3,
+        1
+      ],
+      "axial_coords": [
+        -1,
+        1
+      ],
+      "adjacent_points": [
+        31,
+        32,
+        33,
+        41,
+        42,
+        43
+      ]
+    },
+    "15": {
+      "hex_id": 15,
+      "game_coords": [
+        3,
+        2
+      ],
+      "axial_coords": [
+        0,
+        1
+      ],
+      "adjacent_points": [
+        33,
+        34,
+        35,
+        43,
+        44,
+        45
+      ]
+    },
+    "16": {
+      "hex_id": 16,
+      "game_coords": [
+        3,
+        3
+      ],
+      "axial_coords": [
+        1,
+        1
+      ],
+      "adjacent_points": [
+        35,
+        36,
+        37,
+        45,
+        46,
+        47
+      ]
+    },
+    "17": {
+      "hex_id": 17,
+      "game_coords": [
+        4,
+        0
+      ],
+      "axial_coords": [
+        -2,
+        2
+      ],
+      "adjacent_points": [
+        40,
+        41,
+        42,
+        48,
+        49,
+        50
+      ]
+    },
+    "18": {
+      "hex_id": 18,
+      "game_coords": [
+        4,
+        1
+      ],
+      "axial_coords": [
+        -1,
+        2
+      ],
+      "adjacent_points": [
+        42,
+        43,
+        44,
+        50,
+        51,
+        52
+      ]
+    },
+    "19": {
+      "hex_id": 19,
+      "game_coords": [
+        4,
+        2
+      ],
+      "axial_coords": [
+        0,
+        2
+      ],
+      "adjacent_points": [
+        44,
+        45,
+        46,
+        52,
+        53,
+        54
+      ]
+    }
+  },
+  "points": {
+    "1": {
+      "point_id": 1,
+      "game_coords": [
+        0,
+        0
+      ],
+      "pixel_coords": [
+        377.5,
+        105.14428414850131
+      ],
+      "adjacent_points": [
+        2,
+        9
+      ],
+      "adjacent_hexes": [
+        1
+      ]
+    },
+    "2": {
+      "point_id": 2,
+      "game_coords": [
+        0,
+        1
+      ],
+      "pixel_coords": [
+        422.5,
+        105.14428414850128
+      ],
+      "adjacent_points": [
+        1,
+        3
+      ],
+      "adjacent_hexes": [
+        1
+      ]
+    },
+    "3": {
+      "point_id": 3,
+      "game_coords": [
+        0,
+        2
+      ],
+      "pixel_coords": [
+        445,
+        144.11542731880104
+      ],
+      "adjacent_points": [
+        2,
+        4,
+        11
+      ],
+      "adjacent_hexes": [
+        2,
+        1
+      ]
+    },
+    "4": {
+      "point_id": 4,
+      "game_coords": [
+        0,
+        3
+      ],
+      "pixel_coords": [
+        490,
+        144.11542731880104
+      ],
+      "adjacent_points": [
+        3,
+        5
+      ],
+      "adjacent_hexes": [
+        2
+      ]
+    },
+    "5": {
+      "point_id": 5,
+      "game_coords": [
+        0,
+        4
+      ],
+      "pixel_coords": [
+        512.5,
+        183.08657048910078
+      ],
+      "adjacent_points": [
+        4,
+        6,
+        13
+      ],
+      "adjacent_hexes": [
+        3,
+        2
+      ]
+    },
+    "6": {
+      "point_id": 6,
+      "game_coords": [
+        0,
+        5
+      ],
+      "pixel_coords": [
+        557.5,
+        183.08657048910078
+      ],
+      "adjacent_points": [
+        5,
+        7
+      ],
+      "adjacent_hexes": [
+        3
+      ]
+    },
+    "7": {
+      "point_id": 7,
+      "game_coords": [
+        0,
+        6
+      ],
+      "pixel_coords": [
+        580,
+        222.05771365940052
+      ],
+      "adjacent_points": [
+        6,
+        15
+      ],
+      "adjacent_hexes": [
+        3
+      ]
+    },
+    "8": {
+      "point_id": 8,
+      "game_coords": [
+        1,
+        0
+      ],
+      "pixel_coords": [
+        310,
+        144.11542731880104
+      ],
+      "adjacent_points": [
+        9,
+        18
+      ],
+      "adjacent_hexes": [
+        4
+      ]
+    },
+    "9": {
+      "point_id": 9,
+      "game_coords": [
+        1,
+        1
+      ],
+      "pixel_coords": [
+        355,
+        144.11542731880104
+      ],
+      "adjacent_points": [
+        8,
+        10,
+        1
+      ],
+      "adjacent_hexes": [
+        4,
+        1
+      ]
+    },
+    "10": {
+      "point_id": 10,
+      "game_coords": [
+        1,
+        2
+      ],
+      "pixel_coords": [
+        377.5,
+        183.08657048910078
+      ],
+      "adjacent_points": [
+        9,
+        11,
+        20
+      ],
+      "adjacent_hexes": [
+        5,
+        4,
+        1
+      ]
+    },
+    "11": {
+      "point_id": 11,
+      "game_coords": [
+        1,
+        3
+      ],
+      "pixel_coords": [
+        422.5,
+        183.08657048910078
+      ],
+      "adjacent_points": [
+        10,
+        12,
+        3
+      ],
+      "adjacent_hexes": [
+        5,
+        2,
+        1
+      ]
+    },
+    "12": {
+      "point_id": 12,
+      "game_coords": [
+        1,
+        4
+      ],
+      "pixel_coords": [
+        445,
+        222.05771365940052
+      ],
+      "adjacent_points": [
+        11,
+        13,
+        22
+      ],
+      "adjacent_hexes": [
+        6,
+        5,
+        2
+      ]
+    },
+    "13": {
+      "point_id": 13,
+      "game_coords": [
+        1,
+        5
+      ],
+      "pixel_coords": [
+        490,
+        222.05771365940052
+      ],
+      "adjacent_points": [
+        12,
+        14,
+        5
+      ],
+      "adjacent_hexes": [
+        6,
+        3,
+        2
+      ]
+    },
+    "14": {
+      "point_id": 14,
+      "game_coords": [
+        1,
+        6
+      ],
+      "pixel_coords": [
+        512.5,
+        261.02885682970026
+      ],
+      "adjacent_points": [
+        13,
+        15,
+        24
+      ],
+      "adjacent_hexes": [
+        7,
+        6,
+        3
+      ]
+    },
+    "15": {
+      "point_id": 15,
+      "game_coords": [
+        1,
+        7
+      ],
+      "pixel_coords": [
+        557.5,
+        261.02885682970026
+      ],
+      "adjacent_points": [
+        14,
+        16,
+        7
+      ],
+      "adjacent_hexes": [
+        7,
+        3
+      ]
+    },
+    "16": {
+      "point_id": 16,
+      "game_coords": [
+        1,
+        8
+      ],
+      "pixel_coords": [
+        580,
+        300
+      ],
+      "adjacent_points": [
+        15,
+        26
+      ],
+      "adjacent_hexes": [
+        7
+      ]
+    },
+    "17": {
+      "point_id": 17,
+      "game_coords": [
+        2,
+        0
+      ],
+      "pixel_coords": [
+        242.49999999999997,
+        183.08657048910078
+      ],
+      "adjacent_points": [
+        18,
+        28
+      ],
+      "adjacent_hexes": [
+        8
+      ]
+    },
+    "18": {
+      "point_id": 18,
+      "game_coords": [
+        2,
+        1
+      ],
+      "pixel_coords": [
+        287.5,
+        183.08657048910078
+      ],
+      "adjacent_points": [
+        17,
+        19,
+        8
+      ],
+      "adjacent_hexes": [
+        8,
+        4
+      ]
+    },
+    "19": {
+      "point_id": 19,
+      "game_coords": [
+        2,
+        2
+      ],
+      "pixel_coords": [
+        310,
+        222.05771365940052
+      ],
+      "adjacent_points": [
+        18,
+        20,
+        30
+      ],
+      "adjacent_hexes": [
+        9,
+        8,
+        4
+      ]
+    },
+    "20": {
+      "point_id": 20,
+      "game_coords": [
+        2,
+        3
+      ],
+      "pixel_coords": [
+        355,
+        222.05771365940052
+      ],
+      "adjacent_points": [
+        19,
+        21,
+        10
+      ],
+      "adjacent_hexes": [
+        9,
+        5,
+        4
+      ]
+    },
+    "21": {
+      "point_id": 21,
+      "game_coords": [
+        2,
+        4
+      ],
+      "pixel_coords": [
+        377.5,
+        261.02885682970026
+      ],
+      "adjacent_points": [
+        20,
+        22,
+        32
+      ],
+      "adjacent_hexes": [
+        10,
+        9,
+        5
+      ]
+    },
+    "22": {
+      "point_id": 22,
+      "game_coords": [
+        2,
+        5
+      ],
+      "pixel_coords": [
+        422.5,
+        261.02885682970026
+      ],
+      "adjacent_points": [
+        21,
+        23,
+        12
+      ],
+      "adjacent_hexes": [
+        10,
+        6,
+        5
+      ]
+    },
+    "23": {
+      "point_id": 23,
+      "game_coords": [
+        2,
+        6
+      ],
+      "pixel_coords": [
+        445,
+        300
+      ],
+      "adjacent_points": [
+        22,
+        24,
+        34
+      ],
+      "adjacent_hexes": [
+        11,
+        10,
+        6
+      ]
+    },
+    "24": {
+      "point_id": 24,
+      "game_coords": [
+        2,
+        7
+      ],
+      "pixel_coords": [
+        490,
+        300
+      ],
+      "adjacent_points": [
+        23,
+        25,
+        14
+      ],
+      "adjacent_hexes": [
+        11,
+        7,
+        6
+      ]
+    },
+    "25": {
+      "point_id": 25,
+      "game_coords": [
+        2,
+        8
+      ],
+      "pixel_coords": [
+        512.5,
+        338.97114317029974
+      ],
+      "adjacent_points": [
+        24,
+        26,
+        36
+      ],
+      "adjacent_hexes": [
+        12,
+        11,
+        7
+      ]
+    },
+    "26": {
+      "point_id": 26,
+      "game_coords": [
+        2,
+        9
+      ],
+      "pixel_coords": [
+        557.5,
+        338.97114317029974
+      ],
+      "adjacent_points": [
+        25,
+        27,
+        16
+      ],
+      "adjacent_hexes": [
+        12,
+        7
+      ]
+    },
+    "27": {
+      "point_id": 27,
+      "game_coords": [
+        2,
+        10
+      ],
+      "pixel_coords": [
+        580,
+        377.9422863405995
+      ],
+      "adjacent_points": [
+        26,
+        38
+      ],
+      "adjacent_hexes": [
+        12
+      ]
+    },
+    "28": {
+      "point_id": 28,
+      "game_coords": [
+        3,
+        0
+      ],
+      "pixel_coords": [
+        220,
+        222.05771365940052
+      ],
+      "adjacent_points": [
+        29,
+        17
+      ],
+      "adjacent_hexes": [
+        8
+      ]
+    },
+    "29": {
+      "point_id": 29,
+      "game_coords": [
+        3,
+        1
+      ],
+      "pixel_coords": [
+        242.5,
+        261.02885682970026
+      ],
+      "adjacent_points": [
+        28,
+        30,
+        39
+      ],
+      "adjacent_hexes": [
+        13,
+        8
+      ]
+    },
+    "30": {
+      "point_id": 30,
+      "game_coords": [
+        3,
+        2
+      ],
+      "pixel_coords": [
+        287.5,
+        261.02885682970026
+      ],
+      "adjacent_points": [
+        29,
+        31,
+        19
+      ],
+      "adjacent_hexes": [
+        13,
+        9,
+        8
+      ]
+    },
+    "31": {
+      "point_id": 31,
+      "game_coords": [
+        3,
+        3
+      ],
+      "pixel_coords": [
+        310,
+        300
+      ],
+      "adjacent_points": [
+        30,
+        32,
+        41
+      ],
+      "adjacent_hexes": [
+        14,
+        13,
+        9
+      ]
+    },
+    "32": {
+      "point_id": 32,
+      "game_coords": [
+        3,
+        4
+      ],
+      "pixel_coords": [
+        355,
+        300
+      ],
+      "adjacent_points": [
+        31,
+        33,
+        21
+      ],
+      "adjacent_hexes": [
+        14,
+        10,
+        9
+      ]
+    },
+    "33": {
+      "point_id": 33,
+      "game_coords": [
+        3,
+        5
+      ],
+      "pixel_coords": [
+        377.5,
+        338.97114317029974
+      ],
+      "adjacent_points": [
+        32,
+        34,
+        43
+      ],
+      "adjacent_hexes": [
+        15,
+        14,
+        10
+      ]
+    },
+    "34": {
+      "point_id": 34,
+      "game_coords": [
+        3,
+        6
+      ],
+      "pixel_coords": [
+        422.5,
+        338.97114317029974
+      ],
+      "adjacent_points": [
+        33,
+        35,
+        23
+      ],
+      "adjacent_hexes": [
+        15,
+        11,
+        10
+      ]
+    },
+    "35": {
+      "point_id": 35,
+      "game_coords": [
+        3,
+        7
+      ],
+      "pixel_coords": [
+        445,
+        377.9422863405995
+      ],
+      "adjacent_points": [
+        34,
+        36,
+        45
+      ],
+      "adjacent_hexes": [
+        16,
+        15,
+        11
+      ]
+    },
+    "36": {
+      "point_id": 36,
+      "game_coords": [
+        3,
+        8
+      ],
+      "pixel_coords": [
+        490,
+        377.9422863405995
+      ],
+      "adjacent_points": [
+        35,
+        37,
+        25
+      ],
+      "adjacent_hexes": [
+        16,
+        12,
+        11
+      ]
+    },
+    "37": {
+      "point_id": 37,
+      "game_coords": [
+        3,
+        9
+      ],
+      "pixel_coords": [
+        512.5,
+        416.9134295108992
+      ],
+      "adjacent_points": [
+        36,
+        38,
+        47
+      ],
+      "adjacent_hexes": [
+        16,
+        12
+      ]
+    },
+    "38": {
+      "point_id": 38,
+      "game_coords": [
+        3,
+        10
+      ],
+      "pixel_coords": [
+        557.5,
+        416.9134295108992
+      ],
+      "adjacent_points": [
+        37,
+        27
+      ],
+      "adjacent_hexes": [
+        12
+      ]
+    },
+    "39": {
+      "point_id": 39,
+      "game_coords": [
+        4,
+        0
+      ],
+      "pixel_coords": [
+        220,
+        300
+      ],
+      "adjacent_points": [
+        40,
+        29
+      ],
+      "adjacent_hexes": [
+        13
+      ]
+    },
+    "40": {
+      "point_id": 40,
+      "game_coords": [
+        4,
+        1
+      ],
+      "pixel_coords": [
+        242.5,
+        338.97114317029974
+      ],
+      "adjacent_points": [
+        39,
+        41,
+        48
+      ],
+      "adjacent_hexes": [
+        17,
+        13
+      ]
+    },
+    "41": {
+      "point_id": 41,
+      "game_coords": [
+        4,
+        2
+      ],
+      "pixel_coords": [
+        287.5,
+        338.97114317029974
+      ],
+      "adjacent_points": [
+        40,
+        42,
+        31
+      ],
+      "adjacent_hexes": [
+        17,
+        14,
+        13
+      ]
+    },
+    "42": {
+      "point_id": 42,
+      "game_coords": [
+        4,
+        3
+      ],
+      "pixel_coords": [
+        310,
+        377.9422863405995
+      ],
+      "adjacent_points": [
+        41,
+        43,
+        50
+      ],
+      "adjacent_hexes": [
+        18,
+        17,
+        14
+      ]
+    },
+    "43": {
+      "point_id": 43,
+      "game_coords": [
+        4,
+        4
+      ],
+      "pixel_coords": [
+        355,
+        377.9422863405995
+      ],
+      "adjacent_points": [
+        42,
+        44,
+        33
+      ],
+      "adjacent_hexes": [
+        18,
+        15,
+        14
+      ]
+    },
+    "44": {
+      "point_id": 44,
+      "game_coords": [
+        4,
+        5
+      ],
+      "pixel_coords": [
+        377.5,
+        416.9134295108992
+      ],
+      "adjacent_points": [
+        43,
+        45,
+        52
+      ],
+      "adjacent_hexes": [
+        19,
+        18,
+        15
+      ]
+    },
+    "45": {
+      "point_id": 45,
+      "game_coords": [
+        4,
+        6
+      ],
+      "pixel_coords": [
+        422.5,
+        416.9134295108992
+      ],
+      "adjacent_points": [
+        44,
+        46,
+        35
+      ],
+      "adjacent_hexes": [
+        19,
+        16,
+        15
+      ]
+    },
+    "46": {
+      "point_id": 46,
+      "game_coords": [
+        4,
+        7
+      ],
+      "pixel_coords": [
+        445,
+        455.88457268119896
+      ],
+      "adjacent_points": [
+        45,
+        47,
+        54
+      ],
+      "adjacent_hexes": [
+        19,
+        16
+      ]
+    },
+    "47": {
+      "point_id": 47,
+      "game_coords": [
+        4,
+        8
+      ],
+      "pixel_coords": [
+        490,
+        455.88457268119896
+      ],
+      "adjacent_points": [
+        46,
+        37
+      ],
+      "adjacent_hexes": [
+        16
+      ]
+    },
+    "48": {
+      "point_id": 48,
+      "game_coords": [
+        5,
+        0
+      ],
+      "pixel_coords": [
+        220,
+        377.9422863405995
+      ],
+      "adjacent_points": [
+        49,
+        40
+      ],
+      "adjacent_hexes": [
+        17
+      ]
+    },
+    "49": {
+      "point_id": 49,
+      "game_coords": [
+        5,
+        1
+      ],
+      "pixel_coords": [
+        242.5,
+        416.9134295108992
+      ],
+      "adjacent_points": [
+        48,
+        50
+      ],
+      "adjacent_hexes": [
+        17
+      ]
+    },
+    "50": {
+      "point_id": 50,
+      "game_coords": [
+        5,
+        2
+      ],
+      "pixel_coords": [
+        287.5,
+        416.9134295108992
+      ],
+      "adjacent_points": [
+        49,
+        51,
+        42
+      ],
+      "adjacent_hexes": [
+        18,
+        17
+      ]
+    },
+    "51": {
+      "point_id": 51,
+      "game_coords": [
+        5,
+        3
+      ],
+      "pixel_coords": [
+        310,
+        455.88457268119896
+      ],
+      "adjacent_points": [
+        50,
+        52
+      ],
+      "adjacent_hexes": [
+        18
+      ]
+    },
+    "52": {
+      "point_id": 52,
+      "game_coords": [
+        5,
+        4
+      ],
+      "pixel_coords": [
+        355,
+        455.88457268119896
+      ],
+      "adjacent_points": [
+        51,
+        53,
+        44
+      ],
+      "adjacent_hexes": [
+        19,
+        18
+      ]
+    },
+    "53": {
+      "point_id": 53,
+      "game_coords": [
+        5,
+        5
+      ],
+      "pixel_coords": [
+        377.5,
+        494.8557158514987
+      ],
+      "adjacent_points": [
+        52,
+        54
+      ],
+      "adjacent_hexes": [
+        19
+      ]
+    },
+    "54": {
+      "point_id": 54,
+      "game_coords": [
+        5,
+        6
+      ],
+      "pixel_coords": [
+        422.5,
+        494.8557158514987
+      ],
+      "adjacent_points": [
+        53,
+        46
+      ],
+      "adjacent_hexes": [
+        19
+      ]
+    }
+  }
+}

demo_point_system.py

@@ -0,0 +1,157 @@
+"""
+Interactive demo showing how users can work with point IDs.
+
+This demonstrates the new simplified interface where users work
+with point IDs (1-54) instead of complex coordinates.
+"""
+
+from pycatan import Game, board_definition
+from pycatan.statuses import Statuses
+
+def print_board_info():
+    """Print basic board information."""
+    print("🎮 Catan Board Information")
+    print("=" * 40)
+    print(f"📍 Points available: 1-{len(board_definition.get_all_point_ids())}")
+    print(f"⬢ Hexes on board: {len(board_definition.get_all_hex_ids())}")
+    print()
+
+def show_point_examples():
+    """Show examples of working with points."""
+    print("📍 Point Examples:")
+    print("-" * 20)
+    
+    # Show some corner and edge points
+    example_points = [1, 7, 8, 16, 46, 54]  # Corner and edge points
+    
+    for point_id in example_points:
+        coords = board_definition.point_id_to_game_coords(point_id)
+        adjacent = board_definition.get_adjacent_point_ids(point_id)
+        hexes = board_definition.get_adjacent_hex_ids(point_id)
+        
+        print(f"Point {point_id:2d}: connects to points {adjacent}, touches {len(hexes)} hexes")
+    
+    print()
+
+def demonstrate_road_building():
+    """Demonstrate road building validation."""
+    print("🛤️  Road Building Examples:")
+    print("-" * 30)
+    
+    # Valid road connections
+    valid_roads = [
+        (1, 2),    # Adjacent corner points
+        (10, 11),  # Adjacent edge points  
+        (25, 26),  # Adjacent middle points
+        (25, 36),  # Vertical connection
+    ]
+    
+    invalid_roads = [
+        (1, 54),   # Opposite corners
+        (1, 10),   # Non-adjacent
+        (25, 30),  # Non-adjacent
+    ]
+    
+    print("Valid roads:")
+    for start, end in valid_roads:
+        is_valid = board_definition.is_valid_road_placement(start, end)
+        print(f"  Point {start:2d} -> Point {end:2d}: {'✓' if is_valid else '✗'}")
+    
+    print("\nInvalid roads:")
+    for start, end in invalid_roads:
+        is_valid = board_definition.is_valid_road_placement(start, end)
+        print(f"  Point {start:2d} -> Point {end:2d}: {'✓' if is_valid else '✗'}")
+    
+    print()
+
+def simulate_game_moves():
+    """Simulate some game moves using point IDs."""
+    print("🎯 Simulated Game Moves:")
+    print("-" * 25)
+    
+    # Create game
+    game = Game(num_of_players=2)
+    
+    # Show how a user would build settlements and roads
+    print("Player 0 builds settlement at point 1:")
+    print(f"  Command: game.add_settlement(player=0, point=board.points[0][0], is_starting=True)")
+    
+    # Convert point ID to actual point for game
+    point_coords = board_definition.point_id_to_game_coords(1)
+    if point_coords:
+        point = game.board.points[point_coords[0]][point_coords[1]]
+        result = game.add_settlement(player=0, point=point, is_starting=True)
+        print(f"  Result: {result}")
+    
+    print("\nPlayer 0 builds road from point 1 to point 2:")
+    # Build road between adjacent points
+    start_coords = board_definition.point_id_to_game_coords(1)
+    end_coords = board_definition.point_id_to_game_coords(2)
+    
+    if start_coords and end_coords:
+        start_point = game.board.points[start_coords[0]][start_coords[1]]
+        end_point = game.board.points[end_coords[0]][end_coords[1]]
+        result = game.add_road(player=0, start=start_point, end=end_point, is_starting=True)
+        print(f"  Result: {result}")
+    
+    print("\nCurrent game state:")
+    state = game.get_full_state()
+    print(f"  Buildings: {len(state.board_state.buildings)}")
+    print(f"  Roads: {len(state.board_state.roads)}")
+    
+    if state.board_state.buildings:
+        for point_id, building_info in state.board_state.buildings.items():
+            print(f"    {building_info['type'].title()} at point {point_id} (owner: Player {building_info['owner']})")
+    
+    if state.board_state.roads:
+        for road_info in state.board_state.roads:
+            print(f"    Road from point {road_info['start_point_id']} to {road_info['end_point_id']} (owner: Player {road_info['owner']})")
+    
+    print()
+
+def show_future_user_interface():
+    """Show how the user interface could look."""
+    print("🖥️  Future User Interface Example:")
+    print("-" * 35)
+    
+    print("User input examples:")
+    print("  > build settlement 25")
+    print("  > build road 25 26") 
+    print("  > build city 25")
+    print()
+    
+    print("The system would:")
+    print("  1. Validate point IDs (1-54)")
+    print("  2. Check road connectivity") 
+    print("  3. Convert to internal coordinates")
+    print("  4. Execute game action")
+    print("  5. Update web visualization")
+    print()
+
+def main():
+    """Run the interactive demo."""
+    print("🎮 PyCatan Point ID System Demo")
+    print("=" * 50)
+    print()
+    
+    print_board_info()
+    show_point_examples()
+    demonstrate_road_building()
+    simulate_game_moves()
+    show_future_user_interface()
+    
+    print("✨ Key Benefits:")
+    print("  - Simple point IDs (1-54) instead of complex coordinates")
+    print("  - Consistent across Game, Web UI, and user input")
+    print("  - Automatic validation of road placement")
+    print("  - Single source of truth for board layout")
+    print("  - Easy for humans to remember and use")
+    print()
+    
+    print("🚀 Next steps:")
+    print("  - Update HumanUser to accept point IDs")
+    print("  - Update GameManager to convert point IDs")
+    print("  - Test with web interface")
+
+if __name__ == "__main__":
+    main()

examples/board_renderer.py

@@ -0,0 +1,193 @@
+from pycatan.board import Board
+from pycatan.hex_type import HexType
+from pycatan.game import Game
+from blessings import Terminal
+import math
+
+# Render an board object in ascii in the command prompt
+class BoardRenderer:
+
+    def __init__(self, board, center):
+        self.board = board
+        self.center = center
+        self.terminal = Terminal()
+        # Different colors to use for the 4 players
+        self.player_colors = [
+            self.terminal.red,
+            self.terminal.cyan,
+            self.terminal.green,
+            self.terminal.yellow
+        ]
+
+    def render(self):
+        # Clear screen
+        print(self.terminal.clear())
+        # Render hexes
+        for r in self.board.hexes:
+            for h in r:
+                self.render_hex(h)
+        # Render roads
+        for r in self.board.roads:
+            self.render_road(r)
+        # Render points
+        for r in self.board.points:
+            for p in r:
+                self.render_point(p)
+        # Reset cursor position
+        print(self.terminal.position(0, 0))
+
+    def render_hex(self, hex_obj):
+        # the lines needed to draw each hex
+        hex_lines = [
+            "___",
+            "/%s%s\\" % (BoardRenderer.get_hex_type_string(hex_obj.type), str(hex_obj.token_num).rjust(2) if hex_obj.token_num else "  "),
+            "\\___/"
+        ]
+        # Get the x, y coordinates to render the hex
+        coords = self.get_render_coords(hex_obj.position[0], hex_obj.position[1])
+        # Draw each hex's lines
+        for line_index in range(len(hex_lines)):
+            # Shift the first line over by 1
+            x_offset = 1 if line_index == 0 else 0
+            # Get position
+            position = self.terminal.move(self.center[1] + line_index + coords[1], x_offset + self.center[0] + coords[0])
+            # Print the line
+            print(position + hex_lines[line_index])
+
+    # Draw a point on the hex
+    def render_point(self, point_obj):
+        # Get the building
+        building = point_obj.building
+        # Check it exists
+        if building != None:
+            # Check the point's coordinates
+            coords = self.get_point_coords(point_obj.position[0], point_obj.position[1])
+            # Draw a dot there
+            position = self.terminal.move(self.center[1] + coords[1], self.center[0] + coords[0])
+            # Get the owner of the point
+            owner = building.owner
+            print(self.player_colors[owner] + position + "." + self.terminal.normal)
+
+    # Render a road onto the board
+    def render_road(self, road_obj):
+        # Position to draw the road
+        pos = [0, 0]
+        # String to draw representing the road
+        # Should be either "\", "/" or "___"
+        road_str = ""
+        # Get the points
+        point_one_pos = road_obj.point_one
+        point_two_pos = road_obj.point_two
+        # Get their coordinates
+        p_one_coords = self.get_point_coords(point_one_pos[0], point_one_pos[1])
+        p_two_coords = self.get_point_coords(point_two_pos[0], point_two_pos[1])
+        # If they're on the same line
+        if p_one_coords[1] == p_two_coords[1]:
+            # Just draw a line between them
+            pos = [min(p_one_coords[0], p_two_coords[0]), p_one_coords[1]]
+            road_str = "___"
+        else:
+            if p_one_coords[0] < p_two_coords[0]:
+                if p_one_coords[1] < p_two_coords[1]:
+                    road_str = "\\"
+                else:
+                    road_str = "/"
+            else:
+                if p_one_coords[1] < p_two_coords[1]:
+                    road_str = "/"
+                else:
+                    road_str = "\\"
+            pos = [min(p_one_coords[0], p_two_coords[0]) + 1, max(p_two_coords[1], p_one_coords[1])]
+
+        # Get position
+        render_pos = self.terminal.move(pos[1] + self.center[1], pos[0] + self.center[0])
+        # Print the road
+        print(self.player_colors[road_obj.owner] + render_pos + road_str)
+     
+    # Get the x, y coordinates for a hex from a row and index
+    def get_render_coords(self, row, index):
+        # Initial coords
+        x = 0
+        y = 0
+        # Width/Height of each hex
+        # Each row is futher left than the previous, so decrease x based on row
+        x -= 4 * row
+        # Each row is also half a hex further down than the previous one
+        y += 1 * row
+        # Each index moves the hex down and to the right half a hex each
+        x += 4 * index
+        y += 1 * index
+        # If the row is in the bottom half, it should move the hex down and to the left
+        length = len(self.board.hexes)
+        if row > length / 2:
+            # Move if one hex to the right for every row between its row and the halfway row
+            x += 4 * math.ceil(row - length / 2)
+            # Move it one hex down for every row between its row and the halfway row
+            y += 1 + math.floor(row - length / 2)
+        # Return coords
+        return [x, y]
+
+    # Get the x, y coordinates for a point from a row and index
+    def get_point_coords(self, row, index):
+        # Initial coords
+        x = 1
+        y = 0
+        # Each row moves the point down
+        # Do different positioning if the row is in the top/bottom half of the board
+        half_length = math.floor(len(self.board.points) / 2)
+        if row < half_length:
+            # Each index moves the point over two
+            x += 2 * index
+            # Each second index moves the point down one
+            y += 1 * math.floor(index / 2)
+            # Each row moves the point down and to the left
+            x -= 4 * row
+            y += 1 * row
+        # If the row is in the bottom half, the point should be moved down and to the right
+        if row >= half_length:
+            diff = row - half_length
+            # Move the point to the first position in the bottom row
+            x -= 4 * half_length - 2
+            y += half_length
+            # Move down for each row
+            y += 2 * diff
+            # Move down and to the right for each index
+            y += math.ceil(index / 2)
+            x += 2 * index
+        # Return point
+        return [x, y]
+
+
+    # Get a 1 letter long string representation on a certain hex type
+    @staticmethod
+    def get_hex_type_string(hex_type):
+        if hex_type == HexType.HILLS:
+            return "H"
+        elif hex_type == HexType.MOUNTAINS:
+            return "M"
+        elif hex_type == HexType.PASTURE:
+            return "P"
+        elif hex_type == HexType.FOREST:
+            return "F"
+        elif hex_type == HexType.FIELDS:
+            # Since F is already used, use W for "wheat"
+            return "W"
+        elif hex_type == HexType.DESERT:
+            return "D"
+        else:
+            raise Exception("Unknown HexType %s passed to get_hex_type_string" % hex_type)
+
+
+
+if __name__ == "__main__":
+    g = Game()
+    br = BoardRenderer(g.board, [50, 10])
+    # Add some settlements
+    g.add_settlement(player=0, r=0, i=0, is_starting=True)
+    g.add_settlement(player=1, r=2, i=3, is_starting=True)
+    g.add_settlement(player=2, r=4, i=1, is_starting=True)
+    # Add some roads
+    g.add_road(player=0, start=[0, 0], end=[0, 1], is_starting=True)
+    g.add_road(player=1, start=[2, 3], end=[2, 2], is_starting=True)
+    g.add_road(player=2, start=[4, 1], end=[4, 0], is_starting=True)
+    br.render()

game_viz.log

@@ -0,0 +1,442 @@
+
+>>> Turn 0: a's turn
+✓ a built a settlement
+
+==================================================
+                    GAME STATE                    
+==================================================
+
+Turn: 0
+Current Player: ► a
+
+PLAYERS
+-------
+
+► a
+  Victory Points: 1
+  Resources: None
+  Buildings: Settlements: 1, Cities: 0, Roads: 0
+
+V
+  Victory Points: 0
+  Resources: None
+  Buildings: Settlements: 0, Cities: 0, Roads: 0
+
+BOARD
+-----
+Board Tiles: 19 tiles configured
+
+✓ a built a road
+
+==================================================
+                    GAME STATE                    
+==================================================
+
+Turn: 0
+Current Player: ► a
+
+PLAYERS
+-------
+
+► a
+  Victory Points: 1
+  Resources: None
+  Buildings: Settlements: 1, Cities: 0, Roads: 1
+
+V
+  Victory Points: 0
+  Resources: None
+  Buildings: Settlements: 0, Cities: 0, Roads: 0
+
+BOARD
+-----
+Board Tiles: 19 tiles configured
+
+
+>>> Turn 1: V's turn
+✓ V built a settlement
+
+==================================================
+                    GAME STATE                    
+==================================================
+
+Turn: 1
+Current Player: ► V
+
+PLAYERS
+-------
+
+a
+  Victory Points: 1
+  Resources: None
+  Buildings: Settlements: 1, Cities: 0, Roads: 1
+
+► V
+  Victory Points: 1
+  Resources: None
+  Buildings: Settlements: 1, Cities: 0, Roads: 0
+
+BOARD
+-----
+Board Tiles: 19 tiles configured
+
+✓ V built a road
+
+==================================================
+                    GAME STATE                    
+==================================================
+
+Turn: 1
+Current Player: ► V
+
+PLAYERS
+-------
+
+a
+  Victory Points: 1
+  Resources: None
+  Buildings: Settlements: 1, Cities: 0, Roads: 1
+
+► V
+  Victory Points: 1
+  Resources: None
+  Buildings: Settlements: 1, Cities: 0, Roads: 1
+
+BOARD
+-----
+Board Tiles: 19 tiles configured
+
+
+>>> Turn 2: V's turn
+
+📦 Resources distributed:
+  V: Wood, Brick, Sheep
+✓ V built a settlement
+
+==================================================
+                    GAME STATE                    
+==================================================
+
+Turn: 2
+Current Player: ► V
+
+PLAYERS
+-------
+
+a
+  Victory Points: 1
+  Resources: None
+  Buildings: Settlements: 1, Cities: 0, Roads: 1
+
+► V
+  Victory Points: 2
+  Resources: None
+  Buildings: Settlements: 2, Cities: 0, Roads: 1
+
+BOARD
+-----
+Board Tiles: 19 tiles configured
+
+✓ V built a road
+
+==================================================
+                    GAME STATE                    
+==================================================
+
+Turn: 2
+Current Player: ► V
+
+PLAYERS
+-------
+
+a
+  Victory Points: 1
+  Resources: None
+  Buildings: Settlements: 1, Cities: 0, Roads: 1
+
+► V
+  Victory Points: 2
+  Resources: None
+  Buildings: Settlements: 2, Cities: 0, Roads: 2
+
+BOARD
+-----
+Board Tiles: 19 tiles configured
+
+
+>>> Turn 3: a's turn
+
+📦 Resources distributed:
+  a: Wheat, Brick, Wood
+✓ a built a settlement
+
+==================================================
+                    GAME STATE                    
+==================================================
+
+Turn: 3
+Current Player: ► a
+
+PLAYERS
+-------
+
+► a
+  Victory Points: 2
+  Resources: None
+  Buildings: Settlements: 2, Cities: 0, Roads: 1
+
+V
+  Victory Points: 2
+  Resources: None
+  Buildings: Settlements: 2, Cities: 0, Roads: 2
+
+BOARD
+-----
+Board Tiles: 19 tiles configured
+
+✓ a built a road
+
+==================================================
+                    GAME STATE                    
+==================================================
+
+Turn: 3
+Current Player: ► a
+
+PLAYERS
+-------
+
+► a
+  Victory Points: 2
+  Resources: None
+  Buildings: Settlements: 2, Cities: 0, Roads: 2
+
+V
+  Victory Points: 2
+  Resources: None
+  Buildings: Settlements: 2, Cities: 0, Roads: 2
+
+BOARD
+-----
+Board Tiles: 19 tiles configured
+
+
+>>> Turn 4: a's turn
+
+🎲 a rolled: 5 + 3 = 8
+✓ a rolled the dice
+
+==================================================
+                    GAME STATE                    
+==================================================
+
+Turn: 4
+Current Player: ► a
+
+PLAYERS
+-------
+
+► a
+  Victory Points: 2
+  Resources: None
+  Buildings: Settlements: 2, Cities: 0, Roads: 2
+
+V
+  Victory Points: 2
+  Resources: None
+  Buildings: Settlements: 2, Cities: 0, Roads: 2
+
+BOARD
+-----
+Board Tiles: 19 tiles configured
+
+✗ a proposed a trade
+  Error: V doesn't have the required cards
+
+==================================================
+                    GAME STATE                    
+==================================================
+
+Turn: 4
+Current Player: ► a
+
+PLAYERS
+-------
+
+► a
+  Victory Points: 2
+  Resources: None
+  Buildings: Settlements: 2, Cities: 0, Roads: 2
+
+V
+  Victory Points: 2
+  Resources: None
+  Buildings: Settlements: 2, Cities: 0, Roads: 2
+
+BOARD
+-----
+Board Tiles: 19 tiles configured
+
+✓ a proposed a trade
+
+==================================================
+                    GAME STATE                    
+==================================================
+
+Turn: 4
+Current Player: ► a
+
+PLAYERS
+-------
+
+► a
+  Victory Points: 2
+  Resources: None
+  Buildings: Settlements: 2, Cities: 0, Roads: 2
+
+V
+  Victory Points: 2
+  Resources: None
+  Buildings: Settlements: 2, Cities: 0, Roads: 2
+
+BOARD
+-----
+Board Tiles: 19 tiles configured
+
+✓ a proposed a trade
+
+==================================================
+                    GAME STATE                    
+==================================================
+
+Turn: 4
+Current Player: ► a
+
+PLAYERS
+-------
+
+► a
+  Victory Points: 2
+  Resources: None
+  Buildings: Settlements: 2, Cities: 0, Roads: 2
+
+V
+  Victory Points: 2
+  Resources: None
+  Buildings: Settlements: 2, Cities: 0, Roads: 2
+
+BOARD
+-----
+Board Tiles: 19 tiles configured
+
+✗ a proposed a trade
+  Error: V rejected your trade offer
+
+==================================================
+                    GAME STATE                    
+==================================================
+
+Turn: 4
+Current Player: ► a
+
+PLAYERS
+-------
+
+► a
+  Victory Points: 2
+  Resources: None
+  Buildings: Settlements: 2, Cities: 0, Roads: 2
+
+V
+  Victory Points: 2
+  Resources: None
+  Buildings: Settlements: 2, Cities: 0, Roads: 2
+
+BOARD
+-----
+Board Tiles: 19 tiles configured
+
+✓ a ended their turn
+
+==================================================
+                    GAME STATE                    
+==================================================
+
+Turn: 4
+Current Player: ► a
+
+PLAYERS
+-------
+
+► a
+  Victory Points: 2
+  Resources: None
+  Buildings: Settlements: 2, Cities: 0, Roads: 2
+
+V
+  Victory Points: 2
+  Resources: None
+  Buildings: Settlements: 2, Cities: 0, Roads: 2
+
+BOARD
+-----
+Board Tiles: 19 tiles configured
+
+
+>>> Turn 5: V's turn
+
+🎲 V rolled: 6 + 1 = 7
+✓ V rolled the dice
+
+==================================================
+                    GAME STATE                    
+==================================================
+
+Turn: 5
+Current Player: ► V
+
+PLAYERS
+-------
+
+a
+  Victory Points: 2
+  Resources: None
+  Buildings: Settlements: 2, Cities: 0, Roads: 2
+
+► V
+  Victory Points: 2
+  Resources: None
+  Buildings: Settlements: 2, Cities: 0, Roads: 2
+
+BOARD
+-----
+Board Tiles: 19 tiles configured
+
+✓ V ended their turn
+
+==================================================
+                    GAME STATE                    
+==================================================
+
+Turn: 5
+Current Player: ► V
+
+PLAYERS
+-------
+
+a
+  Victory Points: 2
+  Resources: None
+  Buildings: Settlements: 2, Cities: 0, Roads: 2
+
+► V
+  Victory Points: 2
+  Resources: None
+  Buildings: Settlements: 2, Cities: 0, Roads: 2
+
+BOARD
+-----
+Board Tiles: 19 tiles configured
+
+
+>>> Turn 6: a's turn

play_catan.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+PyCatan Game Launcher
+
+Simple script to launch a complete PyCatan game experience.
+Run this file to start playing!
+
+Features:
+- Interactive player setup
+- Multiple interface windows
+- Console + Web visualization
+- Real-time game updates
+"""
+
+from pycatan import RealGame
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("Welcome to PyCatan!")
+    print("=" * 60)
+    print("Starting the complete game experience...")
+    print()
+    print("What will happen:")
+    print("• You'll enter player count and names")
+    print("• A separate console will open for game visualization")
+    print("• Your web browser will open with the game board")
+    print("• You'll play in this main console")
+    print()
+    
+    # Create and run the game
+    game = RealGame()
+    game.run()

print_game_logic.py

@@ -0,0 +1,40 @@
+
+import sys
+import os
+
+# Add the current directory to the path
+sys.path.append(os.getcwd())
+
+from pycatan import Game
+from pycatan.board_definition import board_definition
+
+def print_game_expectations():
+    print("Initializing Game...")
+    game = Game()
+    board = game.board
+    
+    print("\n" + "="*60)
+    print("GAME LOGIC EXPECTATIONS (What the Python code thinks)")
+    print("="*60 + "\n")
+    
+    print("Format: Hex [Row, Col] -> Connected Point Coordinates [Row, Col]")
+    print("-" * 60)
+
+    # Iterate through all tiles in the game board
+    for r, row in enumerate(board.tiles):
+        for i, tile in enumerate(row):
+            # Get connected points according to Game Logic
+            game_connected_points = tile.points
+            
+            # Get coordinates of connected points
+            point_coords = []
+            for p in game_connected_points:
+                point_coords.append(list(p.position))
+            
+            # Sort for readability
+            point_coords.sort()
+            
+            print(f"Hex [{r}, {i}] connects to Points: {point_coords}")
+
+if __name__ == "__main__":
+    print_game_expectations()

pycatan/__init__.py

@@ -0,0 +1,33 @@
+from pycatan.board import Board
+from pycatan.building import Building
+from pycatan.card import ResCard, DevCard
+from pycatan.game import Game
+from pycatan.harbor import Harbor
+from pycatan.player import Player
+from pycatan.statuses import Statuses
+
+# Board definition system
+from pycatan.board_definition import board_definition, point_id_to_coords, coords_to_point_id
+
+# New simulation framework components
+from pycatan.actions import (
+    Action, ActionType, ActionResult, GameState, PlayerState, BoardState,
+    GamePhase, TurnPhase, create_build_settlement_action, create_build_road_action,
+    create_trade_action
+)
+from pycatan.user import User, UserInputError, validate_user_list, create_test_user
+from pycatan.human_user import HumanUser
+from pycatan.game_manager import GameManager
+from pycatan.visualization import Visualization, VisualizationManager
+from pycatan.console_visualization import ConsoleVisualization
+
+# Optional web visualization (requires Flask)
+try:
+    from pycatan.web_visualization import WebVisualization, create_web_visualization
+except ImportError:
+    # Flask not available - web visualization disabled
+    WebVisualization = None
+    create_web_visualization = None
+
+# Complete game experience
+from pycatan.real_game import RealGame

pycatan/actions.py

@@ -0,0 +1,253 @@
+"""
+Actions & Data Structures for PyCatan Game Management
+
+This module defines the core data structures for managing game actions,
+state, and results in the PyCatan simulation framework.
+"""
+
+from enum import Enum, auto
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Union
+from datetime import datetime
+
+
+class ActionType(Enum):
+    """Enumeration of all possible actions in a Catan game."""
+    
+    # Building actions
+    BUILD_SETTLEMENT = auto()
+    BUILD_CITY = auto() 
+    BUILD_ROAD = auto()
+    
+    # Trading actions
+    TRADE_PROPOSE = auto()
+    TRADE_ACCEPT = auto()
+    TRADE_REJECT = auto()
+    TRADE_COUNTER = auto()
+    TRADE_BANK = auto()
+    
+    # Development card actions
+    USE_DEV_CARD = auto()
+    BUY_DEV_CARD = auto()
+    
+    # Turn management
+    ROLL_DICE = auto()
+    END_TURN = auto()
+    
+    # Special actions
+    ROBBER_MOVE = auto()
+    DISCARD_CARDS = auto()
+    STEAL_CARD = auto()
+    
+    # Setup phase actions
+    PLACE_STARTING_SETTLEMENT = auto()
+    PLACE_STARTING_ROAD = auto()
+
+
+class GamePhase(Enum):
+    """Enumeration of game phases."""
+    SETUP_FIRST_ROUND = auto()
+    SETUP_SECOND_ROUND = auto()
+    NORMAL_PLAY = auto()
+    ENDED = auto()
+
+
+class TurnPhase(Enum):
+    """Enumeration of phases within a single turn."""
+    ROLL_DICE = auto()
+    HANDLE_DICE_EFFECTS = auto()  # Resource distribution, robber on 7
+    DISCARD_PHASE = auto()  # Players with 7+ cards must discard half
+    ROBBER_MOVE = auto()  # Current player must move the robber
+    ROBBER_STEAL = auto()  # Current player must steal from adjacent player
+    PLAYER_ACTIONS = auto()
+    END_TURN = auto()
+
+
+@dataclass
+class Action:
+    """
+    Represents a single action that can be performed in the game.
+    
+    This is the primary interface between Users and the GameManager.
+    All player decisions are expressed as Action objects.
+    """
+    action_type: ActionType
+    player_id: int
+    parameters: Dict[str, Any] = field(default_factory=dict)
+    timestamp: datetime = field(default_factory=datetime.now)
+    
+    def __post_init__(self):
+        """Validate action parameters based on action type."""
+        self._validate_parameters()
+    
+    def _validate_parameters(self):
+        """Basic validation of action parameters."""
+        required_params = {
+            ActionType.BUILD_SETTLEMENT: ['point_coords'],
+            ActionType.BUILD_CITY: ['point_coords'],
+            ActionType.BUILD_ROAD: ['start_coords', 'end_coords'],
+            ActionType.TRADE_PROPOSE: ['offer', 'request', 'target_player'],
+            # TRADE_ACCEPT and TRADE_REJECT don't need trade_id in synchronous mode
+            ActionType.TRADE_COUNTER: ['trade_id', 'counter_offer', 'counter_request'],
+            ActionType.TRADE_BANK: ['offer', 'request'],
+            ActionType.USE_DEV_CARD: ['card_type'],
+            ActionType.ROBBER_MOVE: ['tile_coords'],
+            ActionType.STEAL_CARD: ['target_player'],
+            ActionType.DISCARD_CARDS: ['cards'],
+            ActionType.PLACE_STARTING_SETTLEMENT: ['point_coords'],
+            ActionType.PLACE_STARTING_ROAD: ['start_coords', 'end_coords'],
+        }
+        
+        required = required_params.get(self.action_type, [])
+        missing = [param for param in required if param not in self.parameters]
+        
+        if missing:
+            raise ValueError(f"Action {self.action_type} missing required parameters: {missing}")
+
+
+@dataclass
+@dataclass
+class PlayerState:
+    """Represents the complete state of a single player."""
+    player_id: int
+    name: str
+    cards: List[str]  # Resource cards
+    dev_cards: List[str]  # Development cards
+    settlements: List[tuple]  # Coordinates of settlements
+    cities: List[tuple]  # Coordinates of cities  
+    roads: List[tuple]  # Coordinates of roads (start, end)
+    victory_points: int
+    longest_road_length: int
+    has_longest_road: bool
+    has_largest_army: bool
+    knights_played: int
+
+
+@dataclass
+class BoardState:
+    """Represents the state of the game board."""
+    tiles: List[Dict[str, Any]]  # Tile information
+    robber_position: tuple  # Coordinates of robber
+    harbors: List[Dict[str, Any]]  # Harbor information
+    buildings: Dict[tuple, Dict[str, Any]]  # Point -> building info
+    roads: List[tuple]  # All roads on board
+
+
+@dataclass  
+class GameState:
+    """
+    Represents the complete state of a Catan game at any point in time.
+    
+    This is used for visualization, AI decision-making, and game persistence.
+    """
+    # Game metadata
+    game_id: str = ""
+    turn_number: int = 0
+    current_player: int = 0
+    game_phase: GamePhase = GamePhase.SETUP_FIRST_ROUND
+    turn_phase: TurnPhase = TurnPhase.ROLL_DICE
+    
+    # Game state
+    board_state: BoardState = field(default_factory=lambda: BoardState([], (0, 0), [], {}, []))
+    players_state: List[PlayerState] = field(default_factory=list)
+    
+    # Game resources
+    dev_cards_available: int = 25
+    resource_cards_available: Dict[str, int] = field(default_factory=lambda: {
+        'wood': 19, 'brick': 19, 'sheep': 19, 'wheat': 19, 'ore': 19
+    })
+    
+    # Current turn state
+    dice_rolled: Optional[tuple] = None
+    pending_trades: List[Dict[str, Any]] = field(default_factory=list)
+    pending_actions: List[str] = field(default_factory=list)  # Actions waiting for completion
+    
+    # Robber/Discard state (when 7 is rolled)
+    players_must_discard: Dict[int, int] = field(default_factory=dict)  # player_id -> cards to discard
+    robber_moved: bool = False  # Whether robber has been moved this turn
+    steal_pending: bool = False  # Whether steal action is pending
+    
+    # Game history (for replay/debugging)
+    action_history: List[Action] = field(default_factory=list)
+    
+    def get_player_state(self, player_id: int) -> Optional[PlayerState]:
+        """Get state for a specific player."""
+        for player in self.players_state:
+            if player.player_id == player_id:
+                return player
+        return None
+    
+    def get_current_player_state(self) -> Optional[PlayerState]:
+        """Get state for the current player."""
+        return self.get_player_state(self.current_player)
+
+
+@dataclass
+class ActionResult:
+    """
+    Result of executing an action.
+    
+    Contains information about success/failure, updated game state,
+    and any side effects that occurred.
+    """
+    success: bool
+    error_message: Optional[str] = None
+    updated_state: Optional[GameState] = None
+    affected_players: List[int] = field(default_factory=list)
+    side_effects: List[Action] = field(default_factory=list)  # Additional actions triggered
+    status_code: str = ""  # Maps to pycatan.statuses for compatibility
+    
+    @classmethod
+    def success_result(cls, updated_state: GameState, affected_players: List[int] = None) -> 'ActionResult':
+        """Create a successful action result."""
+        return cls(
+            success=True,
+            updated_state=updated_state,
+            affected_players=affected_players or [],
+            status_code="ALL_GOOD"
+        )
+    
+    @classmethod  
+    def failure_result(cls, error_message: str, status_code: str = "") -> 'ActionResult':
+        """Create a failed action result."""
+        return cls(
+            success=False,
+            error_message=error_message,
+            status_code=status_code
+        )
+
+
+# Utility functions for common action creation
+def create_build_settlement_action(player_id: int, point_coords: tuple, is_starting: bool = False) -> Action:
+    """Helper function to create a build settlement action."""
+    action_type = ActionType.PLACE_STARTING_SETTLEMENT if is_starting else ActionType.BUILD_SETTLEMENT
+    return Action(
+        action_type=action_type,
+        player_id=player_id,
+        parameters={'point_coords': point_coords}
+    )
+
+
+def create_build_road_action(player_id: int, start_coords: tuple, end_coords: tuple, is_starting: bool = False) -> Action:
+    """Helper function to create a build road action."""
+    action_type = ActionType.PLACE_STARTING_ROAD if is_starting else ActionType.BUILD_ROAD
+    return Action(
+        action_type=action_type,
+        player_id=player_id,
+        parameters={'start_coords': start_coords, 'end_coords': end_coords}
+    )
+
+
+def create_trade_action(player_id: int, offer: Dict[str, int], request: Dict[str, int], 
+                       target_player: Optional[int] = None) -> Action:
+    """Helper function to create a trade action."""
+    action_type = ActionType.TRADE_BANK if target_player is None else ActionType.TRADE_PROPOSE
+    parameters = {'offer': offer, 'request': request}
+    if target_player is not None:
+        parameters['target_player'] = target_player
+    
+    return Action(
+        action_type=action_type,
+        player_id=player_id,
+        parameters=parameters
+    )

pycatan/board.py

@@ -0,0 +1,219 @@
+from pycatan.harbor import Harbor, HarborType
+from pycatan.player import Player
+from pycatan.statuses import Statuses
+from pycatan.building import Building
+from pycatan.tile_type import TileType
+from pycatan.card import ResCard, DevCard
+from pycatan.tile import Tile
+from pycatan.point import Point
+
+# used to shuffle the deck of tiles
+import random
+
+import abc
+
+# used for debugging
+import pprint
+
+# Base class for different Catan boards
+# Should not be instantiated, otherwise the board will be empty
+class Board(object):
+    __metaclass__ = abc.ABCMeta
+
+    def __init__(self, game):
+        # The game the board is in
+        self.game = game
+        # The tiles on the board
+        # Should be set in a subclass
+        self.tiles = ()
+        # The points on the board
+        # Where the players can place settlements/cities
+        # Will be set at the end of __init__
+        self.points = ()
+        # The roads
+        self.roads = []
+        # The locations of the harbors
+        self.harbors = []
+        # The location of the robber
+        # going r, i
+        self.robber = None
+
+    # gives the players cards for a certain roll
+    def add_yield(self, roll):
+        
+        # Track resources distributed: {player_name: [resource_names]}
+        distribution = {}
+
+        for r in self.points:
+            for p in r:
+                # Check there is a building on the point
+                if p.building != None:
+                    building = p.building
+                    tiles = p.tiles
+
+                    # checks if any tiles have the right number
+                    for current_tile in tiles:
+
+                        # makes sure the robber isn't there
+                        if self.robber == current_tile.position:
+                            # skips this tile
+                            continue
+
+                        if current_tile.token_num == roll:
+                            # adds the card to the player's inventory
+                            owner = building.owner
+                            # gets the card type
+                            card_type = Board.get_card_from_tile(current_tile.type)
+                            
+                            if card_type:
+                                cards_to_add = []
+                                # adds two if it is a city
+                                if building.type == Building.BUILDING_CITY:
+                                    cards_to_add = [card_type, card_type]
+                                else:
+                                    cards_to_add = [card_type]
+                                    
+                                self.game.players[owner].add_cards(cards_to_add)
+                                
+                                # Record distribution
+                                player_name = f"Player {owner + 1}"
+                                if player_name not in distribution:
+                                    distribution[player_name] = []
+                                
+                                for card in cards_to_add:
+                                    distribution[player_name].append(card.name.split('.')[-1] if hasattr(card, 'name') else str(card))
+        
+        return distribution
+
+
+    # adds a Building object to the board
+    def add_building(self, building, point):
+        point.building = building
+
+    # adds a Building object, which must be a road
+    # since roads record their own position and are not in self.points
+    def add_road(self, road):
+        self.roads.append(road)
+
+    # upgrades an existing settlement to a city
+    def upgrade_settlement(self, player, point):
+        # Get building at point
+        building = point.building
+
+        # checks there is a settlement at r, i
+        if building == None:
+            return Statuses.ERR_NOT_EXIST
+
+        # checks the settlement is controlled by the correct player
+        # if no player is specified, uses the current controlling player
+        if building.owner != player:
+            return Statuses.ERR_BAD_OWNER
+
+        # checks it is a settlement and not a city
+        if building.type != Building.BUILDING_SETTLEMENT:
+            return Statuses.ERR_UPGRADE_CITY
+
+        # checks the player has the cards
+        needed_cards = [
+            ResCard.Wheat,
+            ResCard.Wheat,
+            ResCard.Ore,
+            ResCard.Ore,
+            ResCard.Ore
+        ]
+        if not self.game.players[player].has_cards(needed_cards):
+            return Statuses.ERR_CARDS
+
+        # removes the cards
+        self.game.players[player].remove_cards(needed_cards)
+        # changes the settlement to a city
+        building.type = Building.BUILDING_CITY
+        # adds another victory point
+        self.game.players[player].victory_points += 1
+
+        return Statuses.ALL_GOOD
+
+    # gets all the buildings on the board
+    def get_buildings(self):
+
+        buildings = []
+        for r in self.points:
+            for p in r:
+                if p.building != None:
+                    buildings.append(p.building)
+
+        return buildings
+
+    # moves the robber to a givne coord
+    def move_robber(self, tile_pos):
+        self.robber = tile_pos
+
+    def __repr__(self):
+        return ("Board Object")
+
+    # Get a shuffled deck of the correct number of each type of tile in a board
+    @staticmethod
+    def get_shuffled_tile_deck():
+        deck = []
+        # sets up all_tiles
+        for i in range(4):
+
+            # adds four fields, forests and pastures
+            deck.append(TileType.Fields)
+            deck.append(TileType.Forest)
+            deck.append(TileType.Pasture)
+            # adds three mountains and hills
+            if i < 3:
+                deck.append(TileType.Mountains)
+                deck.append(TileType.Hills)
+
+            # adds one desert
+            if i == 0:
+                deck.append(TileType.Desert)
+
+        # shuffles the deck
+        random.shuffle(deck)
+        return deck
+
+    @staticmethod
+    def get_shuffled_tile_nums():
+        nums = []
+        # Get 2 of each number, most of the time
+        for i in range(2):
+            # Go through each type
+            for x in range(2, 13):
+                # Does not add a number token with 7
+                if x != 7:
+                    # Only adds one 2 and one 12
+                    if x == 2 or x == 12:
+                        if i == 0:
+                            nums.append(x)
+                    # Adds two of everything else
+                    else:
+                        nums.append(x)
+        random.shuffle(nums)
+        return nums
+
+    # returns the card associated with the tile
+    # for example, Brick for Hills, Wood for forests, etc
+    @staticmethod
+    def get_card_from_tile(tile):
+
+        # returns the appropriete card
+        if tile == TileType.Forest:
+            return ResCard.Wood
+
+        elif tile == TileType.Hills:
+            return ResCard.Brick
+
+        elif tile == TileType.Pasture:
+            return ResCard.Sheep
+
+        elif tile == TileType.Fields:
+            return ResCard.Wheat
+
+        elif tile == TileType.Mountains:
+            return ResCard.Ore
+
+        else:
+            return None

pycatan/board_definition.py

@@ -0,0 +1,556 @@
+"""
+Central Board Definition for PyCatan
+
+This module provides the definitive, canonical mapping of the Catan board,
+including all coordinate systems and conversion functions.
+
+ALL other modules should use this as the single source of truth for:
+- Point coordinates and IDs
+- Hex/tile coordinates and IDs  
+- Conversion between coordinate systems
+- Board layout and geometry
+
+This ensures consistency across Game, WebVisualization, JavaScript, and user input.
+"""
+
+from typing import Dict, List, Tuple, Optional, NamedTuple
+from dataclasses import dataclass
+import json
+
+
+@dataclass
+class HexDefinition:
+    """Definition of a single hex on the board."""
+    hex_id: int           # 1-19 for standard Catan
+    game_coords: Tuple[int, int]  # [row, index] used by Game internally
+    axial_coords: Tuple[int, int] # [q, r] for web display
+    adjacent_points: List[int]    # Point IDs (1-54) that border this hex
+
+
+@dataclass
+class PointDefinition:
+    """Definition of a single point/vertex on the board."""
+    point_id: int         # 1-54 for standard Catan  
+    game_coords: Tuple[int, int]  # [row, index] used by Game internally
+    pixel_coords: Tuple[float, float]  # [x, y] for web display
+    adjacent_points: List[int]    # Connected point IDs for roads
+    adjacent_hexes: List[int]     # Hex IDs that this point touches
+
+
+class BoardDefinition:
+    """
+    Central definition of the Catan board layout.
+    
+    This class provides the single source of truth for all coordinate
+    mappings and board geometry. All other systems should use this
+    instead of their own coordinate conversion logic.
+    """
+    
+    def __init__(self):
+        """Initialize the standard Catan board definition."""
+        self.hexes: Dict[int, HexDefinition] = {}
+        self.points: Dict[int, PointDefinition] = {}
+        
+        # Try to load from file first
+        if not self._load_from_file():
+            # Fallback to hardcoded initialization
+            self._initialize_hexes()
+            self._initialize_points() 
+            self._calculate_adjacencies()
+            
+    def _load_from_file(self, filename: str = 'board_definition.json') -> bool:
+        """Load board definition from JSON file."""
+        import os
+        if not os.path.exists(filename):
+            return False
+            
+        try:
+            with open(filename, 'r') as f:
+                data = json.load(f)
+                
+            # Load Hexes
+            for hex_id_str, hex_data in data.get('hexes', {}).items():
+                hex_id = int(hex_id_str)
+                self.hexes[hex_id] = HexDefinition(
+                    hex_id=hex_id,
+                    game_coords=tuple(hex_data['game_coords']),
+                    axial_coords=tuple(hex_data['axial_coords']),
+                    adjacent_points=hex_data.get('adjacent_points', [])
+                )
+                
+            # Load Points
+            for point_id_str, point_data in data.get('points', {}).items():
+                point_id = int(point_id_str)
+                self.points[point_id] = PointDefinition(
+                    point_id=point_id,
+                    game_coords=tuple(point_data['game_coords']),
+                    pixel_coords=tuple(point_data['pixel_coords']),
+                    adjacent_points=point_data.get('adjacent_points', []),
+                    adjacent_hexes=point_data.get('adjacent_hexes', [])
+                )
+                
+            print(f"Loaded board definition from {filename}")
+            return True
+        except Exception as e:
+            print(f"Error loading board definition: {e}")
+            return False
+    
+    def _initialize_hexes(self):
+        """Initialize all 19 hexes with their coordinate mappings."""
+        # Standard Catan board: 5 rows with 3,4,5,4,3 hexes
+        hex_id = 1
+        
+        # Define the game coordinate to axial coordinate conversion
+        # This matches the layout expected by the web visualization
+        hex_layouts = [
+            # Row 0: 3 hexes -> axial coordinates 
+            [(0, 0, 0, -2), (0, 1, 1, -2), (0, 2, 2, -2)],
+            # Row 1: 4 hexes  
+            [(1, 0, -1, -1), (1, 1, 0, -1), (1, 2, 1, -1), (1, 3, 2, -1)],
+            # Row 2: 5 hexes (middle row)
+            [(2, 0, -2, 0), (2, 1, -1, 0), (2, 2, 0, 0), (2, 3, 1, 0), (2, 4, 2, 0)],
+            # Row 3: 4 hexes
+            [(3, 0, -2, 1), (3, 1, -1, 1), (3, 2, 0, 1), (3, 3, 1, 1)],
+            # Row 4: 3 hexes  
+            [(4, 0, -2, 2), (4, 1, -1, 2), (4, 2, 0, 2)]
+        ]
+        
+        for row_layout in hex_layouts:
+            for row, col, q, r in row_layout:
+                self.hexes[hex_id] = HexDefinition(
+                    hex_id=hex_id,
+                    game_coords=(row, col),
+                    axial_coords=(q, r), 
+                    adjacent_points=[]  # Will be calculated later
+                )
+                hex_id += 1
+    
+    def _initialize_points(self):
+        """Initialize all 54 points with their coordinate mappings."""
+        # Standard Catan board: 6 rows with 7,9,11,11,9,7 points
+        point_id = 1
+        
+        # Define all point coordinates as used by the Game internally
+        point_layouts = [
+            # Row 0: 7 points
+            [(0, 0), (0, 1), (0, 2), (0, 3), (0, 4), (0, 5), (0, 6)],
+            # Row 1: 9 points
+            [(1, 0), (1, 1), (1, 2), (1, 3), (1, 4), (1, 5), (1, 6), (1, 7), (1, 8)],
+            # Row 2: 11 points
+            [(2, 0), (2, 1), (2, 2), (2, 3), (2, 4), (2, 5), (2, 6), (2, 7), (2, 8), (2, 9), (2, 10)],
+            # Row 3: 11 points  
+            [(3, 0), (3, 1), (3, 2), (3, 3), (3, 4), (3, 5), (3, 6), (3, 7), (3, 8), (3, 9), (3, 10)],
+            # Row 4: 9 points
+            [(4, 0), (4, 1), (4, 2), (4, 3), (4, 4), (4, 5), (4, 6), (4, 7), (4, 8)],
+            # Row 5: 7 points
+            [(5, 0), (5, 1), (5, 2), (5, 3), (5, 4), (5, 5), (5, 6)]
+        ]
+        
+        for row_points in point_layouts:
+            for row, col in row_points:
+                # Calculate pixel coordinates for web display
+                pixel_x, pixel_y = self._calculate_pixel_coords(row, col)
+                
+                self.points[point_id] = PointDefinition(
+                    point_id=point_id,
+                    game_coords=(row, col),
+                    pixel_coords=(pixel_x, pixel_y),
+                    adjacent_points=[],  # Will be calculated later
+                    adjacent_hexes=[]    # Will be calculated later
+                )
+                point_id += 1
+    
+    def _calculate_pixel_coords(self, row: int, col: int) -> Tuple[float, float]:
+        """
+        Calculate pixel coordinates for a point given its game coordinates.
+        
+        Uses direct mapping of each point to the appropriate hex vertex position.
+        This ensures points are positioned exactly on hex corners.
+        """
+        import math
+        
+        # Base parameters matching JavaScript
+        HEX_RADIUS = 45
+        CENTER_X = 400
+        CENTER_Y = 300
+        
+        # Helper: get pixel coords of hex center from axial coords
+        def get_hex_center(q, r):
+            x = CENTER_X + HEX_RADIUS * (3/2 * q)
+            y = CENTER_Y + HEX_RADIUS * (math.sqrt(3)/2 * q + math.sqrt(3) * r)
+            return (x, y)
+        
+        # Helper: get vertex position (0=top, clockwise)
+        def get_hex_vertex(q, r, vertex_idx):
+            cx, cy = get_hex_center(q, r)
+            angle_deg = 60 * vertex_idx - 90  # Start at top (270°), go clockwise
+            angle_rad = math.radians(angle_deg)
+            x = cx + HEX_RADIUS * math.cos(angle_rad)
+            y = cy + HEX_RADIUS * math.sin(angle_rad)
+            return (x, y)
+        
+        # Manual mapping: (row, col) -> (q, r, vertex)
+        # Based on standard Catan board with axial coordinates
+        point_to_hex_vertex = {
+            # Row 0 (7 points) - top edge
+            (0, 0): (0, -2, 4),   (0, 1): (0, -2, 5),   (0, 2): (0, -2, 0),
+            (0, 3): (1, -2, 5),   (0, 4): (1, -2, 0),   (0, 5): (2, -2, 5),
+            (0, 6): (2, -2, 0),
+            
+            # Row 1 (9 points)
+            (1, 0): (-1, -1, 4),  (1, 1): (-1, -1, 5),  (1, 2): (0, -1, 4),
+            (1, 3): (0, -1, 5),   (1, 4): (1, -1, 4),   (1, 5): (1, -1, 5),
+            (1, 6): (2, -1, 4),   (1, 7): (2, -1, 5),   (1, 8): (2, -1, 0),
+            
+            # Row 2 (11 points) - widest
+            (2, 0): (-2, 0, 4),   (2, 1): (-2, 0, 5),   (2, 2): (-1, 0, 4),
+            (2, 3): (-1, 0, 5),   (2, 4): (0, 0, 4),    (2, 5): (0, 0, 5),
+            (2, 6): (1, 0, 4),    (2, 7): (1, 0, 5),    (2, 8): (2, 0, 4),
+            (2, 9): (2, 0, 5),    (2, 10): (2, 0, 0),
+            
+            # Row 3 (11 points) - widest
+            (3, 0): (-2, 1, 3),   (3, 1): (-2, 1, 4),   (3, 2): (-1, 1, 3),
+            (3, 3): (-1, 1, 4),   (3, 4): (0, 1, 3),    (3, 5): (0, 1, 4),
+            (3, 6): (1, 1, 3),    (3, 7): (1, 1, 4),    (3, 8): (1, 1, 5),
+            (3, 9): (1, 1, 0),    (3, 10): (1, 1, 1),
+            
+            # Row 4 (9 points)
+            (4, 0): (-2, 2, 2),   (4, 1): (-2, 2, 3),   (4, 2): (-1, 2, 2),
+            (4, 3): (-1, 2, 3),   (4, 4): (0, 2, 2),    (4, 5): (0, 2, 3),
+            (4, 6): (0, 2, 4),    (4, 7): (0, 2, 5),    (4, 8): (0, 2, 0),
+            
+            # Row 5 (7 points) - bottom edge
+            (5, 0): (-2, 2, 1),   (5, 1): (-2, 2, 2),   (5, 2): (-1, 2, 1),
+            (5, 3): (-1, 2, 2),   (5, 4): (0, 2, 1),    (5, 5): (0, 2, 2),
+            (5, 6): (0, 2, 3),
+        }
+        
+        # Get the hex and vertex for this point
+        if (row, col) in point_to_hex_vertex:
+            q, r, vertex = point_to_hex_vertex[(row, col)]
+            return get_hex_vertex(q, r, vertex)
+        else:
+            # Fallback for unmapped points
+            print(f"Warning: No mapping for point ({row}, {col})")
+            return (CENTER_X, CENTER_Y)
+        return (x, y)
+    
+    def _calculate_adjacencies(self):
+        """Calculate which points and hexes are adjacent to each other."""
+        # For each hex, determine which points border it
+        # For each point, determine which other points it connects to and which hexes it touches
+        
+        # This is based on the geometric relationships of the hexagonal board
+        # We'll use the existing logic from DefaultBoard.get_tile_indexes_for_point
+        # but in a cleaner, centralized way
+        
+        for point_id, point_def in self.points.items():
+            row, col = point_def.game_coords
+            
+            # Find adjacent hexes using the existing logic from DefaultBoard
+            adjacent_hex_coords = self._get_hex_coords_for_point(row, col)
+            for hex_coord in adjacent_hex_coords:
+                # Find hex with these coordinates
+                for hex_id, hex_def in self.hexes.items():
+                    if hex_def.game_coords == hex_coord:
+                        point_def.adjacent_hexes.append(hex_id)
+                        hex_def.adjacent_points.append(point_id)
+            
+            # Find adjacent points using board connectivity rules
+            point_def.adjacent_points = self._get_connected_point_ids(row, col)
+    
+    def _get_hex_coords_for_point(self, row: int, col: int) -> List[Tuple[int, int]]:
+        """
+        Get hex coordinates that border a given point.
+        This is the same logic as DefaultBoard.get_tile_indexes_for_point
+        """
+        hex_coords = []
+        
+        # The complex logic from DefaultBoard - but cleaner
+        if row < 3:  # Top half
+            # Hexes below the point
+            if col < [7, 9, 11][row] - 1:
+                hex_coords.append((row, col // 2))
+            
+            if col % 2 == 0 and col > 0:
+                hex_coords.append((row, col // 2 - 1))
+            
+            # Hexes above the point
+            if row > 0:
+                if col > 0 and col < [7, 9, 11][row] - 2:
+                    hex_coords.append((row - 1, (col - 1) // 2))
+                
+                if col % 2 == 1 and col < [7, 9, 11][row] - 1 and col > 1:
+                    hex_coords.append((row - 1, (col - 1) // 2 - 1))
+        
+        else:  # Bottom half
+            # Hexes below
+            if row < 5:
+                if col < [11, 9, 7][row - 3] - 2 and col > 0:
+                    hex_coords.append((row, (col - 1) // 2))
+                
+                if col % 2 == 1 and col > 1 and col < [11, 9, 7][row - 3]:
+                    hex_coords.append((row, (col - 1) // 2 - 1))
+            
+            # Hexes above
+            if col < [11, 9, 7][row - 3] - 1:
+                hex_coords.append((row - 1, col // 2))
+            
+            if col > 1 and col % 2 == 0:
+                hex_coords.append((row - 1, (col - 1) // 2))
+        
+        return hex_coords
+    
+    def _get_connected_point_ids(self, row: int, col: int) -> List[int]:
+        """
+        Get point IDs that are directly connected to the given point.
+        This is based on DefaultBoard.get_connected_points logic.
+        """
+        connected = []
+        
+        # Left and right connections
+        if col > 0:
+            left_point_id = self.coords_to_point_id(row, col - 1)
+            if left_point_id:
+                connected.append(left_point_id)
+        
+        row_widths = [7, 9, 11, 11, 9, 7]
+        if col < row_widths[row] - 1:
+            right_point_id = self.coords_to_point_id(row, col + 1)
+            if right_point_id:
+                connected.append(right_point_id)
+        
+        # Up and down connections (more complex due to hexagonal geometry)
+        if row == 2 and col % 2 == 0:
+            down_point_id = self.coords_to_point_id(row + 1, col)
+            if down_point_id:
+                connected.append(down_point_id)
+        elif row == 3 and col % 2 == 0:
+            up_point_id = self.coords_to_point_id(row - 1, col)
+            if up_point_id:
+                connected.append(up_point_id)
+        elif row < 3:
+            if col % 2 == 0:
+                down_point_id = self.coords_to_point_id(row + 1, col + 1)
+                if down_point_id:
+                    connected.append(down_point_id)
+            elif row > 0 and col > 0:
+                up_point_id = self.coords_to_point_id(row - 1, col - 1)
+                if up_point_id:
+                    connected.append(up_point_id)
+        else:
+            if col % 2 == 0:
+                up_point_id = self.coords_to_point_id(row - 1, col + 1)
+                if up_point_id:
+                    connected.append(up_point_id)
+            elif row < 5 and col > 0:
+                down_point_id = self.coords_to_point_id(row + 1, col - 1)
+                if down_point_id:
+                    connected.append(down_point_id)
+        
+        return connected
+    
+    # ===== PUBLIC API FOR COORDINATE CONVERSIONS =====
+    
+    def point_id_to_game_coords(self, point_id: int) -> Optional[Tuple[int, int]]:
+        """Convert point ID (1-54) to game coordinates [row, col]."""
+        point_def = self.points.get(point_id)
+        return point_def.game_coords if point_def else None
+    
+    def game_coords_to_point_id(self, row: int, col: int) -> Optional[int]:
+        """Convert game coordinates [row, col] to point ID (1-54)."""
+        for point_id, point_def in self.points.items():
+            if point_def.game_coords == (row, col):
+                return point_id
+        return None
+    
+    def coords_to_point_id(self, row: int, col: int) -> Optional[int]:
+        """Alias for game_coords_to_point_id for backward compatibility."""
+        return self.game_coords_to_point_id(row, col)
+    
+    def point_id_to_pixel_coords(self, point_id: int) -> Optional[Tuple[float, float]]:
+        """Convert point ID to pixel coordinates for web display."""
+        point_def = self.points.get(point_id)
+        return point_def.pixel_coords if point_def else None
+    
+    def hex_id_to_game_coords(self, hex_id: int) -> Optional[Tuple[int, int]]:
+        """Convert hex ID (1-19) to game coordinates [row, col]."""
+        hex_def = self.hexes.get(hex_id)
+        return hex_def.game_coords if hex_def else None
+    
+    def game_coords_to_hex_id(self, row: int, col: int) -> Optional[int]:
+        """Convert game coordinates [row, col] to hex ID (1-19)."""
+        for hex_id, hex_def in self.hexes.items():
+            if hex_def.game_coords == (row, col):
+                return hex_id
+        return None
+    
+    def hex_id_to_axial_coords(self, hex_id: int) -> Optional[Tuple[int, int]]:
+        """Convert hex ID to axial coordinates [q, r] for web display."""
+        hex_def = self.hexes.get(hex_id)
+        return hex_def.axial_coords if hex_def else None
+    
+    def get_adjacent_point_ids(self, point_id: int) -> List[int]:
+        """Get all point IDs directly connected to the given point."""
+        point_def = self.points.get(point_id)
+        return point_def.adjacent_points.copy() if point_def else []
+    
+    def get_adjacent_hex_ids(self, point_id: int) -> List[int]:
+        """Get all hex IDs that border the given point."""
+        point_def = self.points.get(point_id)
+        return point_def.adjacent_hexes.copy() if point_def else []
+    
+    def get_hex_border_points(self, hex_id: int) -> List[int]:
+        """Get all point IDs that border the given hex."""
+        hex_def = self.hexes.get(hex_id)
+        return hex_def.adjacent_points.copy() if hex_def else []
+    
+    def is_valid_road_placement(self, point_id_1: int, point_id_2: int) -> bool:
+        """Check if a road can be placed between two points."""
+        if point_id_1 == point_id_2:
+            return False
+        
+        adjacent_points = self.get_adjacent_point_ids(point_id_1)
+        return point_id_2 in adjacent_points
+    
+    def get_all_point_ids(self) -> List[int]:
+        """Get all valid point IDs (1-54)."""
+        return sorted(self.points.keys())
+    
+    def get_all_hex_ids(self) -> List[int]:
+        """Get all valid hex IDs (1-19)."""
+        return sorted(self.hexes.keys())
+    
+    # ===== EXPORT FUNCTIONS FOR OTHER SYSTEMS =====
+    
+    def export_for_web(self) -> Dict:
+        """Export board definition in format expected by web visualization."""
+        return {
+            'hexes': [
+                {
+                    'id': hex_def.hex_id,
+                    'q': hex_def.axial_coords[0],
+                    'r': hex_def.axial_coords[1],
+                    'game_coords': hex_def.game_coords
+                }
+                for hex_def in self.hexes.values()
+            ],
+            'points': [
+                {
+                    'id': point_def.point_id,
+                    'x': point_def.pixel_coords[0], 
+                    'y': point_def.pixel_coords[1],
+                    'game_coords': point_def.game_coords,
+                    'adjacent_points': point_def.adjacent_points,
+                    'adjacent_hexes': point_def.adjacent_hexes
+                }
+                for point_def in self.points.values()
+            ],
+            'total_points': len(self.points),
+            'total_hexes': len(self.hexes)
+        }
+    
+    def export_point_mapping(self) -> Dict:
+        """Export point mapping for backward compatibility with point_mapping.py."""
+        return {
+            'point_to_coords': {
+                point_id: list(point_def.game_coords)
+                for point_id, point_def in self.points.items()
+            },
+            'coords_to_point': {
+                f"{point_def.game_coords[0]},{point_def.game_coords[1]}": point_id
+                for point_id, point_def in self.points.items()
+            },
+            'total_points': len(self.points)
+        }
+    
+    def save_to_file(self, filename: str = 'board_definition.json'):
+        """Save board definition to JSON file."""
+        data = {
+            'hexes': {
+                hex_id: {
+                    'hex_id': hex_def.hex_id,
+                    'game_coords': hex_def.game_coords,
+                    'axial_coords': hex_def.axial_coords,
+                    'adjacent_points': hex_def.adjacent_points
+                }
+                for hex_id, hex_def in self.hexes.items()
+            },
+            'points': {
+                point_id: {
+                    'point_id': point_def.point_id,
+                    'game_coords': point_def.game_coords,
+                    'pixel_coords': point_def.pixel_coords,
+                    'adjacent_points': point_def.adjacent_points,
+                    'adjacent_hexes': point_def.adjacent_hexes
+                }
+                for point_id, point_def in self.points.items()
+            }
+        }
+        
+        with open(filename, 'w') as f:
+            json.dump(data, f, indent=2)
+        
+        print(f"Board definition saved to {filename}")
+
+
+# Global board definition instance - single source of truth
+board_definition = BoardDefinition()
+
+
+# Convenience functions for backward compatibility
+def point_id_to_coords(point_id: int) -> Optional[List[int]]:
+    """Convert point ID to game coordinates."""
+    coords = board_definition.point_id_to_game_coords(point_id)
+    return list(coords) if coords else None
+
+
+def coords_to_point_id(row: int, col: int) -> Optional[int]:
+    """Convert game coordinates to point ID."""
+    return board_definition.game_coords_to_point_id(row, col)
+
+
+def get_adjacent_points(point_id: int) -> List[int]:
+    """Get adjacent point IDs for the given point."""
+    return board_definition.get_adjacent_point_ids(point_id)
+
+
+def validate_road_placement(point_id_1: int, point_id_2: int) -> bool:
+    """Check if a road can be placed between two points."""
+    return board_definition.is_valid_road_placement(point_id_1, point_id_2)
+
+
+if __name__ == "__main__":
+    # Test and demonstration
+    print("=== PyCatan Board Definition ===")
+    print(f"Total hexes: {len(board_definition.hexes)}")
+    print(f"Total points: {len(board_definition.points)}")
+    
+    # Test coordinate conversions
+    print("\n=== Coordinate Conversion Tests ===")
+    test_points = [1, 10, 25, 54]
+    for point_id in test_points:
+        game_coords = board_definition.point_id_to_game_coords(point_id)
+        pixel_coords = board_definition.point_id_to_pixel_coords(point_id)
+        back_to_id = board_definition.game_coords_to_point_id(*game_coords) if game_coords else None
+        
+        print(f"Point {point_id}: {game_coords} -> pixels {pixel_coords} -> back to {back_to_id}")
+    
+    # Test adjacency
+    print("\n=== Adjacency Tests ===")
+    test_point = 25
+    adjacent = board_definition.get_adjacent_point_ids(test_point)
+    adjacent_hexes = board_definition.get_adjacent_hex_ids(test_point)
+    print(f"Point {test_point} adjacent to points: {adjacent}")
+    print(f"Point {test_point} adjacent to hexes: {adjacent_hexes}")
+    
+    # Test road validation
+    print("\n=== Road Validation Tests ===")
+    test_roads = [(1, 2), (1, 8), (25, 26), (1, 54)]
+    for p1, p2 in test_roads:
+        valid = board_definition.is_valid_road_placement(p1, p2)
+        status = "✓" if valid else "✗"
+        print(f"Road {p1} -> {p2}: {status}")
+    
+    # Export for web
+    board_definition.save_to_file('board_definition.json')

pycatan/building.py

@@ -0,0 +1,33 @@
+# a  settlement/city class
+
+class Building:
+
+    BUILDING_SETTLEMENT = 0
+    BUILDING_ROAD = 1
+    BUILDING_CITY = 2
+
+    def __init__(self, owner, type, point_one=None, point_two=None):
+
+        # sets the owner and type
+        self.owner = owner
+        self.type = type
+
+        # records where it is if it is a road
+        if self.type == Building.BUILDING_ROAD:
+
+            self.point_one = point_one
+            self.point_two = point_two
+
+        else:
+            self.point = point_one
+
+    def __repr__(self):
+
+        if self.type == Building.BUILDING_ROAD:
+            return "Road, owned by player %s, from %s to %s" % (self.owner, self.point_one.position, self.point_two.position)
+
+        elif self.type == Building.BUILDING_SETTLEMENT:
+            return "Settlement, owned by player %s" % self.owner
+
+        else:
+            return "City, owned by player %s" % self.owner

pycatan/card.py

@@ -0,0 +1,21 @@
+from enum import Enum
+
+# The different types of resource cards
+class ResCard(Enum):
+
+    # the resource cards
+    Wood = 0
+    Brick = 1
+    Ore = 2
+    Sheep = 3
+    Wheat = 4
+
+# The different types of developement cards
+class DevCard(Enum):
+
+    # the developement cards
+    Road = 0
+    VictoryPoint = 1
+    Knight = 2
+    Monopoly = 3
+    YearOfPlenty = 4

pycatan/console_visualization.py

@@ -0,0 +1,645 @@
+"""
+Console-based visualization for PyCatan game.
+
+This module provides a text-based console interface for displaying game state,
+actions, and events. It formats the game information in a readable way for
+terminal display.
+"""
+
+from typing import Dict, Any, List, Optional
+from .visualization import Visualization
+from .actions import Action, ActionResult, ActionType, GameState
+from .card import ResCard, DevCard
+
+
+class ConsoleVisualization(Visualization):
+    """
+    Console-based visualization implementation.
+    
+    Displays game information in a formatted text output suitable for
+    terminal/console viewing. Uses colors and formatting when available.
+    """
+    
+    def __init__(self, use_colors: bool = True, compact_mode: bool = False, output_file: Optional[str] = None):
+        """
+        Initialize the console visualization.
+        
+        Args:
+            use_colors: Whether to use ANSI color codes for formatting
+            compact_mode: Whether to use compact display format
+            output_file: Optional path to a file to write output to instead of stdout
+        """
+        super().__init__("Console")
+        self.use_colors = use_colors
+        self.compact_mode = compact_mode
+        self.output_file = output_file
+        
+        # ANSI color codes (if enabled)
+        if self.use_colors:
+            self.colors = {
+                'reset': '\033[0m',
+                'bold': '\033[1m',
+                'red': '\033[91m',
+                'green': '\033[92m',
+                'yellow': '\033[93m',
+                'blue': '\033[94m',
+                'purple': '\033[95m',
+                'cyan': '\033[96m',
+                'white': '\033[97m'
+            }
+        else:
+            self.colors = {key: '' for key in ['reset', 'bold', 'red', 'green', 
+                                             'yellow', 'blue', 'purple', 'cyan', 'white']}
+
+    def _print(self, text: str = "", end: str = "\n"):
+        """Internal print method to handle output destination."""
+        if self.output_file:
+            try:
+                with open(self.output_file, 'a', encoding='utf-8') as f:
+                    f.write(str(text) + end)
+            except Exception:
+                pass # Ignore errors writing to file
+        else:
+            print(text, end=end)
+    
+    def _format_header(self, text: str) -> str:
+        """Format a header with colors and formatting."""
+        return f"\n{self.colors['bold']}{self.colors['cyan']}{'='*50}{self.colors['reset']}\n" \
+               f"{self.colors['bold']}{self.colors['cyan']}{text.center(50)}{self.colors['reset']}\n" \
+               f"{self.colors['bold']}{self.colors['cyan']}{'='*50}{self.colors['reset']}\n"
+    
+    def _format_subheader(self, text: str) -> str:
+        """Format a subheader with colors."""
+        return f"\n{self.colors['bold']}{self.colors['yellow']}{text}{self.colors['reset']}\n" \
+               f"{self.colors['yellow']}{'-' * len(text)}{self.colors['reset']}"
+    
+    def _format_player_name(self, name: str, is_current: bool = False) -> str:
+        """Format a player name with highlighting if current."""
+        if is_current:
+            return f"{self.colors['bold']}{self.colors['green']}► {name}{self.colors['reset']}"
+        else:
+            return f"{self.colors['white']}{name}{self.colors['reset']}"
+    
+    def _format_resource_card(self, card: ResCard) -> str:
+        """Format a resource card with appropriate color."""
+        card_colors = {
+            ResCard.Wood: 'green',
+            ResCard.Brick: 'red',
+            ResCard.Wheat: 'yellow',
+            ResCard.Sheep: 'white',
+            ResCard.Ore: 'purple'
+        }
+        color = card_colors.get(card, 'white')
+        return f"{self.colors[color]}{card.name}{self.colors['reset']}"
+    
+    def _format_building(self, building_type: str, count: int) -> str:
+        """Format building information."""
+        if count == 0:
+            return f"{building_type}: {self.colors['red']}0{self.colors['reset']}"
+        else:
+            return f"{building_type}: {self.colors['green']}{count}{self.colors['reset']}"
+    
+    def _convert_gamestate_to_dict(self, game_state: Any) -> Dict[str, Any]:
+        """Convert GameState object to dictionary format expected by visualization."""
+        # If it's already a dict, return it
+        if isinstance(game_state, dict):
+            return game_state
+            
+        # It's a GameState object
+        state_dict = {
+            'turn_number': game_state.turn_number,
+            'current_player_index': game_state.current_player,
+            'players': []
+        }
+        
+        # Convert players
+        for p in game_state.players_state:
+            player_dict = {
+                'name': p.name,
+                'victory_points': p.victory_points,
+                'cards': p.cards,
+                'dev_cards': p.dev_cards,
+                'settlements': len(p.settlements),
+                'cities': len(p.cities),
+                'roads': len(p.roads)
+            }
+            state_dict['players'].append(player_dict)
+            
+        # Find current player name
+        current_player_name = "Unknown"
+        for p in game_state.players_state:
+            if p.player_id == game_state.current_player:
+                current_player_name = p.name
+                break
+        state_dict['current_player_name'] = current_player_name
+        
+        # Board
+        state_dict['board'] = {
+            'robber_position': game_state.board_state.robber_position,
+            'tiles': game_state.board_state.tiles
+        }
+        
+        return state_dict
+
+    def display_game_state(self, game_state: Any) -> None:
+        """Display the complete game state."""
+        if not self.enabled:
+            return
+            
+        # Convert GameState object to dict if needed
+        game_state = self._convert_gamestate_to_dict(game_state)
+        
+        self._print(self._format_header("GAME STATE"))
+        
+        # Turn information
+        self._print(f"Turn: {self.colors['bold']}{game_state.get('turn_number', 'N/A')}{self.colors['reset']}")
+        self._print(f"Current Player: {self._format_player_name(game_state.get('current_player_name', 'N/A'), True)}")
+        
+        # Players information
+        players = game_state.get('players', [])
+        if players:
+            self._print(self._format_subheader("PLAYERS"))
+            
+            for i, player in enumerate(players):
+                is_current = i == game_state.get('current_player_index', -1)
+                player_name = player.get('name', f'Player {i}')
+                
+                self._print(f"\n{self._format_player_name(player_name, is_current)}")
+                
+                # Victory points
+                vp = player.get('victory_points', 0)
+                vp_color = 'green' if vp >= 10 else 'white'
+                self._print(f"  Victory Points: {self.colors[vp_color]}{vp}{self.colors['reset']}")
+                
+                # Resource cards
+                cards = player.get('cards', [])
+                card_counts = {}
+                for card in cards:
+                    card_counts[card] = card_counts.get(card, 0) + 1
+                
+                if card_counts:
+                    self._print(f"  Resources: ", end="")
+                    card_strs = []
+                    for card_type in [ResCard.Wood, ResCard.Brick, ResCard.Wheat, ResCard.Sheep, ResCard.Ore]:
+                        count = card_counts.get(card_type, 0)
+                        if count > 0:
+                            card_strs.append(f"{self._format_resource_card(card_type)}×{count}")
+                    self._print(", ".join(card_strs) if card_strs else "None")
+                else:
+                    self._print(f"  Resources: None")
+                
+                # Development cards
+                dev_cards = player.get('dev_cards', [])
+                if dev_cards:
+                    self._print(f"  Dev Cards: {len(dev_cards)}")
+                
+                # Buildings
+                settlements = player.get('settlements', 0)
+                cities = player.get('cities', 0) 
+                roads = player.get('roads', 0)
+                self._print(f"  Buildings: {self._format_building('Settlements', settlements)}, " \
+                      f"{self._format_building('Cities', cities)}, " \
+                      f"{self._format_building('Roads', roads)}")
+        
+        # Board information (simplified)
+        board = game_state.get('board', {})
+        if board:
+            self._print(self._format_subheader("BOARD"))
+            
+            # Robber position
+            robber_pos = game_state.get('robber_position')
+            if robber_pos:
+                self._print(f"Robber Position: {robber_pos}")
+            
+            # Additional board info could be added here
+            if not self.compact_mode:
+                tiles = board.get('tiles', [])
+                if tiles:
+                    self._print(f"Board Tiles: {len(tiles)} tiles configured")
+        
+        self._print()  # Empty line at end
+    
+    def display_action(self, action: Action, result: ActionResult) -> None:
+        """Display a single action and its result."""
+        if not self.enabled:
+            return
+        
+        # Determine result color
+        if result.success:
+            result_color = 'green'
+            result_symbol = '✓'
+        else:
+            result_color = 'red'
+            result_symbol = '✗'
+        
+        # Format action description
+        action_desc = self._get_action_description(action)
+        
+        self._print(f"{self.colors[result_color]}{result_symbol}{self.colors['reset']} {action_desc}")
+        
+        if not result.success and result.error_message:
+            self._print(f"  {self.colors['red']}Error: {result.error_message}{self.colors['reset']}")
+        elif result.success and result.error_message:
+            self._print(f"  {self.colors['green']}{result.error_message}{self.colors['reset']}")
+    
+    def display_turn_start(self, player_name: str, turn_number: int) -> None:
+        """Display turn start notification."""
+        if not self.enabled:
+            return
+        
+        self._print(f"\n{self.colors['bold']}{self.colors['blue']}>>> Turn {turn_number}: {player_name}'s turn{self.colors['reset']}")
+    
+    def display_dice_roll(self, player_name: str, dice_values: List[int], total: int) -> None:
+        """Display dice roll results."""
+        if not self.enabled:
+            return
+        
+        dice_str = " + ".join(str(d) for d in dice_values)
+        total_color = 'red' if total == 7 else 'white'
+        
+        self._print(f"\n{self.colors['bold']}🎲 {player_name} rolled: " \
+              f"{dice_str} = {self.colors[total_color]}{total}{self.colors['reset']}")
+    
+    def display_resource_distribution(self, distributions: Dict[str, List[str]]) -> None:
+        """Display resource distribution from dice roll."""
+        if not self.enabled:
+            return
+        
+        if not distributions:
+            self._print("No resources were distributed.")
+            return
+        
+        self._print("\n📦 Resources distributed:")
+        for player_name, resources in distributions.items():
+            if resources:
+                resource_str = ", ".join(resources)
+                self._print(f"  {player_name}: {self.colors['green']}{resource_str}{self.colors['reset']}")
+    
+    def display_error(self, message: str) -> None:
+        """Display error message."""
+        if not self.enabled:
+            return
+        
+        self._print(f"{self.colors['red']}❌ Error: {message}{self.colors['reset']}")
+    
+    def display_message(self, message: str) -> None:
+        """Display general information message."""
+        if not self.enabled:
+            return
+        
+        self._print(f"{self.colors['cyan']}ℹ️  {message}{self.colors['reset']}")
+    
+    def _get_action_description(self, action: Action) -> str:
+        """Get a human-readable description of an action."""
+        player_name = action.parameters.get('player_name', f'Player {action.player_id}')
+        
+        if action.action_type in [ActionType.BUILD_SETTLEMENT, ActionType.PLACE_STARTING_SETTLEMENT]:
+            return f"{player_name} built a settlement"
+        elif action.action_type == ActionType.BUILD_CITY:
+            return f"{player_name} built a city"
+        elif action.action_type in [ActionType.BUILD_ROAD, ActionType.PLACE_STARTING_ROAD]:
+            return f"{player_name} built a road"
+        elif action.action_type == ActionType.TRADE_BANK:
+            given = action.parameters.get('give', 'resources')
+            received = action.parameters.get('receive', 'resources')
+            return f"{player_name} traded {given} for {received} with bank"
+        elif action.action_type == ActionType.TRADE_PROPOSE:
+            return f"{player_name} proposed a trade"
+        elif action.action_type == ActionType.BUY_DEV_CARD:
+            return f"{player_name} bought a development card"
+        elif action.action_type == ActionType.USE_DEV_CARD:
+            card_type = action.parameters.get('card_type', 'development card')
+            return f"{player_name} used {card_type}"
+        elif action.action_type == ActionType.END_TURN:
+            return f"{player_name} ended their turn"
+        elif action.action_type == ActionType.ROLL_DICE:
+            return f"{player_name} rolled the dice"
+        else:
+            return f"{player_name} performed {action.action_type.value}"
+    
+    def clear_screen(self) -> None:
+        """Clear the console screen (platform dependent)."""
+        import os
+        os.system('cls' if os.name == 'nt' else 'clear')
+    
+    def set_compact_mode(self, enabled: bool) -> None:
+        """Enable or disable compact display mode."""
+        self.compact_mode = enabled
+    
+    def set_colors(self, enabled: bool) -> None:
+        """Enable or disable color output."""
+        self.use_colors = enabled
+        if not enabled:
+            self.colors = {key: '' for key in self.colors.keys()}
+    
+    def display_board_layout(self, game_state: Dict[str, Any]) -> None:
+        """
+        Display the complete board layout with tiles, numbers and robber position.
+        This shows all the hexagonal tiles, their resource types, and dice numbers.
+        """
+        if not self.enabled:
+            return
+        
+        print(self._format_header("BOARD LAYOUT"))
+        
+        # Handle both Game objects and dict game states
+        if hasattr(game_state, 'board'):
+            # This is a Game object - use its board directly
+            self._display_real_board_tiles(game_state.board.tiles)
+            
+            # Get robber position from game if available
+            robber_pos = getattr(game_state, 'robber_pos', None)
+            if robber_pos:
+                print(f"\n{self.colors['red']}🛡️  Robber Position: {robber_pos}{self.colors['reset']}")
+        else:
+            # This is a dict game_state - try to extract board info
+            board = game_state.get('board_state', {}) or game_state.get('board', {})
+            tiles = board.get('tiles', [])
+            
+            if tiles:
+                self._display_dict_board_tiles(tiles)
+            else:
+                print("No board tiles found in game state!")
+                print("Note: This display works with full Game objects.")
+            
+            # Show robber position from dict
+            robber_pos = game_state.get('robber_position')
+            if robber_pos:
+                print(f"\n{self.colors['red']}🛡️  Robber Position: {robber_pos}{self.colors['reset']}")
+        
+        print()
+    
+    def _display_real_board_tiles(self, tiles):
+        """Display tiles from actual Game.board.tiles structure."""
+        print("📋 Board Tiles (by rows):")
+        print()
+        
+        # Group tiles by rows
+        tiles_by_row = {}
+        tile_count = 0
+        
+        for row_index, tile_row in enumerate(tiles):
+            if not tile_row:  # Skip empty rows
+                continue
+                
+            tiles_by_row[row_index] = []
+            for col_index, tile in enumerate(tile_row):
+                if tile:  # Only count non-None tiles
+                    tile_count += 1
+                    tiles_by_row[row_index].append((col_index, tile, tile_count))
+        
+        # Display each row
+        for row in sorted(tiles_by_row.keys()):
+            if not tiles_by_row[row]:  # Skip empty rows
+                continue
+                
+            print(f"{self.colors['yellow']}Row {row}:{self.colors['reset']}")
+            
+            for col, tile, tile_num in tiles_by_row[row]:
+                # Get tile information
+                tile_type = self._get_tile_type_name(tile)
+                tile_number = self._get_tile_number(tile)
+                
+                # Color coding for tile types
+                tile_color = self._get_tile_color(tile_type)
+                
+                # Format tile display
+                tile_display = f"{self.colors[tile_color]}{tile_type:<10}{self.colors['reset']}"
+                number_display = f"({tile_number:>2})" if tile_number != 'N/A' else "    "
+                
+                print(f"  [{tile_num:>2}] {tile_display} {number_display} at [{row},{col}]")
+            print()
+        
+        print(f"Total: {tile_count} tiles on the board")
+    
+    def _display_dict_board_tiles(self, tiles):
+        """Display tiles from dictionary format (fallback)."""
+        print("📋 Board Tiles:")
+        print()
+        
+        for i, tile in enumerate(tiles, 1):
+            # Handle dict format
+            if isinstance(tile, dict):
+                tile_type = tile.get('type', 'Unknown')
+                tile_number = tile.get('number', 'N/A')
+                position = tile.get('position', ['?', '?'])
+            else:
+                tile_type = 'Unknown'
+                tile_number = 'N/A' 
+                position = ['?', '?']
+            
+            # Color coding
+            tile_color = self._get_tile_color(tile_type)
+            
+            # Format display
+            tile_display = f"{self.colors[tile_color]}{tile_type:<10}{self.colors['reset']}"
+            number_display = f"({tile_number:>2})" if tile_number != 'N/A' else "    "
+            
+            print(f"  [{i:>2}] {tile_display} {number_display} at {position}")
+    
+    def _get_tile_type_name(self, tile):
+        """Get the tile type name from a tile object."""
+        # Try different attribute names
+        if hasattr(tile, 'tile_type'):
+            tile_type = tile.tile_type
+        elif hasattr(tile, 'type'):
+            tile_type = tile.type
+        else:
+            return 'Unknown'
+        
+        # Handle different formats
+        if hasattr(tile_type, 'name'):
+            return tile_type.name
+        elif hasattr(tile_type, 'value'):
+            # Handle enum by value
+            type_names = {
+                0: 'Desert', 1: 'Fields', 2: 'Pasture', 
+                3: 'Mountains', 4: 'Hills', 5: 'Forest'
+            }
+            return type_names.get(tile_type.value, 'Unknown')
+        else:
+            return str(tile_type)
+    
+    def _get_tile_number(self, tile):
+        """Get the tile number from a tile object."""
+        # Try different attribute names
+        if hasattr(tile, 'number') and tile.number is not None:
+            return tile.number
+        elif hasattr(tile, 'token_num') and tile.token_num is not None:
+            return tile.token_num
+        else:
+            return 'N/A'
+    
+    def _get_tile_color(self, tile_type):
+        """Get the appropriate color for a tile type."""
+        tile_colors = {
+            'Forest': 'green', 'FOREST': 'green', 'wood': 'green',
+            'Hills': 'red', 'HILLS': 'red', 'brick': 'red', 
+            'Fields': 'yellow', 'FIELDS': 'yellow', 'wheat': 'yellow',
+            'Pasture': 'white', 'PASTURE': 'white', 'sheep': 'white',
+            'Mountains': 'purple', 'MOUNTAINS': 'purple', 'ore': 'purple',
+            'Desert': 'cyan', 'DESERT': 'cyan', 'desert': 'cyan'
+        }
+        return tile_colors.get(tile_type, 'white')
+    
+    def display_points_reference(self) -> None:
+        """
+        Display the point mapping reference (1-54) organized by board sections.
+        This helps players understand which point numbers correspond to which locations.
+        """
+        if not self.enabled:
+            return
+        
+        print(self._format_header("POINTS REFERENCE (1-54)"))
+        
+        print("Points are numbered 1-54 and represent intersections where you can build settlements/cities.")
+        print(f"{self.colors['yellow']}Use these point numbers when building!{self.colors['reset']}\n")
+        
+        # Organize points by rows (based on actual Catan board layout - 54 points total)
+        points_layout = {
+            "Top Row (7 points)": list(range(1, 8)),          # Points 1-7
+            "Second Row (9 points)": list(range(8, 17)),      # Points 8-16  
+            "Third Row (11 points)": list(range(17, 28)),     # Points 17-27
+            "Fourth Row (11 points)": list(range(28, 39)),    # Points 28-38
+            "Fifth Row (9 points)": list(range(39, 48)),      # Points 39-47
+            "Bottom Row (7 points)": list(range(48, 55))      # Points 48-54
+        }
+        
+        for section_name, points in points_layout.items():
+            print(f"{self.colors['cyan']}{section_name}:{self.colors['reset']}")
+            
+            # Display points in rows of 6 for better readability
+            for i in range(0, len(points), 6):
+                row_points = points[i:i+6]
+                formatted_points = [f"{self.colors['green']}{p:>2}{self.colors['reset']}" for p in row_points]
+                print(f"  {' '.join(formatted_points)}")
+            print()
+        
+        print(f"{self.colors['yellow']}💡 Tip: Use 'overview' command to see the full board with both tiles and points!{self.colors['reset']}")
+        print()
+    
+    def display_robber_info(self, game_state: Dict[str, Any]) -> None:
+        """
+        Display information about the robber's current position and effects.
+        """
+        if not self.enabled:
+            return
+        
+        print(self._format_header("ROBBER INFORMATION"))
+        
+        robber_pos = game_state.get('robber_position')
+        
+        if robber_pos:
+            print(f"🛡️  {self.colors['red']}Robber is currently at position: {robber_pos}{self.colors['reset']}")
+            
+            # Try to find which tile the robber is on
+            board = game_state.get('board_state', {}) or game_state.get('board', {})
+            tiles = board.get('tiles', [])
+            
+            robber_tile = None
+            for i, tile in enumerate(tiles):
+                tile_pos = None
+                if hasattr(tile, 'position'):
+                    tile_pos = tile.position
+                elif isinstance(tile, dict) and 'position' in tile:
+                    tile_pos = tile['position']
+                
+                if tile_pos and list(tile_pos) == robber_pos:
+                    robber_tile = tile
+                    break
+            
+            if robber_tile:
+                # Get tile type
+                if hasattr(robber_tile, 'tile_type'):
+                    tile_type = robber_tile.tile_type.name if hasattr(robber_tile.tile_type, 'name') else str(robber_tile.tile_type)
+                elif isinstance(robber_tile, dict) and 'type' in robber_tile:
+                    tile_type = robber_tile['type']
+                else:
+                    tile_type = 'Unknown'
+                
+                # Get tile number
+                if hasattr(robber_tile, 'number'):
+                    tile_number = robber_tile.number
+                elif isinstance(robber_tile, dict) and 'number' in robber_tile:
+                    tile_number = robber_tile['number']
+                else:
+                    tile_number = 'N/A'
+                
+                print(f"📍 This is a {self.colors['yellow']}{tile_type}{self.colors['reset']} tile with number {self.colors['bold']}{tile_number}{self.colors['reset']}")
+                print(f"⚠️  {self.colors['red']}This tile does not produce resources while the robber is there!{self.colors['reset']}")
+            
+            print(f"\n{self.colors['cyan']}Robber Effects:{self.colors['reset']}")
+            print("  • Blocks resource production on the occupied tile")
+            print("  • Can steal cards from players with settlements/cities on that tile")
+            print("  • Moved when a 7 is rolled or when a Knight card is played")
+        else:
+            print("🤔 Robber position not found in game state.")
+        
+        print()
+    
+    def display_game_overview(self, game_state: Dict[str, Any]) -> None:
+        """
+        Display a comprehensive overview of the entire game including board, players, and current state.
+        This is the "everything at once" view for players who want complete information.
+        """
+        if not self.enabled:
+            return
+        
+        print(self._format_header("COMPLETE GAME OVERVIEW"))
+        
+        # Game status
+        turn_num = game_state.get('turn_number', 'N/A')
+        current_player = game_state.get('current_player_name', 'N/A')
+        print(f"🎲 {self.colors['bold']}Turn {turn_num} - {current_player}'s Turn{self.colors['reset']}")
+        print()
+        
+        # Quick board summary
+        board = game_state.get('board_state', {}) or game_state.get('board', {})
+        tiles = board.get('tiles', [])
+        
+        if tiles:
+            # Count tile types
+            tile_counts = {}
+            for tile in tiles:
+                tile_type = 'Unknown'
+                if hasattr(tile, 'tile_type'):
+                    tile_type = tile.tile_type.name if hasattr(tile.tile_type, 'name') else str(tile.tile_type)
+                elif isinstance(tile, dict) and 'type' in tile:
+                    tile_type = tile['type']
+                
+                tile_counts[tile_type] = tile_counts.get(tile_type, 0) + 1
+            
+            print(f"{self.colors['cyan']}📋 Board Summary:{self.colors['reset']}")
+            for tile_type, count in tile_counts.items():
+                print(f"  {tile_type}: {count} tiles")
+            print()
+        
+        # Robber info (condensed)
+        robber_pos = game_state.get('robber_position')
+        if robber_pos:
+            print(f"🛡️  {self.colors['red']}Robber at: {robber_pos}{self.colors['reset']}")
+        
+        # Players summary
+        players = game_state.get('players', [])
+        if players:
+            print(f"\n{self.colors['cyan']}👥 Players Status:{self.colors['reset']}")
+            for i, player in enumerate(players):
+                is_current = i == game_state.get('current_player_index', -1)
+                player_name = player.get('name', f'Player {i}')
+                vp = player.get('victory_points', 0)
+                
+                indicator = "👑" if is_current else "  "
+                vp_indicator = "🏆" if vp >= 10 else f"{vp}VP"
+                
+                cards_count = len(player.get('cards', []))
+                buildings = f"S:{player.get('settlements', 0)} C:{player.get('cities', 0)} R:{player.get('roads', 0)}"
+                
+                print(f"{indicator} {self.colors['bold'] if is_current else ''}{player_name:<12}{self.colors['reset']} " \
+                      f"{vp_indicator:<4} {cards_count:>2}cards {buildings}")
+        
+        print(f"\n{self.colors['yellow']}💡 Commands:{self.colors['reset']}")
+        print("  'points'    - Show detailed point reference (1-54)")
+        print("  'board'     - Show detailed board layout") 
+        print("  'robber'    - Show robber information")
+        print("  'help'      - Show all available commands")
+        print()

pycatan/default_board.py

@@ -0,0 +1,230 @@
+from pycatan.board import Board
+from pycatan.tile import Tile
+from pycatan.point import Point
+from pycatan.tile_type import TileType
+from pycatan.harbor import Harbor, HarborType
+
+import math
+import random
+
+# The default, tileagonal board filled with random tiles and tokens
+class DefaultBoard(Board):
+
+    def __init__(self, game):
+        super(DefaultBoard, self).__init__(game)
+
+        # Set tiles
+        tile_deck = Board.get_shuffled_tile_deck()
+        token_deck = Board.get_shuffled_tile_nums()
+        temp_tiles = []
+        for r in range(5):
+            temp_tiles.append([])
+            for i in range([3, 4, 5, 4, 3][r]):
+                # Add a tile
+                new_tile = Tile(type=tile_deck.pop(), token_num=None, position=[r, i], points=[])
+                temp_tiles[-1].append(new_tile)
+                # Remove the token if it is the desert
+                if new_tile.type == TileType.Desert:
+                    self.robber = [r, i]
+                else:
+                    new_tile.token_num = token_deck.pop()
+
+        self.tiles = tuple(map(lambda x: tuple(x), temp_tiles))
+
+        # Add points
+        temp_points = []
+        for r in range(6):
+            temp_points.append([])
+            for i in range([7, 9, 11, 11, 9, 7][r]):
+                point = Point(tiles=[], position=[r, i])
+                temp_points[-1].append(point)
+                # Set point/tile relations
+                for pos in DefaultBoard.get_tile_indexes_for_point(r, i):
+                    point.tiles.append(self.tiles[pos[0]][pos[1]])
+                    self.tiles[pos[0]][pos[1]].points.append(point)
+
+
+        self.points = tuple(map(lambda x: tuple(x), temp_points))
+        # Set the connected points for each point
+        # Must be done after initializing each point so that the point object exists
+        for r in self.points:
+            for p in r:
+                p.connected_points = self.get_connected_points(p.position[0], p.position[1])
+        # adds a harbor for each points in the pattern 2 3 2 2 3 2 etc
+        outside_points = DefaultBoard.get_outside_points()
+        # the pattern of spaces between harbors
+        pattern = [1, 2, 1]
+        # the current index of pattern
+        index = 0
+        # the different types of harbors
+        harbor_types = [
+            HarborType.Wood,
+            HarborType.Brick,
+            HarborType.Ore,
+            HarborType.Wheat,
+            HarborType.Sheep,
+            HarborType.Any,
+            HarborType.Any,
+            HarborType.Any,
+            HarborType.Any
+        ]
+        # Shuffles the harbors
+        random.shuffle(harbor_types)
+        # Run loop until harbor_types is empty
+        while harbor_types:
+            # Create a new harbor
+            p_one = outside_points.pop()
+            p_two = outside_points.pop()
+            harbor = Harbor(
+                point_one = self.points[p_one[0]][p_one[1]],
+                point_two = self.points[p_two[0]][p_two[1]],
+                type = harbor_types.pop())
+            # Add it to harbors
+            self.harbors.append(harbor)
+            # Remove the unused points from outside_points
+            for _ in range(pattern[index % len(pattern)]):
+                outside_points.pop()
+            # Use next pattern value for number of points inbetween next time
+            index += 1
+
+        # puts the robber on the desert tile to start
+        for r in range(len(temp_tiles)):
+            # checks if this row has the desert
+            if temp_tiles[r].count(TileType.Desert) > 0:
+                # places the robber
+                self.robber = [r, temp_tiles[r].index(TileType.Desert)]
+
+    # Returns the indexes of the tiles connected to a certain points
+    # on the default, tileagonal Catan board
+    @staticmethod
+    def get_tile_indexes_for_point(r, i):
+        # the indexes of the tiles
+        tile_indexes = []
+        # Points on a tileagonal board
+        points = [
+            [None] * 7,
+            [None] * 9,
+            [None] * 11,
+            [None] * 11,
+            [None] * 9,
+            [None] * 7
+        ]
+        # gets the adjacent tiles differently depending on whether the point is in the top or the bottom
+        if r < len(points) / 2:
+            # gets the tiles below the point ------------------
+
+            # adds the tiles to the right
+            if i < len(points[r]) - 1:
+                tile_indexes.append([r, math.floor(i / 2)])
+
+            # if the index is even, the number is between two tiles
+            if i % 2 == 0 and i > 0:
+                tile_indexes.append([r, math.floor(i / 2) - 1])
+
+            # gets the tiles above the point ------------------
+
+            if r > 0:
+                # gets the tile to the right
+                if i > 0 and i < len(points[r]) - 2:
+                    tile_indexes.append([r - 1, math.floor((i - 1) / 2)])
+
+                # gets the tile to the left
+                if i % 2 == 1 and i < len(points[r]) - 1 and i > 1:
+                    tile_indexes.append([r - 1, math.floor((i - 1) / 2) - 1])
+
+        else:
+
+            # adds the below -------------
+
+            if r < len(points) - 1:
+                # gets the tile to the right or directly below
+                if i < len(points[r]) - 2 and i > 0:
+                    tile_indexes.append([r, math.floor((i - 1) / 2)])
+
+                # gets the tile to the left
+                if i % 2 == 1 and i > 1 and i < len(points[r]):
+                    tile_indexes.append([r, math.floor((i - 1) / 2 - 1)])
+
+            # gets the tiles above ------------
+
+            # gets the tile above and to the right or directly above
+            if i < len(points[r]) - 1:
+                tile_indexes.append([r - 1, math.floor(i / 2)])
+
+            # gets the tile to the left
+            if i > 1 and i % 2 == 0:
+                tile_indexes.append([r - 1, math.floor((i - 1) / 2)])
+
+        return tile_indexes
+
+    # gets the points that are connected to the point given
+    def get_connected_points(self, r, i):
+        to_return = []
+        # Get the point to the left and the right
+        if i > 0:
+            to_return.append(self.points[r][i - 1])
+
+        if i < len(self.points[r]) - 1:
+            to_return.append(self.points[r][i + 1])
+
+        # Get the point above and below
+        # First, if the point is in the center two rows, the connected point
+        # is either directly above/below this point
+        if r == 2 and i % 2 == 0:
+            to_return.append(self.points[r + 1][i])
+        elif r == 3 and i % 2 == 0:
+            to_return.append(self.points[r - 1][i])
+        # If the point is not in the 2 center rows, the point will have an offset
+        elif r < len(self.points) / 2:
+            if i % 2 == 0:
+                to_return.append(self.points[r + 1][i + 1])
+            elif r > 0 and i > 0:
+                to_return.append(self.points[r - 1][i - 1])
+        else:
+            if i % 2 == 0:
+                to_return.append(self.points[r - 1][i + 1])
+            elif r < len(self.points) - 1 and i > 0:
+                to_return.append(self.points[r + 1][i - 1])
+        return to_return
+
+    # Get the points along the outside of the board, in clockwise order
+    @staticmethod
+    def get_outside_points():
+        # The lengths of each row of points on the board
+        row_lengths = [
+            7,
+            9,
+            11,
+            11,
+            9,
+            7
+        ]
+        # The points on the bottom
+        bottom = list(map(lambda x: [len(row_lengths) - 1, x], range(row_lengths[-1])))
+        # The points on the top
+        top = list(map(lambda x: [0, x], range(row_lengths[0])))
+        # adds all the points on the right and left
+        right = []
+        left = []
+        for r in range(1, len(row_lengths) - 1):
+            # Get the last two and first two points on this row
+            last_two = list(map(lambda x: [r, x], range(row_lengths[r])[-2:]))
+            first_two = list(map(lambda x: [r, x], reversed(range(2))))
+            # If the points are one the bottom half of the board, reverse them
+            if r > (len(row_lengths) - 1) / 2:
+                last_two = list(reversed(last_two))
+                first_two = list(reversed(first_two))
+            # Add points to right and left
+            right.extend(last_two)
+            left.extend(first_two)
+
+        # Put different sides of points in order
+        # bottom and left are reversed since we want to count those points in reverse order
+        # to make sure we go in clockwise order
+        outside_points = []
+        outside_points.extend(top)
+        outside_points.extend(right)
+        outside_points.extend(reversed(bottom))
+        outside_points.extend(reversed(left))
+        # Return them
+        return outside_points

pycatan/game.py

@@ -0,0 +1,508 @@
+from pycatan.default_board import DefaultBoard
+from pycatan.player import Player
+from pycatan.statuses import Statuses
+from pycatan.card import ResCard, DevCard
+from pycatan.building import Building
+from pycatan.harbor import Harbor
+from pycatan.board_definition import board_definition
+
+import random
+import math
+
+class Game:
+
+    # initializes the  game
+    def __init__(self, num_of_players=3, on_win=None, starting_board=False):
+        # creates a board
+        self.board = DefaultBoard(game=self);
+        # creates players
+        self.players = []
+        for i in range(num_of_players):
+            self.players.append(Player(num=i, game=self))
+        # Set onWin method
+        self.on_win = on_win
+        # creates a new Developement deck
+        self.dev_deck = []
+        for i in range(14):
+            # Add 2 Road, Monopoly and Year of Plenty cards
+            if i < 2:
+                self.dev_deck.append(DevCard.Road)
+                self.dev_deck.append(DevCard.Monopoly)
+                self.dev_deck.append(DevCard.YearOfPlenty)
+            # Add 5 Victory Point cards
+            if i < 5:
+                self.dev_deck.append(DevCard.VictoryPoint)
+            # Add 14 knight cards
+            self.dev_deck.append(DevCard.Knight)
+        # Shuffle the developement deck
+        random.shuffle(self.dev_deck)
+        # the longest road owner and largest army owner
+        self.longest_road_owner = None
+        self.largest_army = None
+        # whether the game has finished or not
+        self.has_ended = False
+
+    # creates a new settlement belong to the player at the coodinates
+    def add_settlement(self, player, point, is_starting=False):
+        # builds the settlement
+        status = self.players[player].build_settlement(point=point, is_starting=is_starting)
+        # If successful, check if the player has now won
+        if status == Statuses.ALL_GOOD:
+            if self.players[player].get_VP() >= 10:
+                # End the game
+                self.has_ended = True
+                self.winner = player
+
+        return status
+
+    # builds a road going from point start to point end
+    def add_road(self, player, start, end, is_starting=False):
+        # builds the road
+        stat = self.players[player].build_road(start=start, end=end, is_starting=is_starting)
+        # checks for a new longest road segment
+        self.set_longest_road()
+        # returns the status
+        return stat
+
+    # builds a new developement cards for the player
+    def build_dev(self, player):
+        # makes sure there is still at least one development card left
+        if len(self.dev_deck) < 1:
+            return Statuses.ERR_DECK
+        # makes sure the player has the right cards
+        needed_cards = [
+            ResCard.Wheat,
+            ResCard.Ore,
+            ResCard.Sheep
+        ]
+        if not self.players[player].has_cards(needed_cards):
+            return Statuses.ERR_CARDS
+        # removes the cards
+        self.players[player].remove_cards(needed_cards)
+        # gives the player a dev card
+        self.players[player].add_dev_card(self.dev_deck[0])
+        # removes that dev card from the deck
+        del self.dev_deck[0]
+
+    # gives players the proper cards for a given roll
+    def add_yield_for_roll(self, roll):
+        return self.board.add_yield(roll)
+
+    # trades cards (given in an array) between two players
+    def trade(self, player_one, player_two, cards_one, cards_two):
+        # check if they players have the cards they are trading
+        # Needs to do this before deleting because one might have the cards while the other does not
+        if not self.players[player_one].has_cards(cards_one):
+            return Statuses.ERR_CARDS
+
+        elif not self.players[player_two].has_cards(cards_two):
+            return Statuses.ERR_CARDS
+
+        else:
+            # removes the cards
+            self.players[player_one].remove_cards(cards_one)
+            self.players[player_two].remove_cards(cards_two)
+            # add the new cards
+            self.players[player_one].add_cards(cards_two)
+            self.players[player_two].add_cards(cards_one)
+            return Statuses.ALL_GOOD
+
+    # moves the robber
+    # Note that player is the player moving the robber
+    # and victim is the player whose card is being taken
+    def move_robber(self, tile, player, victim):
+        # checks the player wants to take a card from somebody
+        if victim != None:
+            # checks the victim has a settlement on the tile
+            has_settlement = False
+            # Iterate over points and check if there is a settlement/city on any of them
+            points = self.board.get_connected_points(tile.position[0], tile.position[1])
+            for p in points:
+                if p != None and p.building != None:
+                    # Check the victim owns the settlement/city
+                    if p.building.owner == victim:
+                        has_settlement = True
+
+            if not has_settlement:
+                return Statuses.ERR_INPUT
+
+        # moves the robber
+        self.board.move_robber(tile)
+        # takes a random card from the victim
+        if victim != None:
+            # removes a random card from the victim
+            index = round(random.random() * (len(self.players[victim].cards) - 1))
+            card = self.players[victim].cards[index]
+            self.players[victim].remove_cards([card])
+            # adds it to the player
+            self.players[player].add_cards([card])
+
+        return Statuses.ALL_GOOD
+
+    # trades cards from a player to the bank
+    # either by 4 for 1 or using a harbor
+    def trade_to_bank(self, player, cards, request):
+        # makes sure the player has the cards
+        if not self.players[player].has_cards(cards):
+            return Statuses.ERR_CARDS
+        # checks all the cards are the same type
+        card_type = cards[0]
+        for c in cards[1:]:
+            if c != card_type:
+                return Statuses.ERR_CARDS
+        # if there are not four cards
+        if len(cards) != 4:
+            # checks if the player has a settlement on the right type of harbor
+            has_harbor = False
+            harbor_types = self.players[player].get_connected_harbor_types()
+            print(harbor_types)
+            for h_type in harbor_types:
+                if Harbor.get_card_from_harbor_type(h_type) == card_type and len(cards) == 2:
+                    has_harbor = True
+                    break
+                elif Harbor.get_card_from_harbor_type(h_type) == None and len(cards) == 3:
+                    has_harbor = True
+                    break
+
+            if not has_harbor:
+                return Statuses.ERR_HARBOR
+
+        # removes cards
+        self.players[player].remove_cards(cards)
+        # adds the new card
+        self.players[player].add_cards([request])
+
+        return Statuses.ALL_GOOD
+
+    # gives the longest road to the correct player
+    def set_longest_road(self):
+        # The length of the current longest road segment
+        longest = 0
+        owner = self.longest_road_owner
+
+        for p in self.players:
+            # longest road needs to be longer than anbody else's
+            # and at least 5 road segments long
+            if p.longest_road_length > longest and p.longest_road_length >= 5:
+                longest = p.longest_road_length
+                owner = self.players.index(p)
+
+        if self.longest_road_owner != owner:
+            self.longest_road_owner = owner
+            # checks if the player has won now that they has longest road
+            if self.players[owner].get_VP() >= 10:
+                self.has_ended = True
+                self.winner = owner
+
+    # changes a settlement on the board for a city
+    def add_city(self, point, player):
+        status = self.board.upgrade_settlement(player, r, i)
+
+        if status == Statuses.ALL_GOOD:
+            # checks if the player won
+            if self.players[player].get_VP() >= 10:
+                self.winner = player
+
+        return status
+
+    # uses a developement card
+    # the required args will vary between different dev cards
+    def use_dev_card(self, player, card, args):
+        # checks the player has the development card
+        if not self.players[player].has_dev_cards([card]):
+            return Statuses.ERR_CARDS
+
+        # applies the action
+        if card == DevCard.Road:
+            # checks the correct arguments are given
+            road_names = [
+                "road_one",
+                "road_two"
+            ]
+            for r in road_names:
+                if not r in args:
+                    return Statuses.ERR_INPUT
+
+                else:
+                    # Check the roads have a start and an end
+                    if not "start" in args[r] or not "end" in args[r]:
+                        return Statuses.ERR_INPUT
+
+            # checks the road location is valid
+
+            # whether the other road is completely isolated but is connected to this road
+            other_road_is_isolated = False
+
+            for r in road_names:
+                location_status = self.players[player].road_location_is_valid(args[r]['start'], args[r]['end'])
+
+                # if the road location is not OK
+                # since the player can build two roads, some
+                # locations that would be invalid are valid depending on the other road location
+                if not location_status == Statuses.ALL_GOOD:
+                    # checks if it is isolated, but would be connected to the other road
+                    if location_status == Statuses.ERR_ISOLATED:
+                        # if the other road is also isolated, just return an error
+                        if other_road_is_isolated:
+                            return location_status
+
+                        # checks if the two roads are connected
+                        # (since the other one is connected, this road is connected through it)
+                        road_points = [
+                            "start",
+                            "end"
+                        ]
+                        roads_are_connected = False
+                        for p_one in road_points:
+                            for p_two in road_points:
+                                if args["road_one"][p_one] == args['road_two'][p_two]:
+                                    other_road_is_isolated = True
+                                    # doesn't return an isolated error
+                                    roads_are_connected = True
+
+                        if not roads_are_connected:
+                            return location_status
+                    else:
+                        return location_status
+
+            # builds the roads
+            for r in road_names:
+                self.board.add_road(Building(point_one=args[r]["start"], point_two=args[r]["end"], owner=player, type=Building.BUILDING_ROAD))
+
+            return Statuses.ALL_GOOD
+
+        elif card == DevCard.Knight:
+            # checks there are the right arguments
+            if not ("robber_pos" in args and "victim" in args):
+                return Statuses.ERR_INPUT
+
+            # checks the victim input is valid
+            if args["victim"] != None:
+                if args["victim"] < 0 or args["victim"] >= len(self.players) or args["victim"] == player:
+                    return Statuses.ERR_INPUT
+
+            # moves the robber
+            result = self.move_robber(r=args["robber_pos"][0], i=args["robber_pos"][1], player=player, victim=args["victim"])
+
+            if result != Statuses.ALL_GOOD:
+                return result
+
+            # adds one to the player's knight count
+            (self.players[player]).knight_cards += 1
+
+            # checks for the largest army
+            if self.largest_army == None:
+                # if nobody has the largest army, the player needs at least 3 cards
+                if self.players[player].knight_cards >= 3:
+                    self.largest_army = player
+
+            else:
+                # the player needs to have more than anybody else
+                current_longest = self.players[self.largest_army].knight_cards
+
+                if self.players[player].knight_cards > current_longest:
+                    self.largest_army = player
+
+        elif card == DevCard.Monopoly:
+            # gets the type of card
+            card_type = args['card_type']
+            # for each player, checks if they have the card
+            for p in self.players:
+                if p.has_cards([card_type]):
+                    # gets how many this player has
+                    number_of_cards = p.cards.count(card_type)
+                    cards_to_give = [card_type] * number_of_cards
+                    # removes the cards
+                    p.remove_cards(cards_to_give)
+                    # adds them to the user's cards
+                    self.players[player].add_cards(cards_to_give)
+
+        elif card == DevCard.VictoryPoint:
+            # players do not play developement cards, so it returns an error
+            return Statuses.ERR_INPUT
+
+        elif card == DevCard.YearOfPlenty:
+            # checks the player gave two development cards
+            if not 'card_one' in args and not 'card_two' in args:
+                return Statuses.ERR_INPUT
+
+            # gives the player 2 resource cards of their choice
+            self.players[player].add_cards([
+                args['card_one'],
+                args['card_two']
+            ])
+
+        else:
+            # error here
+            return Statuses.ERR_INPUT
+
+        # removes the card
+        self.players[player].remove_dev_card(card)
+
+        return Statuses.ALL_GOOD
+
+    # simulates 2 dice rolling
+    def get_roll(self):
+        return round(random.random() * 6) + round(random.random() * 6)
+
+    def get_full_state(self):
+        """
+        Get the complete current state of the game.
+        
+        This method extracts all relevant game state information
+        and returns it in a GameState object for use by the
+        GameManager and visualization systems.
+        
+        Returns:
+            GameState: Complete current game state
+        """
+        from .actions import GameState, PlayerState, BoardState, GamePhase, TurnPhase
+        
+        # Create player states
+        players_state = []
+        for i, player in enumerate(self.players):
+            player_state = PlayerState(
+                player_id=i,
+                name=f"Player {i}",  # Default name - can be enhanced later
+                cards=[card.name.lower() for card in player.cards],  # Convert enum to string
+                dev_cards=[card.name.lower() for card in player.dev_cards],
+                settlements=self._get_player_settlements(player),
+                cities=self._get_player_cities(player),
+                roads=self._get_player_roads(player),
+                victory_points=player.get_VP(),
+                longest_road_length=player.longest_road_length,
+                has_longest_road=(self.longest_road_owner == i),
+                has_largest_army=(self.largest_army == i),
+                knights_played=player.knight_cards
+            )
+            players_state.append(player_state)
+        
+        # Create board state
+        board_state = BoardState(
+            tiles=self._get_tiles_info(),
+            robber_position=tuple(self._get_robber_position()),
+            harbors=self._get_ports_info(),
+            buildings=self._get_all_buildings(),
+            roads=self._get_all_roads()
+        )
+        
+        # Create and return game state
+        return GameState(
+            game_id="current_game",  # Default ID - can be enhanced
+            turn_number=0,  # Basic - can be enhanced
+            current_player=0,  # Basic - managed by GameManager
+            game_phase=GamePhase.NORMAL_PLAY,  # Default to normal play
+            turn_phase=TurnPhase.PLAYER_ACTIONS,  # Default to player actions
+            players_state=players_state,
+            board_state=board_state
+        )
+
+    def _get_player_settlements(self, player):
+        """Get list of settlement coordinates for a player."""
+        settlements = []
+        for point in self.board.points:
+            for p in point:
+                if p and p.building and p.building.type == 0 and p.building.owner == player.num:  # BUILDING_SETTLEMENT = 0
+                    settlements.append(p.position)
+        return settlements
+
+    def _get_player_cities(self, player):
+        """Get list of city coordinates for a player."""
+        cities = []
+        for point in self.board.points:
+            for p in point:
+                if p and p.building and p.building.type == 2 and p.building.owner == player.num:  # BUILDING_CITY = 2
+                    cities.append(p.position)
+        return cities
+
+    def _get_player_roads(self, player):
+        """Get list of road connections for a player."""
+        roads = []
+        for road in self.board.roads:
+            if road and road.owner == player.num and road.type == 1:  # BUILDING_ROAD = 1
+                # Roads connect two points
+                start_pos = road.point_one.position if road.point_one else [0, 0]
+                end_pos = road.point_two.position if road.point_two else [0, 0]
+                roads.append(start_pos + end_pos)  # [start_row, start_col, end_row, end_col]
+        return roads
+
+    def _get_robber_position(self):
+        """Get current robber position."""
+        if hasattr(self.board, 'robber') and self.board.robber:
+            return self.board.robber
+        return [3, 3]  # Default center position if not found
+
+    def _get_tiles_info(self):
+        """Get information about all tiles using BoardDefinition."""
+        tiles = []
+        for i, tile_row in enumerate(self.board.tiles):
+            for j, tile in enumerate(tile_row):
+                if tile:
+                    # Get hex ID from BoardDefinition
+                    hex_id = board_definition.game_coords_to_hex_id(i, j)
+                    # Get axial coordinates for web display
+                    axial_coords = board_definition.hex_id_to_axial_coords(hex_id) if hex_id else (i, j)
+                    
+                    tile_info = {
+                        'id': hex_id or (i * 10 + j),  # Fallback ID if not found
+                        'position': [i, j],  # Game coordinates
+                        'axial_coords': axial_coords,  # Web display coordinates
+                        'type': tile.type.name.lower() if hasattr(tile.type, 'name') else 'desert',
+                        'token': getattr(tile, 'token_num', None),
+                        'has_robber': (self.board.robber == [i, j]) if hasattr(self.board, 'robber') else False
+                    }
+                    tiles.append(tile_info)
+        return tiles
+
+    def _get_ports_info(self):
+        """Get information about all ports/harbors."""
+        ports = []
+        for harbor in self.board.harbors:
+            if harbor:
+                port_info = {
+                    'position': getattr(harbor, 'position', [0, 0]),
+                    'resource': harbor.type.name.lower() if hasattr(harbor.type, 'name') else 'any',
+                    'ratio': getattr(harbor, 'ratio', 3)
+                }
+                ports.append(port_info)
+        return ports
+
+    def _get_all_buildings(self):
+        """Get all buildings on the board using point IDs."""
+        buildings = {}
+        for point_row in self.board.points:
+            for point in point_row:
+                if point and point.building:
+                    # Convert coordinates to point ID using BoardDefinition
+                    point_id = board_definition.game_coords_to_point_id(point.position[0], point.position[1])
+                    
+                    if point_id:
+                        buildings[point_id] = {
+                            'type': 'settlement' if point.building.type == Building.BUILDING_SETTLEMENT else 'city',
+                            'owner': point.building.owner,
+                            'game_coords': point.position  # Keep for debugging
+                        }
+        return buildings
+
+    def _get_all_roads(self):
+        """Get all roads on the board using point IDs."""
+        roads = []
+        for road in self.board.roads:
+            if road and road.type == Building.BUILDING_ROAD:
+                # Convert coordinates to point IDs using BoardDefinition
+                start_coords = road.point_one.position if road.point_one else [0, 0]
+                end_coords = road.point_two.position if road.point_two else [0, 0]
+                
+                start_point_id = board_definition.game_coords_to_point_id(start_coords[0], start_coords[1])
+                end_point_id = board_definition.game_coords_to_point_id(end_coords[0], end_coords[1])
+                
+                if start_point_id and end_point_id:
+                    roads.append({
+                        'start_point_id': start_point_id,
+                        'end_point_id': end_point_id,
+                        'owner': road.owner,
+                        'start_coords': start_coords,  # Keep for debugging
+                        'end_coords': end_coords       # Keep for debugging
+                    })
+        return roads
+

pycatan/game_manager.py

@@ -0,0 +1,1563 @@
+"""
+GameManager - Central coordinator for PyCatan game flow
+
+This module contains the GameManager class that orchestrates the entire
+game flow, manages turns, coordinates between users and the game state.
+"""
+
+from typing import List, Optional, Dict, Any
+import uuid
+import random
+from datetime import datetime
+
+from pycatan.actions import Action, ActionResult, GameState, GamePhase, TurnPhase, ActionType
+from pycatan.user import User, UserList, validate_user_list, UserInputError
+from pycatan.game import Game
+from pycatan.statuses import Statuses
+
+
+class GameManager:
+    """
+    Central coordinator for a Catan game session.
+    
+    The GameManager orchestrates the entire game flow:
+    - Manages turn order and game phases
+    - Coordinates between Users and the Game logic
+    - Maintains the current game state
+    - Handles user input and action execution
+    - Manages game-wide events and notifications
+    """
+    
+    def __init__(self, users: UserList, game_config: Optional[Dict[str, Any]] = None, random_seed: Optional[int] = None):
+        """
+        Initialize a new GameManager.
+        
+        Args:
+            users: List of User objects for this game
+            game_config: Optional configuration for the game (board layout, rules, etc.)
+            random_seed: Optional seed for random number generator (for reproducible games)
+            
+        Raises:
+            ValueError: If users list is invalid
+        """
+        # Validate users
+        validate_user_list(users)
+        
+        # Set random seed if provided (for reproducible games)
+        if random_seed is not None:
+            random.seed(random_seed)
+        
+        # Store game metadata
+        self.game_id = str(uuid.uuid4())
+        self.created_at = datetime.now()
+        self.users = users
+        self.num_players = len(users)
+        
+        # Initialize game configuration
+        self.config = game_config or {}
+        
+        # Visualization manager (can be set later)
+        self.visualization_manager = None
+        
+        # Create the underlying game instance
+        self.game = Game(num_of_players=self.num_players)
+        
+        # Initialize game state
+        self._current_game_state = GameState(
+            game_id=self.game_id,
+            turn_number=0,
+            current_player=0,
+            game_phase=GamePhase.SETUP_FIRST_ROUND,
+            turn_phase=TurnPhase.ROLL_DICE
+        )
+        
+        # Game flow control
+        self._is_running = False
+        self._is_paused = False
+        
+        # Action history and pending operations
+        self._action_history: List[Action] = []
+        self._pending_actions: List[Action] = []
+        
+        # Error tracking per player to prevent infinite loops
+        self._player_error_count = [0] * self.num_players
+        
+        # Setup phase progress tracking
+        self._setup_turn_progress = {'settlement': False, 'road': False}
+        
+    @property
+    def is_running(self) -> bool:
+        """Whether the game is currently running."""
+        return self._is_running
+    
+    @property
+    def is_paused(self) -> bool:
+        """Whether the game is currently paused."""
+        return self._is_paused
+    
+    @property
+    def current_player_id(self) -> int:
+        """ID of the current player."""
+        return self._current_game_state.current_player
+    
+    @property
+    def current_user(self) -> User:
+        """The User object for the current player."""
+        return self.users[self.current_player_id]
+    
+    def get_full_state(self) -> GameState:
+        """
+        Get the complete current state of the game.
+        
+        This method extracts state from the Game object and combines it
+        with GameManager state like current player and turn information.
+        
+        Returns:
+            GameState: Complete current game state
+        """
+        # Get the base state from the Game object
+        game_state = self.game.get_full_state()
+        
+        # Update player names with user names
+        for i, user in enumerate(self.users):
+            if i < len(game_state.players_state):
+                game_state.players_state[i].name = getattr(user, 'name', f'Player {i + 1}')
+        
+        # Update with GameManager-specific information
+        game_state.game_id = self.game_id
+        game_state.turn_number = self._current_game_state.turn_number
+        game_state.current_player = self._current_game_state.current_player
+        game_state.game_phase = self._current_game_state.game_phase
+        game_state.turn_phase = self._current_game_state.turn_phase
+        
+        return game_state
+    
+    def get_available_actions(self) -> List[str]:
+        """
+        Get a list of available action types for the current game state.
+        
+        Returns:
+            List[str]: List of allowed ActionType names
+        """
+        actions = []
+        phase = self._current_game_state.game_phase
+        turn_phase = self._current_game_state.turn_phase
+        
+        if phase in [GamePhase.SETUP_FIRST_ROUND, GamePhase.SETUP_SECOND_ROUND]:
+            # In setup phase: settlement first, then road
+            if not self._setup_turn_progress['settlement']:
+                # Can only place settlement when none placed yet
+                actions.append(ActionType.PLACE_STARTING_SETTLEMENT.name)
+            elif not self._setup_turn_progress['road']:
+                # Can only place road after settlement is placed
+                actions.append(ActionType.PLACE_STARTING_ROAD.name)
+            else:
+                # Both built, turn should auto-end but allow manual end
+                actions.append(ActionType.END_TURN.name)
+            
+        elif phase == GamePhase.NORMAL_PLAY:
+            # Check special robber-related phases first
+            if turn_phase == TurnPhase.DISCARD_PHASE:
+                # Only discard action allowed
+                actions.append(ActionType.DISCARD_CARDS.name)
+            elif turn_phase == TurnPhase.ROBBER_MOVE:
+                # Only robber move allowed
+                actions.append(ActionType.ROBBER_MOVE.name)
+            elif turn_phase == TurnPhase.ROBBER_STEAL:
+                # Only steal action allowed
+                actions.append(ActionType.STEAL_CARD.name)
+            elif not self._current_game_state.dice_rolled:
+                # Normal pre-roll phase
+                actions.extend([
+                    ActionType.ROLL_DICE.name,
+                    ActionType.USE_DEV_CARD.name
+                ])
+            else:
+                # Normal post-roll phase - player actions
+                actions.extend([
+                    ActionType.BUILD_SETTLEMENT.name,
+                    ActionType.BUILD_CITY.name,
+                    ActionType.BUILD_ROAD.name,
+                    ActionType.TRADE_PROPOSE.name,
+                    ActionType.TRADE_BANK.name,
+                    ActionType.BUY_DEV_CARD.name,
+                    ActionType.USE_DEV_CARD.name,
+                    ActionType.END_TURN.name
+                ])
+                
+        return actions
+
+    def execute_action(self, action: Action) -> ActionResult:
+        """
+        Execute an action in the game.
+        
+        This is the main entry point for all game actions.
+        Validates the action and delegates to the appropriate handler.
+        
+        Args:
+            action: The action to execute
+            
+        Returns:
+            ActionResult: Result of the action execution
+        """
+        # Basic validation
+        if not self._is_running:
+            return ActionResult.failure_result(
+                "Game is not running",
+                "GAME_NOT_RUNNING"
+            )
+        
+        if action.player_id != self.current_player_id:
+            return ActionResult.failure_result(
+                f"Not player {action.player_id}'s turn",
+                "NOT_YOUR_TURN"
+            )
+        
+        # Log the action attempt
+        self._action_history.append(action)
+        
+        try:
+            # Route to appropriate handler based on action type
+            if action.action_type == ActionType.END_TURN:
+                return self._handle_end_turn(action)
+            elif action.action_type in [ActionType.BUILD_SETTLEMENT, ActionType.BUILD_CITY, ActionType.BUILD_ROAD,
+                                      ActionType.PLACE_STARTING_SETTLEMENT, ActionType.PLACE_STARTING_ROAD]:
+                return self._handle_building_action(action)
+            elif action.action_type == ActionType.ROLL_DICE:
+                return self._handle_roll_dice(action)
+            elif action.action_type in [ActionType.TRADE_PROPOSE, ActionType.TRADE_ACCEPT, ActionType.TRADE_REJECT]:
+                return self._handle_trade_action(action)
+            elif action.action_type == ActionType.DISCARD_CARDS:
+                return self._handle_discard_cards(action)
+            elif action.action_type == ActionType.ROBBER_MOVE:
+                return self._handle_robber_move(action)
+            elif action.action_type == ActionType.STEAL_CARD:
+                return self._handle_steal_card(action)
+            else:
+                # For now, return "not implemented" for other actions
+                return ActionResult.failure_result(
+                    f"Action {action.action_type} not yet implemented",
+                    "NOT_IMPLEMENTED"
+                )
+                
+        except Exception as e:
+            return ActionResult.failure_result(
+                f"Error executing action: {str(e)}",
+                "EXECUTION_ERROR"
+            )
+    
+    def _handle_end_turn(self, action: Action) -> ActionResult:
+        """Handle end turn action."""
+        # In the new architecture, this method just validates and returns success.
+        # The actual turn advancement happens in _advance_to_next_player()
+        # which is called by the game loop when this action returns success.
+        
+        return ActionResult.success_result(
+            self.get_full_state(),
+            affected_players=[action.player_id]
+        )
+    
+    def _handle_building_action(self, action: Action) -> ActionResult:
+        """Handle building actions (settlements, cities, roads)."""
+        try:
+            if action.action_type in [ActionType.BUILD_SETTLEMENT, ActionType.PLACE_STARTING_SETTLEMENT]:
+                return self._execute_build_settlement(action)
+            elif action.action_type == ActionType.BUILD_CITY:
+                return self._execute_build_city(action)
+            elif action.action_type in [ActionType.BUILD_ROAD, ActionType.PLACE_STARTING_ROAD]:
+                return self._execute_build_road(action)
+            else:
+                return ActionResult.failure_result(
+                    f"Unknown building action: {action.action_type}",
+                    "UNKNOWN_ACTION"
+                )
+        except Exception as e:
+            return ActionResult.failure_result(
+                f"Error executing building action: {str(e)}",
+                "BUILDING_ERROR"
+            )
+
+    def _distribute_setup_resources(self, player_id: int, point: Any) -> None:
+        """Distribute initial resources based on the second settlement."""
+        from pycatan.board import Board
+        
+        resources_given = []
+        
+        # Iterate over tiles adjacent to the point
+        # Point object has 'tiles' attribute which is a list of Tile objects
+        if hasattr(point, 'tiles'):
+            for tile in point.tiles:
+                # Get resource type from tile type
+                card_type = Board.get_card_from_tile(tile.type)
+                
+                # If it's a valid resource (not None/Desert)
+                if card_type:
+                    # Add card to player
+                    self.game.players[player_id].add_cards([card_type])
+                    resources_given.append(card_type.name)
+        
+        if resources_given:
+            # Create a dummy action for notification purposes
+            # We use PLACE_STARTING_SETTLEMENT but need to provide dummy point_coords
+            # to satisfy validation, even though they aren't used for the notification
+            dummy_action = Action(
+                ActionType.PLACE_STARTING_SETTLEMENT, 
+                player_id,
+                {'point_coords': [0, 0]}  # Dummy coordinates
+            )
+            
+            self._notify_user(
+                player_id, 
+                dummy_action, 
+                True, 
+                f"Received starting resources: {', '.join(resources_given)}"
+            )
+            
+            # Notify visualization about starting resources
+            if self.visualization_manager:
+                player_name = self.users[player_id].name if hasattr(self.users[player_id], 'name') else f"Player {player_id + 1}"
+                # Create distribution dict format
+                distribution = {player_name: resources_given}
+                self.visualization_manager.display_resource_distribution(distribution)
+
+    def _execute_build_settlement(self, action: Action) -> ActionResult:
+        """Execute settlement building action."""
+        # Extract coordinates from action parameters
+        if 'point_coords' not in action.parameters:
+            return ActionResult.failure_result(
+                "Settlement action missing point_coords parameter",
+                "MISSING_COORDS"
+            )
+        
+        coords = action.parameters['point_coords']
+        
+        # Determine if this is a starting settlement based on game phase
+        # The GameManager is the authority on rules, so we check the phase here
+        in_setup_phase = self._current_game_state.game_phase in [GamePhase.SETUP_FIRST_ROUND, GamePhase.SETUP_SECOND_ROUND]
+        
+        # If in setup phase, force is_starting to True (free building)
+        # Otherwise respect the action parameter (defaulting to False)
+        if in_setup_phase:
+            is_starting = True
+        else:
+            is_starting = action.parameters.get('is_starting', False)
+        
+        # Get the point object from board
+        try:
+            point = self.game.board.points[coords[0]][coords[1]]
+        except (IndexError, TypeError):
+            return ActionResult.failure_result(
+                f"Invalid coordinates: {coords}",
+                "INVALID_COORDS"
+            )
+        
+        # Call the actual Game method
+        status = self.game.add_settlement(action.player_id, point, is_starting)
+        
+        # Update setup progress if successful and in setup phase
+        if status == Statuses.ALL_GOOD and in_setup_phase:
+            self._setup_turn_progress['settlement'] = True
+            
+            # Only distribute resources in the second round of setup
+            if self._current_game_state.game_phase == GamePhase.SETUP_SECOND_ROUND:
+                self._distribute_setup_resources(action.player_id, point)
+        
+        # Convert Status to ActionResult
+        return self._convert_status_to_result(status, self.get_full_state(), [action.player_id])
+
+    def _execute_build_city(self, action: Action) -> ActionResult:
+        """Execute city building action."""
+        # Extract coordinates from action parameters  
+        if 'point_coords' not in action.parameters:
+            return ActionResult.failure_result(
+                "City action missing point_coords parameter", 
+                "MISSING_COORDS"
+            )
+        
+        coords = action.parameters['point_coords']
+        
+        # Get the point object from board
+        try:
+            point = self.game.board.points[coords[0]][coords[1]]
+        except (IndexError, TypeError):
+            return ActionResult.failure_result(
+                f"Invalid coordinates: {coords}",
+                "INVALID_COORDS"
+            )
+        
+        # Call the actual Game method (add_city doesn't exist, need to implement via settlement upgrade)
+        # For now, return not implemented
+        return ActionResult.failure_result(
+            "City building not yet implemented in Game class",
+            "NOT_IMPLEMENTED"
+        )
+
+    def _execute_build_road(self, action: Action) -> ActionResult:
+        """Execute road building action."""
+        # Extract coordinates from action parameters
+        if 'start_coords' not in action.parameters or 'end_coords' not in action.parameters:
+            return ActionResult.failure_result(
+                "Road action missing start_coords or end_coords parameters",
+                "MISSING_COORDS"
+            )
+        
+        start_coords = action.parameters['start_coords']
+        end_coords = action.parameters['end_coords']
+        
+        # Determine if this is a starting road based on game phase
+        # The GameManager is the authority on rules, so we check the phase here
+        in_setup_phase = self._current_game_state.game_phase in [GamePhase.SETUP_FIRST_ROUND, GamePhase.SETUP_SECOND_ROUND]
+        
+        # If in setup phase, force is_starting to True (free building)
+        # Otherwise respect the action parameter (defaulting to False)
+        if in_setup_phase:
+            is_starting = True
+        else:
+            is_starting = action.parameters.get('is_starting', False)
+        
+        # Get point objects from board
+        try:
+            start_point = self.game.board.points[start_coords[0]][start_coords[1]]
+            end_point = self.game.board.points[end_coords[0]][end_coords[1]]
+        except (IndexError, TypeError):
+            return ActionResult.failure_result(
+                f"Invalid coordinates: start={start_coords}, end={end_coords}",
+                "INVALID_COORDS"
+            )
+        
+        # Call the actual Game method
+        status = self.game.add_road(action.player_id, start_point, end_point, is_starting)
+        
+        # Update setup progress if successful and in setup phase
+        if status == Statuses.ALL_GOOD and in_setup_phase:
+            self._setup_turn_progress['road'] = True
+        
+        # Convert Status to ActionResult
+        return self._convert_status_to_result(status, self.get_full_state(), [action.player_id])
+
+    def _convert_status_to_result(self, status, game_state, affected_players):
+        """Convert Game.Statuses to ActionResult."""
+        from pycatan.statuses import Statuses
+        
+        if status == Statuses.ALL_GOOD:
+            return ActionResult.success_result(game_state, affected_players)
+        elif status == Statuses.ERR_CARDS:
+            return ActionResult.failure_result("Not enough cards", "INSUFFICIENT_RESOURCES")
+        elif status == Statuses.ERR_BLOCKED:
+            return ActionResult.failure_result("Location is blocked", "LOCATION_BLOCKED")
+        elif status == Statuses.ERR_INPUT:
+            return ActionResult.failure_result("Invalid input", "INVALID_INPUT")
+        elif status == Statuses.ERR_NOT_CON:
+            return ActionResult.failure_result("Road points are not connected", "NOT_CONNECTED")
+        elif status == Statuses.ERR_ISOLATED:
+            return ActionResult.failure_result("Not connected to existing buildings", "ISOLATED")
+        else:
+            return ActionResult.failure_result(f"Unknown status: {status}", "UNKNOWN_ERROR")
+    
+    def _handle_trade_action(self, action: Action) -> ActionResult:
+        """Handle trade-related actions."""
+        if action.action_type == ActionType.TRADE_PROPOSE:
+            return self._execute_trade_propose(action)
+        elif action.action_type == ActionType.TRADE_BANK:
+            return self._execute_trade_bank(action)
+        else:
+            # TRADE_ACCEPT and TRADE_REJECT should not be called directly
+            # They are handled internally by _execute_trade_propose
+            return ActionResult.failure_result(
+                f"Trade action {action.action_type} cannot be called directly",
+                "INVALID_ACTION"
+            )
+    
+    def _execute_trade_propose(self, action: Action) -> ActionResult:
+        """
+        Execute a trade proposal between players.
+        
+        This function:
+        1. Validates that both players have the required cards
+        2. Requests input from the target player (accept/reject)
+        3. Executes the trade if accepted
+        """
+        try:
+            proposer_id = action.player_id
+            target_id = action.parameters['target_player']
+            offer = action.parameters['offer']  # {resource: amount}
+            request = action.parameters['request']  # {resource: amount}
+            
+            # Get player names for messages
+            proposer_name = self.users[proposer_id].name
+            target_name = self.users[target_id].name
+            
+            # Convert offer/request dicts to card lists for Game.trade()
+            from pycatan.card import ResCard
+            
+            offer_cards = []
+            for resource, amount in offer.items():
+                card_type = self._resource_name_to_card(resource)
+                offer_cards.extend([card_type] * amount)
+            
+            request_cards = []
+            for resource, amount in request.items():
+                card_type = self._resource_name_to_card(resource)
+                request_cards.extend([card_type] * amount)
+            
+            # Validate that both players have the required cards
+            if not self.game.players[proposer_id].has_cards(offer_cards):
+                print(f"    ✗ You don't have the required cards to offer")
+                return ActionResult.failure_result(
+                    f"You don't have the required cards to offer",
+                    "INSUFFICIENT_RESOURCES"
+                )
+            
+            if not self.game.players[target_id].has_cards(request_cards):
+                print(f"    ✗ {target_name} doesn't have the required cards")
+                return ActionResult.failure_result(
+                    f"{target_name} doesn't have the required cards",
+                    "INSUFFICIENT_RESOURCES"
+                )
+            
+            # Format the trade offer message
+            offer_str = ", ".join([f"{amt} {res}" for res, amt in offer.items()])
+            request_str = ", ".join([f"{amt} {res}" for res, amt in request.items()])
+            
+            # Ask the target player to accept or reject
+            print(f"\n📢 Trade Proposal:")
+            print(f"    {proposer_name} offers: {offer_str}")
+            print(f"    {proposer_name} wants: {request_str}")
+            print(f"    {target_name}, do you accept? (yes/no)")
+            
+            # Get response from target player
+            target_user = self.users[target_id]
+            response = target_user.get_input(
+                self.get_full_state(),
+                f"{target_name}, accept trade?",
+                allowed_actions=[ActionType.TRADE_ACCEPT.name, ActionType.TRADE_REJECT.name]
+            )
+            
+            # Handle response
+            if response.action_type == ActionType.TRADE_ACCEPT:
+                # Execute the trade
+                status = self.game.trade(proposer_id, target_id, offer_cards, request_cards)
+                
+                if status == Statuses.ALL_GOOD:
+                    print(f"    ✓ Trade completed between {proposer_name} and {target_name}!")
+                    return ActionResult.success_result(
+                        self.get_full_state(),
+                        affected_players=[proposer_id, target_id]
+                    )
+                else:
+                    return self._map_status_to_result(status)
+            else:
+                # Trade rejected
+                print(f"    ✗ {target_name} rejected the trade")
+                return ActionResult.failure_result(
+                    f"{target_name} rejected your trade offer",
+                    "TRADE_REJECTED"
+                )
+                
+        except Exception as e:
+            return ActionResult.failure_result(
+                f"Error executing trade: {str(e)}",
+                "EXECUTION_ERROR"
+            )
+    
+    def _execute_trade_bank(self, action: Action) -> ActionResult:
+        """Execute a trade with the bank."""
+        try:
+            player_id = action.player_id
+            offer = action.parameters['offer']  # {resource: amount}
+            request = action.parameters['request']  # {resource: amount}
+            
+            # Convert to card lists
+            from pycatan.card import ResCard
+            
+            offer_cards = []
+            for resource, amount in offer.items():
+                card_type = self._resource_name_to_card(resource)
+                offer_cards.extend([card_type] * amount)
+            
+            request_cards = []
+            for resource, amount in request.items():
+                card_type = self._resource_name_to_card(resource)
+                request_cards.extend([card_type] * amount)
+            
+            # Execute bank trade
+            status = self.game.trade_to_bank(player_id, offer_cards, request_cards)
+            
+            if status == Statuses.ALL_GOOD:
+                offer_str = ", ".join([f"{amt} {res}" for res, amt in offer.items()])
+                request_str = ", ".join([f"{amt} {res}" for res, amt in request.items()])
+                print(f"    ✓ Bank trade: gave {offer_str}, received {request_str}")
+                return ActionResult.success_result(
+                    self.get_full_state(),
+                    affected_players=[player_id]
+                )
+            else:
+                return self._map_status_to_result(status)
+                
+        except Exception as e:
+            return ActionResult.failure_result(
+                f"Error executing bank trade: {str(e)}",
+                "EXECUTION_ERROR"
+            )
+    
+    def _resource_name_to_card(self, resource_name: str):
+        """Convert resource name string to ResCard enum."""
+        from pycatan.card import ResCard
+        
+        resource_map = {
+            'wood': ResCard.Wood,
+            'brick': ResCard.Brick,
+            'sheep': ResCard.Sheep,
+            'wheat': ResCard.Wheat,
+            'ore': ResCard.Ore
+        }
+        
+        return resource_map.get(resource_name.lower())
+    
+    def start_game(self) -> bool:
+        """
+        Start the game session.
+        
+        Initializes the game state and begins the main game loop.
+        
+        Returns:
+            bool: True if game started successfully
+        """
+        if self._is_running:
+            return False  # Already running
+        
+        # Initialize game state
+        self._is_running = True
+        self._is_paused = False
+        
+        # Notify all users
+        self._notify_all_users(
+            "game_start",
+            f"Game {self.game_id} has started with {self.num_players} players!"
+        )
+        
+        # Display Turn 0 immediately when game starts
+        self._display_current_turn_start()
+        
+        return True
+    
+    def pause_game(self) -> bool:
+        """Pause the game."""
+        if not self._is_running or self._is_paused:
+            return False
+        
+        self._is_paused = True
+        self._notify_all_users("game_pause", "Game has been paused.")
+        return True
+    
+    def resume_game(self) -> bool:
+        """Resume a paused game."""
+        if not self._is_running or not self._is_paused:
+            return False
+        
+        self._is_paused = False
+        self._notify_all_users("game_resume", "Game has been resumed.")
+        return True
+    
+    def end_game(self) -> bool:
+        """End the game session."""
+        if not self._is_running:
+            return False
+        
+        self._is_running = False
+        self._is_paused = False
+        
+        # TODO: Calculate final scores, determine winner
+        self._notify_all_users("game_end", "Game has ended.")
+        return True
+    
+    def request_user_input(self, user_id: int, prompt: str, 
+                          allowed_actions: Optional[List[str]] = None) -> Action:
+        """
+        Request input from a specific user.
+        
+        Args:
+            user_id: ID of the user to request input from
+            prompt: Message explaining what input is needed
+            allowed_actions: Optional list of allowed action types
+            
+        Returns:
+            Action: The action chosen by the user
+            
+        Raises:
+            UserInputError: If user input fails
+        """
+        if user_id >= len(self.users):
+            raise UserInputError(f"Invalid user ID: {user_id}")
+        
+        user = self.users[user_id]
+        
+        if not user.is_active:
+            raise UserInputError(f"User {user_id} is not active")
+        
+        try:
+            return user.get_input(
+                self.get_full_state(),
+                prompt,
+                allowed_actions
+            )
+        except Exception as e:
+            raise UserInputError(f"Failed to get input from user {user_id}: {e}", user)
+    
+    def _notify_all_users(self, event_type: str, message: str, 
+                         affected_players: Optional[List[int]] = None) -> None:
+        """Notify all users about a game event."""
+        for user in self.users:
+            if user.is_active:
+                user.notify_game_event(event_type, message, affected_players)
+    
+    def _notify_user(self, user_id: int, action: Action, success: bool, message: str = "") -> None:
+        """Notify a specific user about an action result."""
+        if user_id < len(self.users) and self.users[user_id].is_active:
+            self.users[user_id].notify_action(action, success, message)
+    
+    def get_action_history(self) -> List[Action]:
+        """Get the complete action history for this game."""
+        return self._action_history.copy()
+    
+    def get_user_by_id(self, user_id: int) -> Optional[User]:
+        """Get a user by their ID."""
+        if 0 <= user_id < len(self.users):
+            return self.users[user_id]
+        return None
+    
+    def game_loop(self) -> None:
+        """
+        Main game loop that runs the entire game from start to finish.
+        
+        This is the central function that orchestrates the entire game flow.
+        It manages turn order, requests input from users, executes actions,
+        and updates all systems until the game ends.
+        
+        Flow:
+        1. Check if game is running and not paused
+        2. Get input from current player
+        3. Attempt to execute the action
+        4. Update all systems (visualizations, users)
+        5. Check win conditions
+        6. Move to next turn if needed
+        
+        The function runs until the game ends or is explicitly stopped.
+        """
+        # Continue running until game ends or is explicitly stopped
+        while self._is_running and not self._check_game_end_conditions():
+            
+            # If game is paused, wait
+            if self._is_paused:
+                # In paused state, just continue loop without doing anything
+                continue
+            
+            # Run a single turn for the current player
+            try:
+                turn_ended = self._handle_single_turn()
+                
+                # Reset error count on successful turn processing
+                self._player_error_count[self.current_player_id] = 0
+                
+                # Only advance to next player if turn actually ended
+                if turn_ended:
+                    self._advance_to_next_player()
+                    
+            except Exception as e:
+                # Increment error count for current player
+                self._player_error_count[self.current_player_id] += 1
+                
+                # If error occurred, notify current player
+                self._notify_all_users(
+                    "error", 
+                    f"Error during player {self.current_player_id}'s turn: {str(e)}."
+                )
+                
+                # If too many consecutive errors for this player, skip their turn
+                if self._player_error_count[self.current_player_id] >= 3:
+                    self._notify_all_users(
+                        "player_skip",
+                        f"Player {self.current_player_id} had too many errors. Skipping turn."
+                    )
+                    self._advance_to_next_player()
+                else:
+                    self._notify_all_users(
+                        "retry",
+                        f"Player {self.current_player_id} can try again."
+                    )
+        
+        # Game has ended - handle cleanup
+        self._handle_game_end()
+    
+    def _handle_single_turn(self) -> bool:
+        """
+        Handles a single turn of one player.
+        
+        This function manages one complete turn of a single player:
+        1. Requests an action from the current user
+        2. Attempts to execute the action
+        3. Updates all systems about the result
+        4. Determines if the turn should end or continue
+        
+        Special handling for discard phase when 7 is rolled:
+        - During discard phase, each player who needs to discard gets prompted in turn
+        
+        Returns:
+            bool: True if the turn ended, False if player wants to continue
+        """
+        # Special handling for discard phase - ask each player who needs to discard
+        if self._current_game_state.turn_phase == TurnPhase.DISCARD_PHASE:
+            return self._handle_discard_phase_turn()
+        
+        # Get the current player's action
+        action_result = self._process_user_action()
+        
+        # Update all systems about what happened
+        if hasattr(action_result, 'action'):
+            self._update_all_systems(action_result.action, action_result)
+        
+        # Determine if turn should end
+        if action_result.success and hasattr(action_result, 'action'):
+            action = action_result.action
+            
+            # END_TURN action explicitly ends the turn
+            if action.action_type == ActionType.END_TURN:
+                return True
+            
+            # Auto-end turn in setup phase if both actions are done
+            phase = self._current_game_state.game_phase
+            if phase in [GamePhase.SETUP_FIRST_ROUND, GamePhase.SETUP_SECOND_ROUND]:
+                if self._setup_turn_progress['settlement'] and self._setup_turn_progress['road']:
+                    return True
+            
+            # For other successful actions, player can continue
+            return False
+        else:
+            # If action failed, player can try again (don't end turn)
+            return False
+    
+    def _handle_discard_phase_turn(self) -> bool:
+        """
+        Handle the discard phase when 7 is rolled.
+        
+        Each player who needs to discard is prompted in turn order.
+        After all players have discarded, the phase moves to robber move.
+        
+        Returns:
+            bool: Always False (don't advance to next player during discard)
+        """
+        # Find the next player who needs to discard
+        players_needing_discard = self._current_game_state.players_must_discard
+        
+        if not players_needing_discard:
+            # All done discarding - this shouldn't happen but handle it
+            self._current_game_state.turn_phase = TurnPhase.ROBBER_MOVE
+            return False
+        
+        # Get the first player who still needs to discard
+        discard_player_id = min(players_needing_discard.keys())
+        discard_count = players_needing_discard[discard_player_id]
+        
+        # Get the user for this player
+        discard_user = self.users[discard_player_id]
+        player_name = discard_user.name if hasattr(discard_user, 'name') else f"Player {discard_player_id}"
+        
+        # Request discard action from this player
+        allowed_actions = [ActionType.DISCARD_CARDS.name]
+        
+        try:
+            action = discard_user.get_input(
+                self.get_full_state(),
+                f"{player_name}, you must discard {discard_count} cards. Use: drop [amount] [resource] ...",
+                allowed_actions
+            )
+            
+            # Override the player_id to match the discarding player (not current turn player)
+            action.player_id = discard_player_id
+            
+            # Execute the discard action
+            result = self._handle_discard_cards(action)
+            
+            # Update systems
+            self._update_all_systems(action, result)
+            
+        except Exception as e:
+            self._notify_all_users(
+                "error",
+                f"Error during {player_name}'s discard: {str(e)}"
+            )
+        
+        # Don't end the turn - continue with discard phase or move to robber
+        return False
+    
+    def _process_user_action(self) -> ActionResult:
+        """
+        Requests an action from the current user and attempts to execute it.
+        
+        This function:
+        1. Identifies the current player
+        2. Requests them to choose an action via get_input()
+        3. Validates the action
+        4. Attempts to execute the action via execute_action()
+        5. Returns the result
+        
+        Returns:
+            ActionResult: The result of executing the action
+        """
+        try:
+            # Get the current user
+            current_user = self.current_user
+            
+            # Get allowed actions for current state
+            allowed_actions = self.get_available_actions()
+            
+            # Request action from the current user
+            action = current_user.get_input(
+                self.get_full_state(),
+                f"Player {self.current_player_id}, choose your action:",
+                allowed_actions
+            )
+            
+            # Validate that the action is for the current player
+            if action.player_id != self.current_player_id:
+                return ActionResult.failure_result(
+                    f"Action player_id {action.player_id} doesn't match current player {self.current_player_id}",
+                    "INVALID_PLAYER_ID"
+                )
+            
+            # Execute the action
+            result = self.execute_action(action)
+            
+            # Add the action to the result for reference
+            if hasattr(result, 'action'):
+                result.action = action
+            else:
+                # If ActionResult doesn't have action field, add it dynamically
+                setattr(result, 'action', action)
+            
+            return result
+            
+        except Exception as e:
+            # Handle any errors during action processing
+            return ActionResult.failure_result(
+                f"Error processing user action: {str(e)}",
+                "ACTION_PROCESSING_ERROR"
+            )
+    
+    def _update_all_systems(self, action: Action, result: ActionResult) -> None:
+        """
+        Updates all systems after an action has been executed.
+        
+        This function ensures that all parts of the system are informed
+        about what happened and can update their displays accordingly.
+        
+        Updates:
+        1. Notifies all users about the action and its result
+        2. Updates visualizations with new game state
+        3. Logs the action for history/debugging
+        4. Handles any side effects of the action
+        
+        Args:
+            action: The action that was executed
+            result: The result of the action execution
+        """
+        # Notify the specific user who performed the action
+        self._notify_user(
+            action.player_id, 
+            action, 
+            result.success, 
+            result.error_message or ""
+        )
+        
+        # If action was successful, notify all users about the action
+        if result.success:
+            action_description = self._get_action_description(action)
+            self._notify_all_users(
+                "action_performed",
+                f"Player {action.player_id} {action_description}",
+                result.affected_players if hasattr(result, 'affected_players') else [action.player_id]
+            )
+        
+        # Update visualizations if available
+        if self.visualization_manager:
+            try:
+                # Add player name to action parameters for better visualization
+                if not hasattr(action, 'parameters') or action.parameters is None:
+                    action.parameters = {}
+                
+                # Add player name if not already present
+                if 'player_name' not in action.parameters:
+                    player_name = self.users[action.player_id].name if hasattr(self.users[action.player_id], 'name') else f"Player {action.player_id}"
+                    action.parameters['player_name'] = player_name
+                
+                # Display the action result (success or failure)
+                self.visualization_manager.display_action(action, result)
+                
+                current_state = self.get_full_state()
+                # Pass GameState object directly so visualizations can extract what they need
+                self.visualization_manager.display_game_state(current_state)
+            except Exception as e:
+                # Log visualization errors
+                print(f"Error updating visualizations: {e}")
+        
+        # Log the action and result for debugging
+        if self.config.get('debug', False):
+            # Only print if debug config is explicitly enabled
+            pass
+
+    def _gamestate_to_dict(self, game_state) -> Dict[str, Any]:
+        """Convert GameState object to dict format expected by visualizations."""
+        try:
+            return {
+                'game_id': game_state.game_id,
+                'turn_number': game_state.turn_number,
+                'current_player': game_state.current_player,
+                'current_player_name': self.users[game_state.current_player].name if hasattr(self.users[game_state.current_player], 'name') else f"Player {game_state.current_player}",
+                'game_phase': game_state.game_phase.name if hasattr(game_state.game_phase, 'name') else str(game_state.game_phase),
+                'turn_phase': game_state.turn_phase.name if hasattr(game_state.turn_phase, 'name') else str(game_state.turn_phase),
+                'players': [
+                    {
+                        'id': i,
+                        'name': self.users[i].name if hasattr(self.users[i], 'name') else f"Player {i}",
+                        'victory_points': player.victory_points,
+                        'cards': len(player.cards),
+                        'settlements': len(player.settlements),
+                        'cities': len(player.cities),
+                        'roads': len(player.roads),
+                        'longest_road_length': player.longest_road_length,
+                        'has_longest_road': player.has_longest_road,
+                        'has_largest_army': player.has_largest_army,
+                        'knights_played': player.knights_played
+                    }
+                    for i, player in enumerate(game_state.players_state)
+                ],
+                'board': {
+                    'tiles_count': len(game_state.board_state.tiles),
+                    'robber_position': game_state.board_state.robber_position,
+                    'buildings_count': len(game_state.board_state.buildings),
+                    'roads_count': len(game_state.board_state.roads)
+                }
+            }
+        except Exception as e:
+            # Fallback dict if conversion fails
+            return {
+                'turn_number': getattr(game_state, 'turn_number', 0),
+                'current_player': getattr(game_state, 'current_player', 0),
+                'current_player_name': f"Player {getattr(game_state, 'current_player', 0)}",
+                'game_phase': 'UNKNOWN',
+                'players': [],
+                'board': {}
+            }
+    
+    def _get_action_description(self, action: Action) -> str:
+        """
+        Get a human-readable description of an action.
+        
+        Args:
+            action: The action to describe
+            
+        Returns:
+            str: Human-readable description
+        """
+        if action.action_type == ActionType.BUILD_SETTLEMENT:
+            return "built a settlement"
+        elif action.action_type == ActionType.BUILD_CITY:
+            return "built a city"
+        elif action.action_type == ActionType.BUILD_ROAD:
+            return "built a road"
+        elif action.action_type == ActionType.END_TURN:
+            return "ended their turn"
+        elif action.action_type == ActionType.TRADE_PROPOSE:
+            return "proposed a trade"
+        else:
+            return f"performed action: {action.action_type}"
+    
+    def _advance_to_next_player(self) -> None:
+        """
+        Advances the game to the next player's turn.
+        
+        This function handles the transition between players,
+        updating turn counters and notifying all users.
+        It implements the "Snake Draft" order for setup phase:
+        Round 1: 0 -> 1 -> ... -> N-1
+        Round 2: N-1 -> N-2 -> ... -> 0
+        """
+        # Reset setup progress for the new turn
+        self._setup_turn_progress = {'settlement': False, 'road': False}
+        
+        # Reset dice_rolled for the new turn (important for normal play!)
+        self._current_game_state.dice_rolled = None
+
+        # Increment turn number
+        self._current_game_state.turn_number += 1
+        turn = self._current_game_state.turn_number
+        
+        # Handle Setup Phase Logic
+        if self._current_game_state.game_phase == GamePhase.SETUP_FIRST_ROUND:
+            if turn < self.num_players:
+                # Still in first round, standard order
+                self._current_game_state.current_player = turn
+            else:
+                # Switch to second round
+                self._current_game_state.game_phase = GamePhase.SETUP_SECOND_ROUND
+                # The first player of second round is the last player of first round
+                self._current_game_state.current_player = self.num_players - 1
+                self._notify_all_users("phase_change", "First round of setup complete! Starting second round (reverse order).")
+                
+        elif self._current_game_state.game_phase == GamePhase.SETUP_SECOND_ROUND:
+            # Check if setup is done
+            if turn >= self.num_players * 2:
+                self._current_game_state.game_phase = GamePhase.NORMAL_PLAY
+                self._current_game_state.current_player = 0
+                self._notify_all_users("phase_change", "Setup complete! Entering Normal Play phase.")
+            else:
+                # Calculate reverse order for snake draft
+                # Formula: (2 * num_players - 1) - turn
+                self._current_game_state.current_player = (2 * self.num_players - 1) - turn
+        
+        else: # Normal Play
+             self._current_game_state.current_player = (self._current_game_state.current_player + 1) % self.num_players
+        
+        # Display turn start
+        self._display_current_turn_start()
+    
+    def _display_current_turn_start(self) -> None:
+        """Display turn start notification for the current player and turn."""
+        # Notify all users about the turn change
+        self._notify_all_users(
+            "turn_change", 
+            f"Turn {self._current_game_state.turn_number}: Player {self._current_game_state.current_player}'s turn begins."
+        )
+        
+        # Notify visualization
+        if self.visualization_manager:
+            player_id = self._current_game_state.current_player
+            player_name = self.users[player_id].name if hasattr(self.users[player_id], 'name') else f"Player {player_id + 1}"
+            self.visualization_manager.display_turn_start(player_name, self._current_game_state.turn_number)
+    
+    def _handle_game_end(self) -> None:
+        """
+        Handles the end of the game.
+        
+        This function is called when the game loop exits,
+        either due to win conditions or explicit termination.
+        """
+        # Set game as not running
+        self._is_running = False
+        self._is_paused = False
+        
+        # TODO: Calculate final scores and determine winner
+        # For now, just notify that game ended
+        self._notify_all_users("game_end", "Game has ended.")
+        
+        # TODO: Cleanup resources, save game state, etc.
+    
+    def _check_game_end_conditions(self) -> bool:
+        """
+        Checks if the game has ended based on win conditions.
+        
+        This function examines the current game state to determine
+        if any player has achieved victory conditions.
+        
+        Standard Catan win conditions:
+        1. First player to reach 10 victory points wins
+        2. Victory points come from: settlements (1), cities (2), 
+           development cards (1 each), longest road (2), largest army (2)
+        
+        Returns:
+            bool: True if game has ended (someone won), False if game continues
+        """
+        # Check victory points for each player
+        for player_id in range(self.num_players):
+            player = self.game.players[player_id]
+            
+            # Calculate total victory points for this player
+            # We include dev cards because we want to know if they actually won
+            victory_points = player.get_VP(include_dev=True)
+            
+            # Check if this player has won (10+ victory points)
+            if victory_points >= 10:
+                self._announce_winner(player_id, victory_points)
+                return True
+        
+        # No player has won yet
+        return False
+    
+    def _announce_winner(self, player_id: int, victory_points: int) -> None:
+        """
+        Announces the winner of the game.
+        
+        Args:
+            player_id: ID of the winning player
+            victory_points: Number of victory points the winner achieved
+        """
+        winner_name = self.users[player_id].name if hasattr(self.users[player_id], 'name') else f"Player {player_id}"
+        
+        self._notify_all_users(
+            "game_winner",
+            f"🎉 {winner_name} has won the game with {victory_points} victory points! 🎉"
+        )
+        
+        # Log the victory for debugging/statistics
+        print(f"[GAME END] Player {player_id} ({winner_name}) won with {victory_points} victory points")
+    
+    def _handle_roll_dice(self, action: Action) -> ActionResult:
+        """Handle dice rolling."""
+        # Check game phase
+        if self._current_game_state.game_phase != GamePhase.NORMAL_PLAY:
+             return ActionResult.failure_result(
+                 f"Cannot roll dice in {self._current_game_state.game_phase.name} phase.\n"
+                 "💡 Hint: In setup phase, use 'settlement <point> starting' and 'road <p1> <p2> starting'.", 
+                 "INVALID_PHASE"
+             )
+
+        # Check if dice already rolled this turn
+        if self._current_game_state.dice_rolled:
+             return ActionResult.failure_result("Dice already rolled this turn", "ALREADY_ROLLED")
+             
+        # Roll dice
+        die1 = random.randint(1, 6)
+        die2 = random.randint(1, 6)
+        total = die1 + die2
+        
+        # Update state
+        self._current_game_state.dice_rolled = (die1, die2)
+        
+        # Notify visualization about dice roll
+        if self.visualization_manager:
+            player_name = self.users[action.player_id].name if hasattr(self.users[action.player_id], 'name') else f"Player {action.player_id + 1}"
+            self.visualization_manager.display_dice_roll(player_name, [die1, die2], total)
+        
+        # Distribute resources or handle robber
+        if total != 7:
+            distribution = self.game.add_yield_for_roll(total)
+            
+            # Notify visualization about resources (even if empty)
+            if self.visualization_manager:
+                if distribution:
+                    self.visualization_manager.display_resource_distribution(distribution)
+                    message = f"Rolled {total} ({die1}+{die2}). Resources distributed."
+                else:
+                    # No resources were distributed (no settlements on this number)
+                    message = f"Rolled {total} ({die1}+{die2}). No settlements on this number - no resources distributed."
+            else:
+                message = f"Rolled {total} ({die1}+{die2}). Resources distributed."
+        else:
+            # Rolled 7! Handle robber sequence
+            message = f"Rolled 7 ({die1}+{die2})! 🏴‍☠️ Robber activated!"
+            self._handle_rolled_seven()
+            
+        # Notify
+        self._notify_all_users("dice_roll", message)
+        
+        return ActionResult.success_result(
+            self.get_full_state()
+        )
+    
+    def _handle_rolled_seven(self) -> None:
+        """
+        Handle the effects of rolling a 7:
+        1. Check which players have more than 7 cards and need to discard
+        2. Set up the discard phase if needed
+        3. Prepare for robber movement
+        """
+        # Check which players need to discard (more than 7 cards)
+        players_must_discard = {}
+        
+        for player_id, player in enumerate(self.game.players):
+            card_count = len(player.cards)
+            if card_count > 7:
+                # Must discard half, rounded down
+                discard_count = card_count // 2
+                players_must_discard[player_id] = discard_count
+                
+                player_name = self.users[player_id].name if hasattr(self.users[player_id], 'name') else f"Player {player_id}"
+                self._notify_all_users(
+                    "discard_required",
+                    f"⚠️ {player_name} has {card_count} cards and must discard {discard_count}."
+                )
+        
+        # Store the discard requirements in game state
+        self._current_game_state.players_must_discard = players_must_discard
+        self._current_game_state.robber_moved = False
+        self._current_game_state.steal_pending = False
+        
+        # Set the appropriate turn phase
+        if players_must_discard:
+            self._current_game_state.turn_phase = TurnPhase.DISCARD_PHASE
+        else:
+            # No one needs to discard, go straight to robber move
+            self._current_game_state.turn_phase = TurnPhase.ROBBER_MOVE
+            self._notify_all_users(
+                "robber",
+                f"🏴‍☠️ {self.users[self.current_player_id].name} must move the robber!"
+            )
+    
+    def _handle_discard_cards(self, action: Action) -> ActionResult:
+        """
+        Handle a player discarding cards (when 7 is rolled).
+        
+        The action must contain:
+        - cards: List of card names to discard
+        """
+        player_id = action.player_id
+        cards_to_discard = action.parameters.get('cards', [])
+        
+        # Check if this player needs to discard
+        required_discard = self._current_game_state.players_must_discard.get(player_id, 0)
+        
+        if required_discard == 0:
+            return ActionResult.failure_result(
+                "You don't need to discard any cards.",
+                "NO_DISCARD_REQUIRED"
+            )
+        
+        # Check if they're discarding the right amount
+        if len(cards_to_discard) != required_discard:
+            return ActionResult.failure_result(
+                f"You must discard exactly {required_discard} cards, but you're trying to discard {len(cards_to_discard)}.",
+                "WRONG_DISCARD_COUNT"
+            )
+        
+        # Convert card names to ResCard enum and verify player has them
+        from pycatan.card import ResCard
+        
+        player = self.game.players[player_id]
+        cards_enum = []
+        
+        for card_name in cards_to_discard:
+            try:
+                card = ResCard[card_name]
+                cards_enum.append(card)
+            except KeyError:
+                return ActionResult.failure_result(
+                    f"Unknown card type: {card_name}",
+                    "INVALID_CARD"
+                )
+        
+        # Check if player has all these cards
+        if not player.has_cards(cards_enum):
+            return ActionResult.failure_result(
+                "You don't have all the cards you're trying to discard.",
+                "MISSING_CARDS"
+            )
+        
+        # Remove the cards from player
+        player.remove_cards(cards_enum)
+        
+        # Update discard tracking
+        del self._current_game_state.players_must_discard[player_id]
+        
+        player_name = self.users[player_id].name if hasattr(self.users[player_id], 'name') else f"Player {player_id}"
+        self._notify_all_users(
+            "discard_complete",
+            f"✓ {player_name} discarded {len(cards_to_discard)} cards."
+        )
+        
+        # Check if all players have finished discarding
+        if not self._current_game_state.players_must_discard:
+            # All discards complete, move to robber phase
+            self._current_game_state.turn_phase = TurnPhase.ROBBER_MOVE
+            current_player_name = self.users[self.current_player_id].name if hasattr(self.users[self.current_player_id], 'name') else f"Player {self.current_player_id}"
+            self._notify_all_users(
+                "robber",
+                f"🏴‍☠️ {current_player_name} must now move the robber!"
+            )
+        
+        return ActionResult.success_result(self.get_full_state())
+    
+    def _handle_robber_move(self, action: Action) -> ActionResult:
+        """
+        Handle moving the robber to a new tile.
+        
+        The action must contain:
+        - tile_coords: [row, index] of the new robber position
+        """
+        tile_coords = action.parameters.get('tile_coords')
+        
+        if not tile_coords:
+            return ActionResult.failure_result(
+                "Robber move requires tile coordinates.",
+                "MISSING_COORDS"
+            )
+        
+        row, index = tile_coords
+        
+        # Validate the tile exists
+        try:
+            tile = self.game.board.tiles[row][index]
+        except (IndexError, KeyError):
+            return ActionResult.failure_result(
+                f"Invalid tile coordinates: [{row}, {index}]",
+                "INVALID_COORDS"
+            )
+        
+        # Can't place robber on desert (already there) - check if it's the same position
+        current_robber_pos = getattr(self.game.board, 'robber_tile', None)
+        if current_robber_pos and current_robber_pos == (row, index):
+            return ActionResult.failure_result(
+                "You must move the robber to a different tile.",
+                "SAME_POSITION"
+            )
+        
+        # Move the robber
+        # First, remove robber from current position
+        if current_robber_pos:
+            old_row, old_index = current_robber_pos
+            try:
+                self.game.board.tiles[old_row][old_index].has_robber = False
+            except (IndexError, AttributeError):
+                pass
+        
+        # Place robber on new position
+        tile.has_robber = True
+        self.game.board.robber_tile = (row, index)
+        
+        self._current_game_state.robber_moved = True
+        
+        # Find players adjacent to this tile who can be stolen from
+        stealable_players = self._get_stealable_players(row, index)
+        
+        player_name = self.users[action.player_id].name if hasattr(self.users[action.player_id], 'name') else f"Player {action.player_id}"
+        self._notify_all_users(
+            "robber_moved",
+            f"��‍☠️ {player_name} moved the robber to [{row}, {index}]."
+        )
+        
+        if stealable_players:
+            # There are players to steal from
+            self._current_game_state.turn_phase = TurnPhase.ROBBER_STEAL
+            self._current_game_state.steal_pending = True
+            
+            stealable_names = [self.users[pid].name for pid in stealable_players]
+            self._notify_all_users(
+                "steal_available",
+                f"🎯 {player_name} can steal from: {', '.join(stealable_names)}"
+            )
+        else:
+            # No one to steal from, proceed to normal play
+            self._current_game_state.turn_phase = TurnPhase.PLAYER_ACTIONS
+            self._notify_all_users(
+                "robber_complete",
+                "No players with cards adjacent to robber. Proceeding with turn."
+            )
+        
+        return ActionResult.success_result(self.get_full_state())
+    
+    def _get_stealable_players(self, tile_row: int, tile_index: int) -> List[int]:
+        """
+        Get list of player IDs who have settlements/cities adjacent to the given tile
+        and have at least 1 card (excluding the current player).
+        """
+        stealable = []
+        current_player = self.current_player_id
+        
+        try:
+            tile = self.game.board.tiles[tile_row][tile_index]
+        except (IndexError, KeyError):
+            return []
+        
+        # Get all points adjacent to this tile
+        adjacent_points = tile.points if hasattr(tile, 'points') else []
+        
+        for point in adjacent_points:
+            if point.building is not None:
+                owner_id = point.building.owner
+                # Don't include current player, and don't include players with no cards
+                if owner_id != current_player and owner_id not in stealable:
+                    if len(self.game.players[owner_id].cards) > 0:
+                        stealable.append(owner_id)
+        
+        return stealable
+    
+    def _handle_steal_card(self, action: Action) -> ActionResult:
+        """
+        Handle stealing a card from a player adjacent to the robber.
+        
+        The action must contain:
+        - target_player: Player ID to steal from (or None if no one to steal from)
+        """
+        target_player = action.parameters.get('target_player')
+        
+        if target_player is None:
+            # No one to steal from
+            self._current_game_state.turn_phase = TurnPhase.PLAYER_ACTIONS
+            self._current_game_state.steal_pending = False
+            return ActionResult.success_result(self.get_full_state())
+        
+        # Validate target player
+        if target_player < 0 or target_player >= self.num_players:
+            return ActionResult.failure_result(
+                f"Invalid player ID: {target_player}",
+                "INVALID_PLAYER"
+            )
+        
+        if target_player == action.player_id:
+            return ActionResult.failure_result(
+                "You cannot steal from yourself!",
+                "STEAL_SELF"
+            )
+        
+        # Check target has cards
+        target = self.game.players[target_player]
+        if len(target.cards) == 0:
+            return ActionResult.failure_result(
+                f"Player {target_player} has no cards to steal.",
+                "NO_CARDS"
+            )
+        
+        # Check target is adjacent to robber
+        robber_pos = getattr(self.game.board, 'robber_tile', None)
+        if robber_pos:
+            stealable = self._get_stealable_players(robber_pos[0], robber_pos[1])
+            if target_player not in stealable:
+                return ActionResult.failure_result(
+                    f"Player {target_player} is not adjacent to the robber.",
+                    "NOT_ADJACENT"
+                )
+        
+        # Steal a random card
+        import random
+        stolen_card = random.choice(target.cards)
+        target.remove_cards([stolen_card])
+        self.game.players[action.player_id].add_cards([stolen_card])
+        
+        # Update state
+        self._current_game_state.turn_phase = TurnPhase.PLAYER_ACTIONS
+        self._current_game_state.steal_pending = False
+        
+        # Notify (don't reveal what card was stolen to everyone)
+        thief_name = self.users[action.player_id].name if hasattr(self.users[action.player_id], 'name') else f"Player {action.player_id}"
+        victim_name = self.users[target_player].name if hasattr(self.users[target_player], 'name') else f"Player {target_player}"
+        
+        self._notify_all_users(
+            "steal_complete",
+            f"🎯 {thief_name} stole a card from {victim_name}!"
+        )
+        
+        # Notify the thief specifically what they got
+        self._notify_user(
+            action.player_id,
+            action,
+            True,
+            f"You stole a {stolen_card.name}!"
+        )
+        
+        return ActionResult.success_result(self.get_full_state())
+    
+    def __str__(self) -> str:
+        """String representation of the GameManager."""
+        status = "running" if self._is_running else "stopped"
+        if self._is_paused:
+            status = "paused"
+        
+        return f"GameManager(id={self.game_id[:8]}, players={self.num_players}, status={status})"
+    
+    def __repr__(self) -> str:
+        """Detailed string representation of the GameManager."""
+        return (f"GameManager(game_id='{self.game_id}', "
+                f"players={self.num_players}, "
+                f"current_player={self.current_player_id}, "
+                f"turn={self._current_game_state.turn_number}, "
+                f"running={self._is_running}, "
+                f"paused={self._is_paused})")

pycatan/game_moves.txt

@@ -0,0 +1,19 @@
+s 3
+road 3 4
+s 34
+road 34 23
+s 12
+road 12 22
+s 31 
+road 31 32
+roll
+t player v wood ore 
+t player v wood sheep
+y
+t player v brick wood
+y
+t player v wood brick
+n
+roll
+end
+roll

pycatan/harbor.py

@@ -0,0 +1,70 @@
+from enum import Enum
+from pycatan.card import ResCard
+
+# The different types of harbors found throughout the game
+class HarborType(Enum):
+    # the different 2:1 types
+    Wood = 0
+    Sheep = 1
+    Brick = 2
+    Wheat = 3
+    Ore = 4
+
+    # the 3:1 type
+    Any = 5
+
+# represents a catan harbor
+class Harbor:
+
+    def __init__(self, point_one, point_two, type):
+        # sets the type
+        self.type = type
+
+        # sets the points
+        self.point_one = point_one
+        self.point_two = point_two
+
+    def __repr__(self):
+        return "Harbor %s, %s Type %s" % (self.point_one, self.point_two, self.type)
+
+    def get_points(self):
+        return [self.point_one, self.point_two]
+
+    # returns a string representation of the type
+    # Ex: 3:1, 2:1S, 2:1Wh
+    def get_type(self):
+
+        if self.type == HarborType.Wood:
+            return "2:1W"
+
+        elif self.type == HarborType.Sheep:
+            return "2:1S"
+
+        elif self.type == HarborType.Brick:
+            return "2:1B"
+
+        elif self.type == HarborType.Wheat:
+            return "2:1Wh"
+
+        elif self.type == HarborType.Ore:
+            return "2:1O"
+
+        elif self.type == HarborType.Any:
+            return "3:1"
+
+    @staticmethod
+    def get_card_from_harbor_type(h_type):
+        if h_type == HarborType.Wood:
+            return ResCard.Wood
+        elif h_type == HarborType.Brick:
+            return ResCard.Brick
+        elif h_type == HarborType.Wheat:
+            return ResCard.Wheat
+        elif h_type == HarborType.Ore:
+            return ResCard.Ore
+        elif h_type == HarborType.Sheep:
+            return ResCard.Sheep
+        elif h_type == HarborType.Any:
+            return None
+        else:
+            raise Exception("Harbor has invalid type %s" % h_type)

pycatan/human_user.py

@@ -0,0 +1,667 @@
+"""
+Human User Implementation for PyCatan Game Management
+
+This module implements HumanUser, which provides a command-line interface
+for human players to interact with the game.
+"""
+
+from typing import List, Optional, Dict, Tuple
+from pycatan.user import User, UserInputError
+from pycatan.actions import Action, ActionType, GameState
+from pycatan.card import ResCard, DevCard
+from pycatan.board_definition import board_definition
+
+
+class HumanUser(User):
+    """
+    Human user implementation with command-line interface.
+    
+    This class provides a text-based interface for human players to interact
+    with the game. It parses text commands and converts them to Action objects.
+    """
+    
+    def __init__(self, name: str, user_id: int):
+        """Initialize a HumanUser with CLI interface."""
+        super().__init__(name, user_id)
+        self.command_history = []
+    
+    def get_input(self, game_state: GameState, prompt_message: str, 
+                  allowed_actions: Optional[List[str]] = None) -> Action:
+        """
+        Get input from human player via command line.
+        
+        Args:
+            game_state: Current state of the game
+            prompt_message: Message explaining what input is needed
+            allowed_actions: Optional list of allowed action types
+            
+        Returns:
+            Action: The action the player wants to perform
+            
+        Raises:
+            UserInputError: If input parsing fails or action is invalid
+        """
+        while True:
+            try:
+                # Show game status
+                self._display_game_status(game_state)
+                
+                # Show prompt with clear format
+                print(f"\n>>> {self.name}'s Turn")
+                
+                # Show allowed actions in a compact format
+                if allowed_actions:
+                    # Format actions nicely (e.g., "BUILD_SETTLEMENT" -> "build settlement")
+                    formatted_actions = [self._format_action_name(a) for a in allowed_actions]
+                    actions_str = " | ".join(formatted_actions)
+                    print(f"    Options: {actions_str}")
+                
+                # Get user input with clean prompt
+                user_input = input(f"    {self.name} > ").strip()
+                
+                if not user_input:
+                    continue
+                
+                # Store in history
+                self.command_history.append(user_input)
+                
+                # Parse the input into an action
+                action = self._parse_input(user_input, game_state)
+                
+                # Validate against allowed actions if provided
+                if allowed_actions and action.action_type.name not in allowed_actions:
+                    print(f"    ✗ '{self._format_action_name(action.action_type.name)}' is not allowed right now.")
+                    continue
+                
+                return action
+                
+            except UserInputError as e:
+                print(f"    ✗ {e.message}")
+            except KeyboardInterrupt:
+                print("\n    Game interrupted by user.")
+                return Action(ActionType.END_TURN, self.user_id)
+    
+    def _display_game_status(self, game_state: GameState) -> None:
+        return
+        """Display current game status to the user."""
+        print("\n" + "="*60)
+        print(f"🎮 GAME STATUS - Turn {game_state.turn_number}")
+        print("="*60)
+        
+        # Show all players
+        for player in game_state.players_state:
+            is_current = player.player_id == game_state.current_player
+            marker = "👉 " if is_current else "   "
+            
+            print(f"\n{marker}Player {player.player_id}: {player.name}")
+            print(f"   🏆 Victory Points: {player.victory_points}")
+            
+            # Count resources
+            resource_count = {}
+            for card in player.cards:
+                resource_count[card] = resource_count.get(card, 0) + 1
+            
+            if resource_count:
+                # Show only if it's the current user or if viewing own cards
+                if player.player_id == self.user_id:
+                    print(f"   📦 Resources: ", end="")
+                    cards_str = ", ".join([f"{count} {res}" for res, count in resource_count.items()])
+                    print(cards_str)
+                else:
+                    # Just show total count for other players
+                    print(f"   📦 Resources: {len(player.cards)} cards")
+            else:
+                print(f"   📦 Resources: none")
+            
+            print(f"   🏘️  Settlements: {len(player.settlements)} | Cities: {len(player.cities)} | Roads: {len(player.roads)}")
+            
+            if player.dev_cards:
+                print(f"   🎴 Dev Cards: {len(player.dev_cards)}")
+            
+            if player.has_longest_road:
+                print(f"   🛣️  Has Longest Road!")
+            if player.has_largest_army:
+                print(f"   ⚔️  Has Largest Army!")
+        
+        print("\n" + "="*60)
+    
+    def _format_action_name(self, action_name: str) -> str:
+        """Convert action enum name to readable format."""
+        # Convert "BUILD_SETTLEMENT" to "build settlement"
+        words = action_name.replace("_", " ").lower()
+        return words
+    
+    def _parse_input(self, user_input: str, game_state: GameState) -> Action:
+        """
+        Parse user input text into an Action object.
+        
+        Args:
+            user_input: Text command from user
+            game_state: Current game state for context
+            
+        Returns:
+            Action: Parsed action
+            
+        Raises:
+            UserInputError: If parsing fails
+        """
+        parts = user_input.lower().split()
+        if not parts:
+            raise UserInputError("Empty command")
+        
+        command = parts[0]
+        
+        # Handle different commands
+        if command in ['help', 'h', '?']:
+            self._show_help()
+            raise UserInputError("Help displayed, please enter a command")
+        
+        elif command in ['quit', 'exit', 'q']:
+            raise KeyboardInterrupt("User requested to quit")
+        
+        elif command in ['points', 'p']:
+            self._show_points()
+            raise UserInputError("Points displayed, please enter a command")
+        
+        elif command in ['status', 'info', 'i']:
+            self._show_game_status(game_state)
+            raise UserInputError("Game status displayed, please enter a command")
+        
+        elif command in ['end', 'pass', 'done']:
+            return Action(ActionType.END_TURN, self.user_id)
+        
+        elif command in ['roll', 'dice', 'r']:
+            return Action(ActionType.ROLL_DICE, self.user_id)
+        
+        elif command in ['settlement', 'settle', 's', 'set']:
+            return self._parse_build_settlement(parts, game_state)
+        
+        elif command in ['city', 'c']:
+            return self._parse_build_city(parts, game_state)
+        
+        elif command in ['road', 'rd']:
+            return self._parse_build_road(parts, game_state)
+        
+        elif command in ['trade', 't']:
+            return self._parse_trade(parts, game_state)
+        
+        elif command in ['buy', 'dev']:
+            return Action(ActionType.BUY_DEV_CARD, self.user_id)
+        
+        elif command in ['use']:
+            return self._parse_use_dev_card(parts, game_state)
+        
+        elif command in ['robber', 'rob']:
+            return self._parse_robber_move(parts, game_state)
+        
+        elif command in ['drop', 'discard']:
+            return self._parse_discard_cards(parts, game_state)
+        
+        elif command in ['steal']:
+            return self._parse_steal(parts, game_state)
+        
+        elif command in ['yes', 'y', 'accept']:
+            return Action(ActionType.TRADE_ACCEPT, self.user_id)
+        
+        elif command in ['no', 'n', 'reject', 'decline']:
+            return Action(ActionType.TRADE_REJECT, self.user_id)
+        
+        else:
+            raise UserInputError(f"Unknown command: {command}. Type 'help' for available commands.")
+    
+    def _parse_build_settlement(self, parts: List[str], game_state: GameState) -> Action:
+        """Parse settlement building command."""
+        # Support both old coordinate format and new point format
+        if len(parts) < 2:
+            raise UserInputError("Settlement command requires a point number or coordinates. Example: 'settlement 12' or 'settlement 0 5'")
+        
+        # Check if using new point format (1 number) or old coordinate format (2 numbers)
+        if len(parts) == 2 or (len(parts) == 3 and parts[2].lower() in ['start', 'starting']):
+            # New point format: settlement <point> [start]
+            try:
+                point = int(parts[1])
+                is_starting = len(parts) > 2 and parts[2].lower() in ['start', 'starting']
+                
+                # Convert point to coordinates using BoardDefinition
+                coords = board_definition.point_id_to_game_coords(point)
+                if coords is None:
+                    raise UserInputError(f"Invalid point number: {point}. Valid points: 1-{len(board_definition.get_all_point_ids())}")
+                
+                row, index = coords
+                
+            except ValueError:
+                raise UserInputError("Point number must be a valid integer. Example: 'settlement 12'")
+                
+        else:
+            # Old coordinate format: settlement <row> <index> [start]
+            if len(parts) < 3:
+                raise UserInputError("Old format settlement command requires row and index. Example: 'settlement 0 5'")
+            
+            try:
+                row = int(parts[1])
+                index = int(parts[2])
+                is_starting = len(parts) > 3 and parts[3].lower() in ['start', 'starting']
+                
+            except ValueError:
+                raise UserInputError("Row and index must be numbers. Example: 'settlement 0 5'")
+        
+        # Auto-detect if we're in setup phase to determine action type
+        in_setup = hasattr(game_state, 'game_phase') and hasattr(game_state.game_phase, 'name') and \
+                   'SETUP' in game_state.game_phase.name
+        
+        # Force starting settlement if in setup phase
+        if in_setup:
+            action_type = ActionType.PLACE_STARTING_SETTLEMENT
+        else:
+            action_type = ActionType.PLACE_STARTING_SETTLEMENT if is_starting else ActionType.BUILD_SETTLEMENT
+        
+        params = {
+            'point_coords': [row, index],
+            'is_starting': in_setup or is_starting
+        }
+        
+        return Action(action_type, self.user_id, params)
+    
+    def _parse_build_city(self, parts: List[str], game_state: GameState) -> Action:
+        """Parse city building command."""
+        # Support both old coordinate format and new point format
+        if len(parts) < 2:
+            raise UserInputError("City command requires a point number or coordinates. Example: 'city 12' or 'city 0 5'")
+        
+        # Check if using new point format (1 number) or old coordinate format (2 numbers)
+        if len(parts) == 2:
+            # New point format: city <point>
+            try:
+                point = int(parts[1])
+                
+                # Convert point to coordinates
+                coords = point_to_coords(point)
+                if coords is None:
+                    raise UserInputError(f"Invalid point number: {point}. Valid points: 1-{len(get_all_points())}")
+                
+                row, index = coords
+                
+            except ValueError:
+                raise UserInputError("Point number must be a valid integer. Example: 'city 12'")
+                
+        else:
+            # Old coordinate format: city <row> <index>
+            if len(parts) < 3:
+                raise UserInputError("Old format city command requires row and index. Example: 'city 0 5'")
+            
+            try:
+                row = int(parts[1])
+                index = int(parts[2])
+                
+            except ValueError:
+                raise UserInputError("Row and index must be numbers. Example: 'city 0 5'")
+        
+        params = {'point_coords': [row, index]}
+        return Action(ActionType.BUILD_CITY, self.user_id, params)
+    
+    def _parse_build_road(self, parts: List[str], game_state: GameState) -> Action:
+        """Parse road building command."""
+        # Support both old coordinate format and new point format
+        if len(parts) < 3:
+            raise UserInputError("Road command requires 2 points. Example: 'road 5 6' or 'road 0 5 0 6'")
+        
+        # Check if using new point format (2 numbers) or old coordinate format (4 numbers)
+        if len(parts) == 3 or (len(parts) == 4 and parts[3].lower() in ['start', 'starting']):
+            # New point format: road <point1> <point2> [start]
+            try:
+                point1 = int(parts[1])
+                point2 = int(parts[2])
+                is_starting = len(parts) > 3 and parts[3].lower() in ['start', 'starting']
+                
+                # Validate road placement using BoardDefinition
+                if not board_definition.is_valid_road_placement(point1, point2):
+                    raise UserInputError(f"Cannot build road between points {point1} and {point2} - they are not adjacent")
+                
+                # Convert points to coordinates using BoardDefinition
+                start_coords = board_definition.point_id_to_game_coords(point1)
+                end_coords = board_definition.point_id_to_game_coords(point2)
+                
+                if start_coords is None:
+                    raise UserInputError(f"Invalid point number: {point1}. Valid points: 1-{len(board_definition.get_all_point_ids())}")
+                if end_coords is None:
+                    raise UserInputError(f"Invalid point number: {point2}. Valid points: 1-{len(board_definition.get_all_point_ids())}")
+                
+                start_row, start_index = start_coords
+                end_row, end_index = end_coords
+                
+            except ValueError:
+                raise UserInputError("Point numbers must be valid integers. Example: 'road 5 6'")
+                
+        else:
+            # Old coordinate format: road <start_row> <start_index> <end_row> <end_index> [start]
+            if len(parts) < 5:
+                raise UserInputError("Old format road command requires start and end coordinates. Example: 'road 0 5 0 6'")
+            
+            try:
+                start_row = int(parts[1])
+                start_index = int(parts[2])
+                end_row = int(parts[3])
+                end_index = int(parts[4])
+                is_starting = len(parts) > 5 and parts[5].lower() in ['start', 'starting']
+                
+            except ValueError:
+                raise UserInputError("Coordinates must be numbers. Example: 'road 0 5 0 6'")
+        
+        # Auto-detect if we're in setup phase to determine action type
+        in_setup = hasattr(game_state, 'game_phase') and hasattr(game_state.game_phase, 'name') and \
+                   'SETUP' in game_state.game_phase.name
+        
+        # Force starting road if in setup phase
+        if in_setup:
+            action_type = ActionType.PLACE_STARTING_ROAD
+        else:
+            action_type = ActionType.PLACE_STARTING_ROAD if is_starting else ActionType.BUILD_ROAD
+        
+        params = {
+            'start_coords': [start_row, start_index],
+            'end_coords': [end_row, end_index],
+            'is_starting': in_setup or is_starting
+        }
+        
+        return Action(action_type, self.user_id, params)
+    
+    def _parse_trade(self, parts: List[str], game_state: GameState) -> Action:
+        """Parse trading command."""
+        if len(parts) < 2:
+            raise UserInputError("Trade command needs more info. Examples: 'trade bank wood 4 wheat 1' or 'trade player 1 wood sheep'")
+        
+        if parts[1].lower() == 'bank':
+            return self._parse_bank_trade(parts[2:])
+        elif parts[1].lower() == 'player':
+            return self._parse_player_trade(parts[2:], game_state)
+        else:
+            raise UserInputError("Trade must specify 'bank' or 'player'. Examples: 'trade bank wood 4 wheat 1' or 'trade player 1 wood sheep'")
+    
+    def _parse_bank_trade(self, parts: List[str]) -> Action:
+        """Parse bank trading command."""
+        if len(parts) < 4:
+            raise UserInputError("Bank trade format: 'trade bank [give_resource] [give_amount] [get_resource] [get_amount]'")
+        
+        try:
+            give_resource = self._parse_resource(parts[0])
+            give_amount = int(parts[1])
+            get_resource = self._parse_resource(parts[2])
+            get_amount = int(parts[3])
+            
+            params = {
+                'offer': {give_resource.name.lower(): give_amount},
+                'request': {get_resource.name.lower(): get_amount}
+            }
+            
+            return Action(ActionType.TRADE_BANK, self.user_id, params)
+            
+        except (ValueError, KeyError):
+            raise UserInputError("Invalid trade format or resource names")
+    
+    def _parse_player_trade(self, parts: List[str], game_state: GameState = None) -> Action:
+        """Parse player trading command."""
+        if len(parts) < 3:
+            raise UserInputError("Player trade format: 'trade player [player_id_or_name] [your_resource] [their_resource]'")
+        
+        try:
+            # Try to parse as player ID first
+            try:
+                target_player = int(parts[0])
+            except ValueError:
+                # Not a number, try to find by name
+                player_name = parts[0].lower()
+                target_player = None
+                
+                if game_state and game_state.players_state:
+                    for player in game_state.players_state:
+                        if player.name.lower() == player_name:
+                            target_player = player.player_id
+                            break
+                
+                if target_player is None:
+                    raise UserInputError(f"Player '{parts[0]}' not found. Use player name or ID (0-{len(game_state.players_state)-1 if game_state else 3})")
+            
+            give_resource = self._parse_resource(parts[1])
+            get_resource = self._parse_resource(parts[2])
+            
+            params = {
+                'target_player': target_player,
+                'offer': {give_resource.name.lower(): 1},
+                'request': {get_resource.name.lower(): 1}
+            }
+            
+            return Action(ActionType.TRADE_PROPOSE, self.user_id, params)
+            
+        except (ValueError, KeyError):
+            raise UserInputError("Invalid trade format or resource names")
+    
+    def _parse_use_dev_card(self, parts: List[str], game_state: GameState) -> Action:
+        """Parse development card usage command."""
+        if len(parts) < 2:
+            raise UserInputError("Use command requires card type. Example: 'use knight' or 'use road'")
+        
+        card_name = parts[1].lower()
+        params = {'card_type': card_name}
+        
+        # Add specific parameters based on card type
+        if card_name == 'knight' and len(parts) >= 5:
+            try:
+                robber_row = int(parts[2])
+                robber_index = int(parts[3])
+                victim_player = int(parts[4]) if parts[4] != 'none' else None
+                
+                params.update({
+                    'tile_coords': [robber_row, robber_index],
+                    'victim': victim_player
+                })
+            except ValueError:
+                raise UserInputError("Knight card format: 'use knight [robber_row] [robber_index] [victim_player_or_none]'")
+        
+        return Action(ActionType.USE_DEV_CARD, self.user_id, params)
+    
+    def _parse_robber_move(self, parts: List[str], game_state: GameState) -> Action:
+        """Parse robber movement command.
+        
+        Format: 'robber [row] [index]' or 'rob [row] [index]'
+        The steal action is now separate via 'steal [player]' command.
+        """
+        if len(parts) < 3:
+            raise UserInputError("Robber command format: 'robber [row] [index]'. Example: 'robber 2 1'")
+        
+        try:
+            row = int(parts[1])
+            index = int(parts[2])
+            
+            params = {
+                'tile_coords': [row, index]
+            }
+            
+            return Action(ActionType.ROBBER_MOVE, self.user_id, params)
+            
+        except ValueError:
+            raise UserInputError("Robber coordinates must be numbers. Example: 'robber 2 1'")
+    
+    def _parse_steal(self, parts: List[str], game_state: GameState) -> Action:
+        """Parse steal card command.
+        
+        Format: 'steal [player_id_or_name]' or 'steal none'
+        """
+        if len(parts) < 2:
+            raise UserInputError("Steal command format: 'steal [player_id_or_name]' or 'steal none'")
+        
+        target = parts[1].lower()
+        
+        if target == 'none':
+            # No one to steal from (all adjacent players have 0 cards)
+            params = {'target_player': None}
+        else:
+            try:
+                # Try to parse as player ID first
+                target_player = int(target)
+            except ValueError:
+                # Try to find by name
+                target_player = None
+                if game_state and game_state.players_state:
+                    for player in game_state.players_state:
+                        if player.name.lower() == target:
+                            target_player = player.player_id
+                            break
+                
+                if target_player is None:
+                    raise UserInputError(f"Player '{parts[1]}' not found.")
+            
+            params = {'target_player': target_player}
+        
+        return Action(ActionType.STEAL_CARD, self.user_id, params)
+    
+    def _parse_discard_cards(self, parts: List[str], game_state: GameState) -> Action:
+        """Parse discard cards command.
+        
+        Format: 'drop [amount1] [resource1] [amount2] [resource2] ...'
+        Example: 'drop 2 wood 1 brick' means discard 2 wood and 1 brick
+        
+        The game will validate that the total discarded equals the required amount
+        and that the player has those cards.
+        """
+        if len(parts) < 3:
+            raise UserInputError(
+                "Discard command format: 'drop [amount] [resource] [amount] [resource] ...'\n"
+                "Example: 'drop 2 wood 1 brick' to discard 2 wood and 1 brick"
+            )
+        
+        # Parse pairs of (amount, resource)
+        cards_to_discard = []
+        i = 1
+        
+        while i < len(parts) - 1:
+            try:
+                amount = int(parts[i])
+                resource_name = parts[i + 1].lower()
+                
+                # Parse the resource
+                resource = self._parse_resource(resource_name)
+                
+                # Add the cards to discard list (one entry per card)
+                for _ in range(amount):
+                    cards_to_discard.append(resource.name)
+                
+                i += 2
+            except ValueError:
+                raise UserInputError(
+                    f"Invalid format at '{parts[i]}'. Expected: [amount] [resource]\n"
+                    "Example: 'drop 2 wood 1 brick'"
+                )
+        
+        if not cards_to_discard:
+            raise UserInputError("You must specify at least one card to discard.")
+        
+        params = {'cards': cards_to_discard}
+        return Action(ActionType.DISCARD_CARDS, self.user_id, params)
+    
+    def _parse_resource(self, resource_name: str) -> ResCard:
+        """Parse resource name to ResCard enum."""
+        resource_mapping = {
+            'wood': ResCard.Wood,
+            'lumber': ResCard.Wood,
+            'brick': ResCard.Brick,
+            'sheep': ResCard.Sheep,
+            'wool': ResCard.Sheep,
+            'wheat': ResCard.Wheat,
+            'grain': ResCard.Wheat,
+            'ore': ResCard.Ore,
+            'stone': ResCard.Ore
+        }
+        
+        resource_name = resource_name.lower()
+        if resource_name not in resource_mapping:
+            raise UserInputError(f"Unknown resource: {resource_name}. Valid resources: {list(resource_mapping.keys())}")
+        
+        return resource_mapping[resource_name]
+    
+    def _show_points(self) -> None:
+        """Display all available points on the board."""
+        print("\n" + "="*60)
+        print("BOARD POINTS MAP")
+        print("="*60)
+        
+        # Get all points using BoardDefinition
+        all_points_list = board_definition.get_all_point_ids()
+        
+        # Group points by row for cleaner display
+        points_by_row = {}
+        for point_id in all_points_list:
+            coords = board_definition.point_id_to_game_coords(point_id)
+            if coords:
+                row, index = coords
+                if row not in points_by_row:
+                    points_by_row[row] = []
+                points_by_row[row].append((point_id, index))
+        
+        # Display by row
+        for row in sorted(points_by_row.keys()):
+            points_in_row = sorted(points_by_row[row], key=lambda x: x[1])
+            point_list = [f"{pid}({idx})" for pid, idx in points_in_row]
+            print(f"Row {row}: {', '.join(point_list)}")
+        
+        print()
+        print("Format: Point_ID(Index)")
+        print("Usage: 'settlement 12' builds at point 12")
+        print("       'road 5 6' builds road between points 5 and 6")
+        print("="*60)
+
+    def _show_help(self) -> None:
+        """Display help information to the user."""
+        print("\n" + "="*60)
+        print("🎮 PYCATAN COMMANDS HELP")
+        print("="*60)
+        print("🏗️  BUILDING (Points 1-54):")
+        print("  s <point>           - Build settlement (short: s, settle, settlement)")
+        print("  road <p1> <p2>      - Build road between points (short: rd)")
+        print("  city <point>        - Upgrade settlement to city (short: c)")
+        print()
+        print("💰 TRADING:")
+        print("  trade bank <give> <amount> <get> <amount>")
+        print("  trade player <id_or_name> <give> <get>    (short: t)")
+        print("  Examples: 'trade bank wood 4 sheep 1' or 't player v wood sheep'")
+        print()
+        print("🃏 DEVELOPMENT CARDS:")
+        print("  buy                 - Buy development card (short: dev)")
+        print("  use <card_type>     - Use development card")
+        print()
+        print("🎲 TURN ACTIONS:")
+        print("  roll               - Roll dice (short: r, dice)")
+        print("  end                - End turn (short: pass, done)")
+        print()
+        print("ℹ️  INFO:")
+        print("  help               - Show this help (short: h, ?)")
+        print("  status             - Show all players' status (short: info, i)")
+        print("  points             - Show all valid points (short: p)")
+        print()
+        print("📦 RESOURCES: wood, brick, sheep, wheat, ore")
+        print("🎯 POINTS: Use numbers 1-54. Example: 's 12' builds settlement at point 12")
+        print("🔗 ROADS: Example: 'road 5 6' builds road between points 5 and 6")
+        print("="*60)
+    
+    def notify_action(self, action: Action, success: bool, message: str = "") -> None:
+        """Notify the user about an action result."""
+        # Don't print here - the console visualization already displays this
+        # This method is kept for compatibility but doesn't produce output
+        pass
+    
+    def notify_game_event(self, event_type: str, message: str, 
+                         affected_players: Optional[List[int]] = None) -> None:
+        """Notify the user about general game events."""
+        # Only notify for specific important events - avoid clutter
+        skip_events = [
+            'turn_change',  # Already handled by display_turn_start
+            'action_performed',  # Already handled by notify_action + visualization
+            'phase_change'  # Important, show this
+        ]
+        
+        # Skip most events to avoid clutter
+        if event_type not in ['phase_change']:
+            return
+        
+        # For phase changes, show them clearly
+        if event_type == 'phase_change':
+            print(f"\n    ✨ {message}\n")

pycatan/player.py

@@ -0,0 +1,385 @@
+from pycatan.building import Building
+from pycatan.statuses import Statuses
+from pycatan.card import ResCard, DevCard
+
+import math
+
+# The player class for
+class Player:
+
+    def __init__ (self, game, num):
+        # the game the player belongs to
+        self.game = game
+        # the player number for this player
+        self.num = num
+        # the starting roads for this player
+        # used to determine the longest road
+        self.starting_roads = []
+        # the number of victory points
+        self.victory_points = 0
+        # the cards the player has
+        # each will be a number corresponding with the static variables CARD_<type>
+        self.cards = []
+        # the development cards this player has
+        self.dev_cards = []
+        # the number of knight cards the player has played
+        self.knight_cards = 0
+        # the longest road segment this player has
+        self.longest_road_length = 0
+
+    # builds a settlement belonging to this player
+    def build_settlement(self, point, is_starting=False):
+
+        if not is_starting:
+            # makes sure the player has the cards to build a settlements
+            cards_needed = [
+                ResCard.Wood,
+                ResCard.Brick,
+                ResCard.Sheep,
+                ResCard.Wheat
+            ]
+
+            # checks the player has the cards
+            if not self.has_cards(cards_needed):
+                return Statuses.ERR_CARDS
+
+            # checks it is connected to a road owned by the player
+            connected_by_road = False
+            # gets the roads
+            roads = self.game.board.roads
+
+            for r in roads:
+                # checks if the road is connected
+                if r.point_one is point or r.point_two is point:
+                    # checks this player owns the road
+                    if r.owner == self.num:
+                        connected_by_road = True
+
+            if not connected_by_road:
+                return Statuses.ERR_ISOLATED
+
+        # checks that a building does not already exist there
+        if point.building != None:
+            return Statuses.ERR_BLOCKED
+
+        # checks all other settlements are at least 2 away
+        # gets the connecting point's coords
+        points = point.connected_points
+        for p in points:
+
+            # checks if the point is occupied
+            if p.building != None:
+                return Statuses.ERR_BLOCKED
+
+        if not is_starting:
+            # removes the cards
+            self.remove_cards(cards_needed)
+
+        # adds the settlement
+        self.game.board.add_building(Building(
+            owner = self.num,
+            type = Building.BUILDING_SETTLEMENT,
+            point_one = point),
+            point = point)
+        # adds a victory point
+        self.victory_points += 1
+
+        return Statuses.ALL_GOOD
+
+    # checks if the player has all of the cards given in an array
+    def has_cards(self, cards):
+
+        # needs to duplicate the cards, and then delete them once found
+        # otherwise checking if the player has multiple of the same card
+        # will return true with only one card
+
+        # cards_dup stands for cards duplicate
+        cards_dup = self.cards[:]
+        for c in cards:
+            if cards_dup.count(c) == 0:
+                return False
+            else:
+                index = cards_dup.index(c)
+                del cards_dup[index]
+
+        return True
+
+    # adds some cards to a player's hand
+    def add_cards(self, cards):
+        for c in cards:
+            self.cards.append(c)
+
+    # removes cards from a player's hand
+    def remove_cards(self, cards):
+        # makes sure it has all the cards before deleting any
+        if not self.has_cards(cards):
+            return Statuses.ERR_CARDS
+
+        else:
+            # removes the cards
+            for c in cards:
+                index = self.cards.index(c)
+                del self.cards[index]
+
+    #adds a development card
+    def add_dev_card(self, dev_card):
+        self.dev_cards.append(dev_card)
+
+    # removes a dev card
+    def remove_dev_card(self, card):
+        # finds the card
+        for i in range(len(self.dev_cards)):
+            if self.dev_cards[i] == card:
+
+                # deletes the card
+                del self.dev_cards[i]
+                return Statuses.ALL_GOOD
+
+        # error if the player does not have the cards
+        return Statuses.ERR_CARDS
+
+    # checks a road location is valid
+    def road_location_is_valid(self, start, end):
+        # checks the two points are connected
+        connected = False
+        # gets the points connected to start
+        points = start.connected_points
+
+        for p in points:
+            if end == p:
+                connected = True
+                break
+
+        if not connected:
+            return Statuses.ERR_NOT_CON
+
+        connected_by_road = False
+        for road in self.game.board.roads:
+            # checks the road does not already exists with these points
+            if road.point_one == start or road.point_two == start:
+                if road.point_one == end or road.point_two == end:
+                    return Statuses.ERR_BLOCKED
+
+        # check this player has a settlement on one of these points or a connecting road
+        is_connected = False
+
+        if start.building != None:
+            # checks if this player owns the settlement/city
+            if start.building.owner == self.num:
+                is_connected = True
+
+        # does the same for the other point
+        elif end.building != None:
+            if end.building.owner == self.num:
+                is_connected = True
+
+        # then checks if there is a road connecting them
+        roads = self.game.board.roads
+        points = [start, end]
+
+        for r in roads:
+            for p in points:
+                if r.point_one == p or r.point_two == p:
+
+                    # checks that there is not another player's settlement here, so that it's not going through it
+                    if p.building == None:
+                        is_connected = True
+
+                    # if theere is a settlement/city there, the road can be built if this player owns it
+                    elif p.building.owner == self.num:
+                        is_connected = True
+
+        if not is_connected:
+            return Statuses.ERR_ISOLATED
+
+        return Statuses.ALL_GOOD
+
+    # builds a road
+    def build_road(self, start, end, is_starting=False):
+
+        # checks the location is valid
+        location_status = self.road_location_is_valid(start=start, end=end)
+
+        if not location_status == Statuses.ALL_GOOD:
+            return location_status
+
+        # if the road is being created on the starting turn, the player does not needed
+        # to have the cards
+        if not is_starting:
+
+            # checks that it has the proper cards
+            cards_needed = [
+                ResCard.Wood,
+                ResCard.Brick
+            ]
+            if not self.has_cards(cards_needed):
+                return Statuses.ERR_CARDS
+
+            # removes the cards
+            self.remove_cards(cards_needed)
+
+        # adds the road
+        road = Building(owner=self.num, type=Building.BUILDING_ROAD, point_one=start, point_two=end)
+        (self.game).board.add_road(road)
+
+        self.get_longest_road(new_road=road)
+
+        return Statuses.ALL_GOOD
+
+    # returns an array of all the harbors the player has access to
+    def get_connected_harbor_types(self):
+
+        # gets the settlements/cities belonging to this player
+        harbors = []
+        all_harbors = self.game.board.harbors
+        buildings = self.game.board.get_buildings()
+
+        for b in buildings:
+            # checks the building belongs to this player
+            if b.owner == self.num:
+                # checks if the building is connected to any harbors
+                for h in all_harbors:
+                    print(h)
+                    print(b.point)
+                    if h.point_one is b.point or h.point_two is b.point:
+                        print("A")
+                        # adds the type
+                        if harbors.count(h.type) == 0:
+                            harbors.append(h.type)
+
+        return harbors
+
+    # gets the longest road segment this player has which includes the road given
+    # should be called whenever a new road is build
+    # since this player's longest road will only change if a new road is build
+    def get_longest_road(self, new_road):
+
+        # gets the roads that belong to this player
+        roads = self.get_roads()
+        del roads[roads.index(new_road)]
+
+        # checks for longest road
+        self.check_connected_roads(road=new_road, all_roads=roads, length=1)
+
+    # checks the roads for connected roads, and then checks those roads until there are no more
+    def check_connected_roads(self, road, all_roads, length):
+
+        # do both point one and two
+        points = [
+            road.point_one,
+            road.point_two
+        ]
+
+        for p in points:
+            # gets the connected roads
+            connected = self.get_connected_roads(point=p, roads=all_roads)
+            # if there are no new connected roads
+            if len(connected) == 0:
+                # if this is the longest road so far
+                if length > self.longest_road_length:
+                    # records the length
+                    self.longest_road_length = length
+                    # self.begin_celebration()
+
+            # if there are connected roads
+            else:
+                # check each of them for connections if they have not been used
+                for c in connected:
+                    # checks it hasn't used this road before
+                    if all_roads.count(c) > 0:
+                        # copies all usable roads
+                        c_roads = all_roads[:]
+                        # removes this road from them
+                        del c_roads[c_roads.index(c)]
+                        # checks for connected roads to this road
+                        self.check_connected_roads(c, c_roads, length + 1)
+
+    # returns which roads in the roads array are connected to the point
+    def get_connected_roads(self, point, roads):
+        con_roads = []
+        for r in roads:
+            if r.point_one == point or r.point_two == point:
+                con_roads.append(r)
+
+        return con_roads
+
+    # returns an array of all the roads belonging to this player
+    def get_roads(self):
+        # gets all the roads on the board
+        all_roads = (self.game).board.roads
+        # filters out roads that do not belong to this player
+        roads = []
+        for r in all_roads:
+            if r.owner == self.num:
+                roads.append(r)
+
+        return roads
+
+    # checks if the player has some development cards
+    def has_dev_cards(self, cards):
+        card_duplicate = self.dev_cards[:]
+        for c in cards:
+            if not card_duplicate.count(c) > 0:
+                return False
+            else:
+                del card_duplicate[card_duplicate.index(c)]
+
+        return True
+
+    # returns the number of VP
+    # if include_dev is False, it will not include points from developement cards
+    # because other players aren't able to see them
+    def get_VP(self, include_dev=False):
+
+        # gets the victory points from settlements and cities
+        points = self.victory_points
+
+        # adds VPs from longest road
+        if self.game.longest_road_owner == self.num:
+            points += 2
+
+        # adds VPs from largest army
+        if self.game.largest_army == self.num:
+            points += 2
+
+        # adds VPs from developement cards
+        if include_dev:
+            for d in self.dev_cards:
+                if d == DevCard.VP:
+                    points += 1
+
+        return points
+
+    # prints the cards given
+    @staticmethod
+    def print_cards(cards):
+        print("[")
+        for c in cards:
+
+            card_name = ""
+
+            if c == ResCard.Wood:
+                card_name = "Wood"
+
+            elif c == ResCard.Sheep:
+                card_name = "Sheep"
+
+            elif c == ResCard.Brick:
+                card_name = "Brick"
+
+            elif c == ResCard.Wheat:
+                card_name = "Wheat"
+
+            elif c == ResCard.Ore:
+                card_name = "Ore"
+
+            else:
+                print("INVALID CARD %s" % c)
+                continue
+
+            if cards.index(c) < len(cards) - 1:
+                card_name += ","
+
+            print("    %s" % card_name)
+
+        print("]")

pycatan/point.py

@@ -0,0 +1,8 @@
+class Point:
+    def __init__(self, tiles, position):
+        self.tiles = tiles
+        self.building = None
+        self.position = position
+
+    def __repr__(self):
+        return "| Point at r=%s, i=%s |" % (self.position[0], self.position[1])

pycatan/point_mapping.py

@@ -0,0 +1,202 @@
+"""
+Point Mapping System for PyCatan
+
+This module provides translation between user-friendly point IDs (1, 2, 3...)
+and internal coordinate system ([row, index]).
+
+This creates a unified point reference system for both human input and visualization.
+"""
+
+from typing import Dict, List, Tuple, Optional
+import json
+import os
+
+
+class PointMapper:
+    """
+    Manages mapping between point IDs and coordinates.
+    
+    Point IDs are simple numbers (1, 2, 3...) that users can easily reference.
+    Coordinates are [row, index] pairs used internally by the game engine.
+    """
+    
+    def __init__(self):
+        """Initialize the point mapper."""
+        self.point_to_coords: Dict[int, List[int]] = {}
+        self.coords_to_point: Dict[str, int] = {}
+        self._load_default_mapping()
+    
+    def _load_default_mapping(self):
+        """Load the default Catan board point mapping."""
+        # Standard Catan board layout - 54 intersection points
+        # This follows the hexagonal board structure with 19 tiles
+        
+        default_mapping = [
+            # Top row (7 points) - wider at the top
+            [0, 0], [0, 1], [0, 2], [0, 3], [0, 4], [0, 5], [0, 6],
+            
+            # Second row (9 points) 
+            [1, 0], [1, 1], [1, 2], [1, 3], [1, 4], [1, 5], [1, 6], [1, 7], [1, 8],
+            
+            # Third row (11 points) - widest row
+            [2, 0], [2, 1], [2, 2], [2, 3], [2, 4], [2, 5], [2, 6], [2, 7], [2, 8], [2, 9], [2, 10],
+            
+            # Fourth row (11 points) - also widest
+            [3, 0], [3, 1], [3, 2], [3, 3], [3, 4], [3, 5], [3, 6], [3, 7], [3, 8], [3, 9], [3, 10],
+            
+            # Fifth row (9 points)
+            [4, 0], [4, 1], [4, 2], [4, 3], [4, 4], [4, 5], [4, 6], [4, 7], [4, 8],
+            
+            # Bottom row (7 points) - narrows at the bottom  
+            [5, 0], [5, 1], [5, 2], [5, 3], [5, 4], [5, 5], [5, 6]
+        ]
+        
+        # Create both mappings
+        for point_id, coords in enumerate(default_mapping, 1):
+            self.point_to_coords[point_id] = coords
+            self.coords_to_point[f"{coords[0]},{coords[1]}"] = point_id
+    
+    def point_to_coordinate(self, point_id: int) -> Optional[List[int]]:
+        """Convert point ID to coordinates."""
+        return self.point_to_coords.get(point_id)
+    
+    def coordinate_to_point(self, row: int, index: int) -> Optional[int]:
+        """Convert coordinates to point ID."""
+        return self.coords_to_point.get(f"{row},{index}")
+    
+    def get_all_points(self) -> List[int]:
+        """Get all valid point IDs."""
+        return sorted(self.point_to_coords.keys())
+    
+    def get_adjacent_points(self, point_id: int) -> List[int]:
+        """
+        Get points adjacent to the given point (for road validation).
+        
+        This is a simplified version - in a real implementation,
+        this would check actual board topology.
+        """
+        coords = self.point_to_coordinate(point_id)
+        if not coords:
+            return []
+        
+        row, index = coords
+        adjacent_coords = [
+            [row-1, index-1], [row-1, index], [row-1, index+1],
+            [row, index-1], [row, index+1],
+            [row+1, index-1], [row+1, index], [row+1, index+1]
+        ]
+        
+        adjacent_points = []
+        for adj_coords in adjacent_coords:
+            adj_point = self.coordinate_to_point(adj_coords[0], adj_coords[1])
+            if adj_point:
+                adjacent_points.append(adj_point)
+        
+        return adjacent_points
+    
+    def validate_road_placement(self, start_point: int, end_point: int) -> bool:
+        """Check if two points can be connected by a road."""
+        if start_point == end_point:
+            return False
+        
+        # Check if points are adjacent
+        adjacent_to_start = self.get_adjacent_points(start_point)
+        return end_point in adjacent_to_start
+    
+    def export_mapping(self, filename: str = "point_mapping.json"):
+        """Export mapping to JSON file for use by visualizations."""
+        export_data = {
+            "point_to_coords": self.point_to_coords,
+            "coords_to_point": self.coords_to_point,
+            "total_points": len(self.point_to_coords)
+        }
+        
+        with open(filename, 'w') as f:
+            json.dump(export_data, f, indent=2)
+        
+        print(f"Point mapping exported to {filename}")
+    
+    def import_mapping(self, filename: str):
+        """Import mapping from JSON file."""
+        if not os.path.exists(filename):
+            print(f"Mapping file {filename} not found, using default mapping")
+            return
+        
+        with open(filename, 'r') as f:
+            data = json.load(f)
+        
+        # Convert string keys back to integers for point_to_coords
+        self.point_to_coords = {int(k): v for k, v in data["point_to_coords"].items()}
+        self.coords_to_point = data["coords_to_point"]
+        
+        print(f"Point mapping imported from {filename}")
+    
+    def print_mapping(self):
+        """Print the current mapping for debugging."""
+        print("Point ID -> Coordinates mapping:")
+        print("=" * 40)
+        
+        for point_id in sorted(self.point_to_coords.keys()):
+            coords = self.point_to_coords[point_id]
+            print(f"Point {point_id:2d} -> [{coords[0]}, {coords[1]}]")
+        
+        print(f"\\nTotal points: {len(self.point_to_coords)}")
+
+
+# Global point mapper instance
+point_mapper = PointMapper()
+
+
+# Convenience functions for easy import
+def point_to_coords(point_id: int) -> Optional[List[int]]:
+    """Convert point ID to coordinates."""
+    return point_mapper.point_to_coordinate(point_id)
+
+
+def coords_to_point(row: int, index: int) -> Optional[int]:
+    """Convert coordinates to point ID."""
+    return point_mapper.coordinate_to_point(row, index)
+
+
+def validate_road(start_point: int, end_point: int) -> bool:
+    """Check if a road can be placed between two points."""
+    return point_mapper.validate_road_placement(start_point, end_point)
+
+
+def get_all_points() -> List[int]:
+    """Get all valid point IDs."""
+    return point_mapper.get_all_points()
+
+
+if __name__ == "__main__":
+    # Demo and testing
+    print("PyCatan Point Mapping System")
+    print("=" * 40)
+    
+    # Print the mapping
+    point_mapper.print_mapping()
+    
+    # Test some conversions
+    print("\\n" + "=" * 40)
+    print("Testing conversions:")
+    
+    test_points = [1, 10, 25, 54]
+    for point in test_points:
+        coords = point_to_coords(point)
+        if coords:
+            back_to_point = coords_to_point(coords[0], coords[1])
+            print(f"Point {point} -> {coords} -> Point {back_to_point}")
+    
+    # Test road validation
+    print("\\n" + "=" * 40)
+    print("Testing road placements:")
+    
+    test_roads = [(1, 2), (1, 10), (25, 26), (1, 54)]
+    for start, end in test_roads:
+        valid = validate_road(start, end)
+        status = "✓" if valid else "✗"
+        print(f"Road {start} -> {end}: {status}")
+    
+    # Export mapping for web visualization
+    print("\\n" + "=" * 40)
+    point_mapper.export_mapping("pycatan/static/js/point_mapping.json")

pycatan/real_game.py

@@ -0,0 +1,372 @@
+"""
+RealGame - Complete Interactive Catan Game Experience
+
+This class orchestrates a full Catan game with multiple interfaces:
+- Main console for player input and game commands
+- Console visualization for game state display  
+- Web browser interface for interactive board view
+
+The game provides a complete, multi-interface gaming experience.
+"""
+
+import threading
+import time
+import webbrowser
+from typing import List, Optional
+import subprocess
+import sys
+import os
+
+from .game_manager import GameManager
+from .human_user import HumanUser
+from .console_visualization import ConsoleVisualization
+from .web_visualization import WebVisualization
+from .visualization import VisualizationManager
+
+
+class RealGame:
+    """
+    Complete interactive Catan game with multiple interfaces.
+    
+    Features:
+    - Player setup (names, count)
+    - Main game loop with human input
+    - Real-time console visualization
+    - Web browser board display
+    - Coordinated multi-interface experience
+    """
+    
+    def __init__(self):
+        """Initialize the real game manager."""
+        self.num_players = 0
+        self.player_names = []
+        self.users = []
+        self.game_manager = None
+        self.visualization_manager = None
+        self.console_viz = None
+        self.web_viz = None
+        self.web_thread = None
+        self.console_thread = None
+        self.is_running = False
+        
+    def setup_game(self) -> bool:
+        """
+        Interactive setup for the game.
+        Collects number of players and their names.
+        
+        Returns:
+            bool: True if setup successful
+        """
+        print("🎮 Welcome to PyCatan - Interactive Settlers of Catan!")
+        print("=" * 60)
+        
+        # Get number of players
+        while True:
+            try:
+                self.num_players = int(input("How many players? (2-4): "))
+                if 2 <= self.num_players <= 4:
+                    break
+                else:
+                    print("Please enter a number between 2 and 4.")
+            except ValueError:
+                print("Please enter a valid number.")
+        
+        print(f"\nGreat! Setting up a game for {self.num_players} players.")
+        print("=" * 40)
+        
+        # Get player names
+        self.player_names = []
+        for i in range(self.num_players):
+            while True:
+                name = input(f"Enter name for Player {i + 1}: ").strip()
+                if name and len(name) <= 20:
+                    self.player_names.append(name)
+                    break
+                elif not name:
+                    print("Name cannot be empty. Please try again.")
+                else:
+                    print("Name too long (max 20 characters). Please try again.")
+        
+        print(f"\n✅ Players registered: {', '.join(self.player_names)}")
+        
+        # Create user objects
+        self.users = []
+        for i, name in enumerate(self.player_names):
+            user = HumanUser(name, i)
+            self.users.append(user)
+        
+        print("✅ Player objects created successfully!")
+        return True
+    
+    def setup_interfaces(self) -> bool:
+        """
+        Setup all game interfaces (console, web).
+        
+        Returns:
+            bool: True if setup successful
+        """
+        print("\n🖥️  Setting up game interfaces...")
+        print("=" * 40)
+        
+        try:
+            # Define log file for visualization
+            self.viz_log_file = os.path.abspath("game_viz.log")
+            # Clear existing log file
+            with open(self.viz_log_file, 'w', encoding='utf-8') as f:
+                f.write("")
+                
+            # Create console visualization pointing to log file
+            self.console_viz = ConsoleVisualization(
+                use_colors=True,
+                compact_mode=False,
+                output_file=self.viz_log_file
+            )
+            print("✅ Console visualization ready (redirected to separate window)")
+            
+            # Create web visualization  
+            self.web_viz = WebVisualization(
+                port=5000,
+                auto_open=False,  # We'll open manually
+                debug=False
+            )
+            print("✅ Web visualization ready")
+            
+            # Create visualization manager
+            self.visualization_manager = VisualizationManager()
+            self.visualization_manager.add_visualization(self.console_viz)
+            self.visualization_manager.add_visualization(self.web_viz)
+            
+            print("✅ Visualization manager configured")
+            
+            # Open separate console for visualization (Windows only)
+            if os.name == 'nt':  # Windows
+                try:
+                    self._open_visualization_console()
+                    print("✅ Separate visualization console opened")
+                except Exception as e:
+                    print(f"⚠️  Could not open separate console: {e}")
+            
+            return True
+            
+        except Exception as e:
+            print(f"❌ Failed to setup interfaces: {e}")
+            return False
+
+    def _open_visualization_console(self):
+        """Open a separate console window for visualization (Windows only)."""
+        if os.name != 'nt':
+            return  # Only works on Windows
+        
+        # Create a Python script that will run in the new console
+        # This script tails the log file
+        script_content = f'''
+# -*- coding: utf-8 -*-
+import sys
+import time
+import os
+
+log_file = r"{self.viz_log_file}"
+
+print("PyCatan - Game Visualization Console")
+print("=" * 50)
+print("This window shows real-time game state updates.")
+print("Keep this window open while playing!")
+print("=" * 50)
+print(f"Reading from: {{log_file}}")
+
+# Wait for file to exist
+while not os.path.exists(log_file):
+    time.sleep(0.1)
+
+# Tail the file
+with open(log_file, 'r', encoding='utf-8') as f:
+    # Go to the end of file
+    # f.seek(0, 2) 
+    # Actually start from beginning since we just created it
+    
+    while True:
+        line = f.readline()
+        if line:
+            print(line, end='')
+        else:
+            time.sleep(0.1)
+'''
+        
+        # Write the script to a temporary file
+        temp_script = "temp_viz_console.py"
+        with open(temp_script, 'w', encoding='utf-8') as f:
+            f.write(script_content)
+        
+        # Open new console window
+        try:
+            # Use proper path without extra quotes
+            cmd_args = [
+                'cmd', '/k', 
+                f'python {temp_script}'
+            ]
+            subprocess.Popen(cmd_args, creationflags=subprocess.CREATE_NEW_CONSOLE)
+        except Exception as e:
+            print(f"Failed to open console: {e}")
+    
+    def start_game(self) -> bool:
+        """
+        Start the actual game with all interfaces.
+        
+        Returns:
+            bool: True if game started successfully
+        """
+        print("\n🚀 Starting the game...")
+        print("=" * 40)
+        
+        try:
+            # Create users if they don't exist
+            if not self.users:
+                from .human_user import HumanUser
+                self.users = []
+                for i, name in enumerate(self.player_names):
+                    user = HumanUser(name, i)
+                    self.users.append(user)
+                print(f"✅ Created {len(self.users)} user objects")
+            
+            # Create GameManager
+            self.game_manager = GameManager(
+                users=self.users,
+                game_config={"enable_visualizations": True},
+                random_seed=0
+            )
+            
+            # Set up visualizations with GameManager
+            self.game_manager.visualization_manager = self.visualization_manager
+            
+            # Start the game
+            self.game_manager.start_game()
+            print("✅ Game engine started")
+            
+            # Start web server in background thread
+            self.web_thread = threading.Thread(
+                target=self._run_web_server,
+                daemon=True
+            )
+            self.web_thread.start()
+            
+            # Give web server time to start
+            time.sleep(2)
+            
+            # Update web interface with initial game state
+            if self.web_viz:
+                try:
+                    self.web_viz.update_full_state(self.game_manager.get_full_state())
+                    print("✅ Initial web state updated")
+                except Exception as e:
+                    print(f"⚠️  Initial web update failed: {e}")
+            
+            # Open web browser
+            print("🌐 Opening web browser for board view...")
+            webbrowser.open('http://localhost:5000')
+            
+            print("✅ Web interface launched")
+            
+            self.is_running = True
+            return True
+            
+        except Exception as e:
+            print(f"❌ Failed to start game: {e}")
+            return False
+    
+    def _run_web_server(self):
+        """Run the web visualization server in background thread."""
+        try:
+            # Suppress Flask/Werkzeug logs
+            import logging
+            logging.getLogger('werkzeug').setLevel(logging.ERROR)
+            logging.getLogger('flask').setLevel(logging.ERROR)
+            
+            self.web_viz.__enter__()  # Start the server
+            # The server runs in its own event loop
+        except Exception as e:
+            print(f"❌ Web server error: {e}")
+    
+    def _cleanup(self):
+        """Clean up resources when game ends."""
+        print("\n🧹 Cleaning up...")
+        
+        try:
+            # Stop game manager
+            if self.game_manager:
+                self.game_manager.end_game()
+            
+            # Stop web server
+            if self.web_viz:
+                self.web_viz.__exit__(None, None, None)
+            
+            # Clean up temp files
+            if os.name == 'nt':  # Windows
+                try:
+                    if os.path.exists("temp_viz_console.py"):
+                        os.remove("temp_viz_console.py")
+                except:
+                    pass
+                
+            print("✅ Cleanup completed")
+            
+        except Exception as e:
+            print(f"⚠️  Cleanup error: {e}")
+    
+    def run(self):
+        """
+        Run the complete game experience.
+        This is the main entry point for starting a full game.
+        """
+        try:
+            # Step 1: Setup game (players, names)
+            if not self.setup_game():
+                return False
+            
+            # Step 2: Setup interfaces (console, web)
+            if not self.setup_interfaces():
+                return False
+            
+            # Step 3: Start game engine
+            if not self.start_game():
+                return False
+            
+            # Step 4: Play the game (delegate to GameManager)
+            print("\n🎯 Game Started! Control passed to GameManager.")
+            print("=" * 60)
+            print("🔥 Multiple interfaces are now active:")
+            print("   📱 This console - for entering commands")
+            print("   🖥️  Console visualization - for game state display")  
+            print("   🌐 Web browser - for interactive board view")
+            print("=" * 60)
+            
+            try:
+                self.game_manager.game_loop()
+            except KeyboardInterrupt:
+                print("\n\n🛑 Game interrupted by user.")
+            finally:
+                self._cleanup()
+            
+            return True
+            
+        except Exception as e:
+            print(f"❌ Fatal error: {e}")
+            return False
+
+
+def main():
+    """Main entry point for running a complete Catan game."""
+    print("🏴‍☠️ Starting PyCatan Real Game Experience...")
+    
+    real_game = RealGame()
+    success = real_game.run()
+    
+    if success:
+        print("\n🎉 Thanks for playing PyCatan!")
+    else:
+        print("\n😔 Game ended with errors.")
+    
+    print("👋 Goodbye!")
+
+
+if __name__ == "__main__":
+    main()

pycatan/starting_board.json

@@ -0,0 +1,64 @@
+{
+    "hexes": [
+        [
+            "fo",
+            "p",
+            "fi"
+        ],
+        [
+            "h",
+            "m",
+            "h",
+            "p"
+        ],
+        [
+            "d",
+            "fo",
+            "fi",
+            "fo",
+            "fi"
+        ],
+        [
+            "h",
+            "p",
+            "p",
+            "m"
+        ],
+        [
+            "m",
+            "fi",
+            "fo"
+        ]
+    ],
+    "hex_nums": [
+        [
+            11,
+            12,
+            9
+        ],
+        [
+            4,
+            6,
+            5,
+            10
+        ],
+        [
+            null,
+            3,
+            11,
+            4,
+            8
+        ],
+        [
+            8,
+            10,
+            9,
+            3
+        ],
+        [
+            5,
+            2,
+            6
+        ]
+    ]
+}

pycatan/static/css/style.css

@@ -0,0 +1,774 @@
+/* Reset and basic styling */
+* {
+    margin: 0;
+    padding: 0;
+    box-sizing: border-box;
+}
+
+:root {
+    --primary-color: #2c3e50;
+    --secondary-color: #3498db;
+    --success-color: #27ae60;
+    --danger-color: #e74c3c;
+    --warning-color: #f39c12;
+    --accent-color: #9b59b6;
+    --light-bg: #ecf0f1;
+    --border-radius: 12px;
+    --shadow: 0 8px 24px rgba(0,0,0,0.15);
+    --transition: 0.3s cubic-bezier(0.25, 0.46, 0.45, 0.94);
+}
+
+body {
+    font-family: 'Segoe UI', 'Roboto', 'Arial', sans-serif;
+    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+    min-height: 100vh;
+    padding: 0;
+    direction: ltr;
+    overflow: hidden;
+    color: var(--primary-color);
+}
+
+h1 {
+    color: white;
+    text-align: center;
+    margin: 0;
+    font-size: 2.2em;
+    font-weight: 700;
+    text-shadow: 2px 2px 4px rgba(0,0,0,0.2);
+    letter-spacing: 1px;
+}
+
+.subtitle {
+    color: rgba(255,255,255,0.8);
+    font-size: 0.9em;
+    margin: 5px 0 0 0;
+    font-weight: 300;
+}
+
+/* Header */
+.game-header {
+    width: 100%;
+    padding: 20px;
+    background: linear-gradient(135deg, rgba(44, 62, 80, 0.95), rgba(52, 152, 219, 0.9));
+    box-shadow: var(--shadow);
+    border-bottom: 3px solid rgba(255,255,255,0.1);
+}
+
+/* מכולת הלוח */
+.game-container {
+    display: flex;
+    flex-direction: column;
+    width: 100%;
+    height: 100vh;
+}
+
+.content-wrapper {
+    display: flex;
+    flex: 1;
+    gap: 12px;
+    padding: 12px;
+    overflow: hidden;
+}
+
+.board-wrapper {
+    flex: 1;
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    min-width: 0;
+}
+
+.board-container {
+    background: linear-gradient(135deg, #3498db, #5dade2);
+    border: 3px solid rgba(255,255,255,0.2);
+    border-radius: var(--border-radius);
+    padding: 12px;
+    box-shadow: var(--shadow);
+    position: relative;
+    overflow: hidden;
+    cursor: grab;
+    width: 100%;
+    height: 100%;
+    max-width: 1400px;
+}
+
+.board-container:active {
+    cursor: grabbing;
+}
+
+/* כפתורי בקרה */
+.board-controls {
+    position: absolute;
+    top: 12px;
+    right: 12px;
+    z-index: 100;
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+    background: rgba(255,255,255,0.1);
+    padding: 8px;
+    border-radius: 12px;
+    backdrop-filter: blur(10px);
+}
+
+.control-btn {
+    width: 44px;
+    height: 44px;
+    border-radius: 10px;
+    border: 2px solid rgba(255,255,255,0.3);
+    background: linear-gradient(135deg, rgba(255,255,255,0.2), rgba(255,255,255,0.05));
+    color: white;
+    font-size: 18px;
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transition: all var(--transition);
+    box-shadow: 0 4px 12px rgba(0,0,0,0.15);
+    font-weight: 600;
+}
+
+.control-btn:hover {
+    background: linear-gradient(135deg, rgba(255,255,255,0.3), rgba(255,255,255,0.15));
+    transform: translateY(-2px);
+    box-shadow: 0 6px 16px rgba(0,0,0,0.2);
+}
+
+.control-btn:active {
+    transform: translateY(0);
+    box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+}
+
+/* SVG הלוח */
+#catan-board {
+    width: 100%;
+    height: 100%;
+    transition: transform 0.1s ease;
+}
+
+/* Sidebars */
+.sidebar {
+    background: rgba(255, 255, 255, 0.95);
+    border-radius: var(--border-radius);
+    padding: 16px;
+    box-shadow: var(--shadow);
+    backdrop-filter: blur(10px);
+    overflow-y: auto;
+    direction: ltr;
+}
+
+.sidebar-left {
+    width: 300px;
+    flex-shrink: 0;
+}
+
+.sidebar-right {
+    width: 320px;
+    flex-shrink: 0;
+}
+
+/* משושים */
+.hexagon {
+    stroke: #dbc08e;
+    stroke-width: 5;
+    stroke-linejoin: round;
+    vector-effect: non-scaling-stroke;
+    cursor: pointer;
+    transition: all 0.3s ease;
+}
+
+.hexagon:hover {
+    opacity: 0.1;
+}
+
+/* מספרים על משושים */
+.hex-number {
+    font-size: 18px;
+    font-weight: bold;
+    text-anchor: middle;
+    dominant-baseline: middle;
+    fill: #2c3e50;
+    pointer-events: none;
+    text-shadow: 2px 2px 4px rgba(255,255,255,0.8);
+}
+
+.hex-number.red {
+    fill: #e74c3c;
+    font-weight: 900;
+}
+
+/* שודד */
+.robber {
+    fill: #2c3e50;
+    stroke: #34495e;
+    stroke-width: 3;
+    cursor: pointer;
+    filter: drop-shadow(2px 2px 4px rgba(0,0,0,0.5));
+    transition: opacity 0.3s ease;
+}
+
+.robber:hover {
+    opacity: 0.1;
+}
+
+.robber-text {
+    font-size: 16px;
+    font-weight: bold;
+    text-anchor: middle;
+    dominant-baseline: middle;
+    fill: white;
+    pointer-events: none;
+}
+
+/* יישובים */
+.settlement {
+    stroke: #2c3e50;
+    stroke-width: 2;
+    cursor: pointer;
+    filter: drop-shadow(1px 1px 2px rgba(0,0,0,0.3));
+    transition: opacity 0.3s ease;
+}
+
+.settlement:hover {
+    opacity: 0.1;
+}
+
+.settlement.player1 { fill: #FF4444; }
+.settlement.player2 { fill: #4444FF; }
+.settlement.player3 { fill: #44FF44; }
+.settlement.player4 { fill: #FFAA00; }
+
+/* ערים */
+.city {
+    stroke: #2c3e50;
+    stroke-width: 3;
+    cursor: pointer;
+    filter: drop-shadow(2px 2px 3px rgba(0,0,0,0.3));
+    transition: opacity 0.3s ease;
+}
+
+.city:hover {
+    opacity: 0.1;
+}
+
+.city.player1 { fill: #FF4444; }
+.city.player2 { fill: #4444FF; }
+.city.player3 { fill: #44FF44; }
+.city.player4 { fill: #FFAA00; }
+
+/* דרכים */
+.road {
+    stroke-width: 6;
+    stroke-linecap: round;
+    cursor: pointer;
+    transition: all 0.3s ease;
+    filter: drop-shadow(1px 1px 2px rgba(0,0,0,0.3));
+}
+
+.road:hover {
+    opacity: 0.1;
+}
+
+.road.player1 { stroke: #FF4444; }
+.road.player2 { stroke: #4444FF; }
+.road.player3 { stroke: #44FF44; }
+.road.player4 { stroke: #FFAA00; }
+
+/* קודקודים */
+.vertex {
+    fill: #e74c3c;
+    stroke: #ffffff;
+    stroke-width: 3;
+    opacity: 0;
+    transition: opacity 0.3s ease;
+    cursor: pointer;
+}
+
+.vertex:hover {
+    opacity: 0.1;
+}
+
+.vertices-visible .vertex {
+    opacity: 0.9;
+}
+
+.vertex-number {
+    font-size: 14px;
+    font-weight: 900;
+    text-anchor: middle;
+    dominant-baseline: middle;
+    fill: white;
+    pointer-events: none;
+    opacity: 0;
+    transition: opacity 0.3s ease;
+    text-shadow: 
+        -1px -1px 0 #000,  
+        1px -1px 0 #000,
+        -1px 1px 0 #000,
+        1px 1px 0 #000;
+}
+
+.vertices-visible .vertex-number {
+    opacity: 1;
+}
+
+/* רספונסיביות */
+@media (max-width: 1400px) {
+    .sidebar-left,
+    .sidebar-right {
+        width: 280px;
+    }
+}
+
+@media (max-width: 1200px) {
+    .content-wrapper {
+        gap: 8px;
+    }
+    
+    .sidebar-left,
+    .sidebar-right {
+        width: 260px;
+    }
+}
+
+@media (max-width: 1024px) {
+    .content-wrapper {
+        flex-wrap: wrap;
+    }
+    
+    .sidebar-left,
+    .sidebar-right {
+        width: 100%;
+        max-height: 30vh;
+    }
+    
+    .board-wrapper {
+        width: 100%;
+        min-height: 50vh;
+    }
+}
+
+@media (max-width: 768px) {
+    .game-header {
+        padding: 15px;
+    }
+    
+    h1 {
+        font-size: 1.8em;
+    }
+    
+    .subtitle {
+        font-size: 0.8em;
+    }
+    
+    .content-wrapper {
+        padding: 8px;
+    }
+    
+    .sidebar-left,
+    .sidebar-right {
+        width: 100%;
+        max-height: 25vh;
+    }
+    
+    .board-wrapper {
+        width: 100%;
+        min-height: 60vh;
+    }
+    
+    .board-controls {
+        top: 8px;
+        right: 8px;
+        flex-direction: row;
+        gap: 6px;
+    }
+    
+    .control-btn {
+        width: 40px;
+        height: 40px;
+        font-size: 16px;
+    }
+}
+
+@media (max-width: 480px) {
+    body {
+        padding: 0;
+    }
+    
+    .game-header {
+        padding: 12px;
+    }
+    
+    h1 {
+        font-size: 1.4em;
+    }
+    
+    .subtitle {
+        font-size: 0.7em;
+    }
+    
+    .sidebar-left,
+    .sidebar-right {
+        max-height: 20vh;
+    }
+    
+    .game-info,
+    .action-log {
+        font-size: 0.8em;
+    }
+}
+
+/* Game Info */
+.game-info {
+    display: flex;
+    flex-direction: column;
+    gap: 10px;
+}
+
+.game-info h3 {
+    margin: 0;
+    color: var(--primary-color);
+    font-size: 1.1em;
+    border-bottom: 2px solid var(--secondary-color);
+    padding-bottom: 8px;
+}
+
+.game-info .loading {
+    text-align: center;
+    color: var(--secondary-color);
+    padding: 20px;
+    font-style: italic;
+}
+
+.player-info {
+    margin-bottom: 8px;
+    padding: 10px 12px;
+    border-radius: 8px;
+    border-left: 4px solid transparent;
+    background: var(--light-bg);
+    cursor: pointer;
+    transition: all var(--transition);
+}
+
+.player-info:hover {
+    background: rgba(52, 152, 219, 0.15);
+    transform: translateX(-4px);
+}
+
+.player-info.active {
+    border-left-color: var(--secondary-color);
+    background: rgba(52, 152, 219, 0.2);
+    font-weight: 600;
+}
+
+.player-info h4 {
+    margin: 0 0 6px 0;
+    font-size: 0.95em;
+    color: var(--primary-color);
+}
+
+.player-resources {
+    font-size: 0.85em;
+    color: #555;
+    line-height: 1.4;
+    margin: 4px 0;
+}
+
+.log-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: 12px;
+}
+
+.log-header h3 {
+    margin: 0;
+    color: var(--primary-color);
+    font-size: 1.1em;
+    border-bottom: 2px solid var(--secondary-color);
+    padding-bottom: 8px;
+    flex: 1;
+}
+
+.clear-log-btn {
+    background: var(--light-bg);
+    border: none;
+    padding: 6px 10px;
+    border-radius: 6px;
+    cursor: pointer;
+    font-size: 0.9em;
+    transition: all var(--transition);
+}
+
+.clear-log-btn:hover {
+    background: var(--danger-color);
+    color: white;
+}
+
+.action-log {
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
+    font-family: 'Consolas', 'Monaco', monospace;
+    font-size: 0.85em;
+    direction: ltr;
+    max-height: calc(100vh - 180px);
+    overflow-y: auto;
+}
+
+.action-log::-webkit-scrollbar {
+    width: 6px;
+}
+
+.action-log::-webkit-scrollbar-track {
+    background: rgba(0,0,0,0.05);
+    border-radius: 3px;
+}
+
+.action-log::-webkit-scrollbar-thumb {
+    background: rgba(0,0,0,0.2);
+    border-radius: 3px;
+}
+
+.action-log::-webkit-scrollbar-thumb:hover {
+    background: rgba(0,0,0,0.3);
+}
+
+.action-log div {
+    margin: 0;
+    padding: 8px 10px;
+    border-radius: 6px;
+    border-left: 4px solid var(--secondary-color);
+    background: rgba(52, 152, 219, 0.1);
+    line-height: 1.3;
+    word-break: break-word;
+}
+
+.action-log .success {
+    color: var(--success-color);
+    border-left-color: var(--success-color);
+    background: rgba(39, 174, 96, 0.1);
+}
+
+.action-log .error {
+    color: var(--danger-color);
+    border-left-color: var(--danger-color);
+    background: rgba(231, 76, 60, 0.1);
+    font-weight: 500;
+}
+
+.action-log .info {
+    color: var(--secondary-color);
+    border-left-color: var(--secondary-color);
+    background: rgba(52, 152, 219, 0.1);
+}
+
+.action-log .log-dice {
+    color: var(--warning-color);
+    border-left-color: var(--warning-color);
+    background: rgba(243, 156, 18, 0.1);
+    font-weight: 600;
+}
+
+.action-log .log-turn {
+    color: white;
+    background: linear-gradient(90deg, var(--secondary-color), var(--accent-color));
+    border: none;
+    text-align: center;
+    font-weight: 700;
+    padding: 10px;
+    font-size: 0.9em;
+    border-radius: 8px;
+    box-shadow: 0 2px 8px rgba(52, 152, 219, 0.3);
+}
+
+.action-log .log-resource {
+    color: var(--accent-color);
+    border-left-color: var(--accent-color);
+    background: rgba(155, 89, 182, 0.1);
+    font-style: italic;
+}
+
+.action-log .log-build {
+    color: var(--success-color);
+    border-left-color: var(--success-color);
+    background: rgba(39, 174, 96, 0.1);
+    font-weight: 600;
+}
+
+/* Player Cards Display */
+.player-cards {
+    display: none;
+    margin-top: 8px;
+    padding: 8px;
+    background: white;
+    border-radius: 6px;
+    border: 1px solid rgba(52, 152, 219, 0.2);
+    animation: slideDown var(--transition);
+}
+
+.player-info.expanded .player-cards {
+    display: block;
+}
+
+@keyframes slideDown {
+    from {
+        opacity: 0;
+        transform: translateY(-8px);
+    }
+    to {
+        opacity: 1;
+        transform: translateY(0);
+    }
+}
+
+.player-cards div {
+    margin-bottom: 6px;
+}
+
+.player-cards strong {
+    color: var(--primary-color);
+    font-size: 0.85em;
+}
+
+.card-list {
+    list-style: none;
+    padding: 0;
+    margin: 4px 0 0 0;
+    font-size: 0.8em;
+    display: flex;
+    flex-wrap: wrap;
+    gap: 4px;
+}
+
+.card-list li {
+    display: inline-block;
+    padding: 4px 8px;
+    background: linear-gradient(135deg, var(--secondary-color), var(--secondary-color));
+    color: white;
+    border-radius: 4px;
+    border: 1px solid rgba(52, 152, 219, 0.3);
+    font-weight: 500;
+    white-space: nowrap;
+    transition: all var(--transition);
+}
+
+.card-list li:hover {
+    transform: translateY(-2px);
+    box-shadow: 0 3px 8px rgba(52, 152, 219, 0.3);
+}
+
+/* Modal for Building Costs */
+.modal {
+    position: fixed;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    background: rgba(0, 0, 0, 0.5);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    z-index: 1000;
+    backdrop-filter: blur(4px);
+    animation: fadeIn var(--transition);
+}
+
+.modal.hidden {
+    display: none;
+}
+
+@keyframes fadeIn {
+    from {
+        opacity: 0;
+    }
+    to {
+        opacity: 1;
+    }
+}
+
+.modal-content {
+    background: white;
+    border-radius: var(--border-radius);
+    box-shadow: var(--shadow);
+    max-width: 500px;
+    width: 90%;
+    max-height: 80vh;
+    overflow-y: auto;
+    animation: slideUp var(--transition);
+}
+
+@keyframes slideUp {
+    from {
+        transform: translateY(30px);
+        opacity: 0;
+    }
+    to {
+        transform: translateY(0);
+        opacity: 1;
+    }
+}
+
+.modal-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    padding: 20px;
+    border-bottom: 2px solid var(--secondary-color);
+}
+
+.modal-header h3 {
+    margin: 0;
+    color: var(--primary-color);
+    font-size: 1.3em;
+}
+
+.modal-close {
+    background: none;
+    border: none;
+    font-size: 24px;
+    cursor: pointer;
+    color: var(--danger-color);
+    transition: all var(--transition);
+}
+
+.modal-close:hover {
+    transform: scale(1.2);
+}
+
+.modal-body {
+    padding: 20px;
+}
+
+.costs-table {
+    width: 100%;
+    border-collapse: collapse;
+    margin-bottom: 16px;
+}
+
+.costs-table thead {
+    background: linear-gradient(135deg, var(--secondary-color), var(--accent-color));
+    color: white;
+}
+
+.costs-table th {
+    padding: 12px;
+    text-align: left;
+    font-weight: 600;
+}
+
+.costs-table td {
+    padding: 12px;
+    border-bottom: 1px solid var(--light-bg);
+}
+
+.costs-table tbody tr:hover {
+    background: rgba(52, 152, 219, 0.1);
+}
+
+.costs-note {
+    font-size: 0.85em;
+    color: #666;
+    font-style: italic;
+    margin: 0;
+}

pycatan/static/js/board.js

@@ -0,0 +1,763 @@
+// CatanBoard class for managing the game board visualization
+class CatanBoard {
+    constructor() {
+        this.svg = document.getElementById('catan-board');
+        this.hexRadius = 45;
+        this.centerX = 400;
+        this.centerY = 300;
+        
+        this.zoomLevel = 1;
+        this.panX = 0;
+        this.panY = 0;
+        this.isDragging = false;
+        this.lastMouseX = 0;
+        this.lastMouseY = 0;
+        this.showVertices = true;
+        
+        // Board mapping from server
+        this.boardMapping = null;
+        this.vertices = [];
+        
+        this.init();
+    }
+    
+    async init() {
+        this.setupEventListeners();
+        // Load board mapping from server
+        await this.loadBoardMapping();
+        
+        if (this.boardMapping && this.boardMapping.points) {
+            console.log("Using server-provided board mapping for vertices");
+            this.generateVerticesFromServer();
+        } else {
+            // Generate vertices derived directly from hex geometry
+            // This ensures perfect visual alignment
+            this.generateVerticesFromHexes();
+        }
+        
+        this.createBoard();
+    }
+    
+    async loadBoardMapping() {
+        try {
+            const response = await fetch('/api/board_mapping');
+            this.boardMapping = await response.json();
+            console.log('Board mapping loaded from server:', this.boardMapping);
+        } catch (error) {
+            console.error('Failed to load board mapping:', error);
+            // Fallback to default if server fails
+            this.boardMapping = null;
+        }
+    }
+    
+    setupEventListeners() {
+        // Zoom and pan events
+        this.svg.addEventListener('wheel', (e) => this.handleZoom(e));
+        this.svg.addEventListener('mousedown', (e) => this.startDrag(e));
+        this.svg.addEventListener('mousemove', (e) => this.handleDrag(e));
+        this.svg.addEventListener('mouseup', () => this.endDrag());
+        this.svg.addEventListener('mouseleave', () => this.endDrag());
+    }
+    
+    // Convert hex coordinates to pixels
+    hexToPixel(q, r) {
+        const x = this.hexRadius * (3/2 * q);
+        const y = this.hexRadius * (Math.sqrt(3)/2 * q + Math.sqrt(3) * r);
+        return {
+            x: this.centerX + x,
+            y: this.centerY + y
+        };
+    }
+    
+    // Get hexagon vertices
+    getHexagonVertices(q, r) {
+        const center = this.hexToPixel(q, r);
+        const vertices = [];
+        
+        for (let i = 0; i < 6; i++) {
+            const angle = (Math.PI / 3) * i;
+            const x = center.x + this.hexRadius * Math.cos(angle);
+            const y = center.y + this.hexRadius * Math.sin(angle);
+            vertices.push({x: x, y: y});
+        }
+        
+        return vertices;
+    }
+    
+    generateVerticesFromHexes() {
+        console.log('Generating vertices derived from hex geometry...');
+        this.vertices = [];
+        const uniqueVerticesMap = new Map(); // To prevent duplicates
+        
+        // Get hex data (from game state, board mapping, or default)
+        let hexes;
+        if (this.currentGameState && this.currentGameState.hexes && this.currentGameState.hexes.length > 0) {
+            hexes = this.currentGameState.hexes;
+        } else if (this.boardMapping && this.boardMapping.hexes) {
+            hexes = this.boardMapping.hexes;
+        } else {
+            hexes = GAMEDATA.hexes;
+        }
+
+        hexes.forEach(hex => {
+            // Get the 6 corners of the current hex
+            const corners = this.getHexagonVertices(hex.q, hex.r);
+            
+            corners.forEach(corner => {
+                // Create unique key based on position (rounded to handle floating point)
+                const keyX = Math.round(corner.x); 
+                const keyY = Math.round(corner.y);
+                const key = `${keyX},${keyY}`;
+                
+                if (!uniqueVerticesMap.has(key)) {
+                    uniqueVerticesMap.set(key, {
+                        x: corner.x,
+                        y: corner.y,
+                        adjacent_hexes: [hex.id]
+                    });
+                } else {
+                    // If point exists, add hex to its adjacent list
+                    const entry = uniqueVerticesMap.get(key);
+                    if (!entry.adjacent_hexes.includes(hex.id)) {
+                        entry.adjacent_hexes.push(hex.id);
+                    }
+                }
+            });
+        });
+
+        // Convert map to array
+        let tempVertices = Array.from(uniqueVerticesMap.values());
+        
+        // Sort: First by Y (rows), then by X (columns)
+        // This attempts to match the server's ID generation order (row by row, left to right)
+        tempVertices.sort((a, b) => {
+            // Use a tolerance for Y comparison to group vertices into rows
+            if (Math.abs(a.y - b.y) > 10) return a.y - b.y; 
+            return a.x - b.x;
+        });
+
+        // Create final structure with IDs
+        this.vertices = tempVertices.map((v, index) => ({
+            id: index + 1, // Renumber 1-54
+            x: v.x,
+            y: v.y,
+            game_coords: [], // Not critical for display
+            adjacent_points: [], // Will be calculated if needed
+            adjacent_hexes: v.adjacent_hexes,
+            buildings: []
+        }));
+
+        console.log(`Generated ${this.vertices.length} vertices aligned to hex corners`);
+    }
+
+    generateVerticesFromServer() {
+        // Generate vertices using the server-provided board mapping
+        if (!this.boardMapping || !this.boardMapping.points) {
+            console.error('No board mapping available from server, using fallback');
+            // Create a fallback basic vertex layout
+            this.generateFallbackVertices();
+            return;
+        }
+        
+        this.vertices = [];
+        
+        // Use the server-provided point data
+        for (const pointData of this.boardMapping.points) {
+            const vertex = {
+                id: pointData.id,           // Point ID (1-54)
+                x: pointData.x,             // Pixel coordinates from server
+                y: pointData.y,
+                game_coords: pointData.game_coords,  // [row, col] for debugging
+                adjacent_points: pointData.adjacent_points || [],
+                adjacent_hexes: pointData.adjacent_hexes || [],
+                buildings: []  // Will be populated when buildings are added
+            };
+            
+            this.vertices.push(vertex);
+        }
+        
+        console.log(`Generated ${this.vertices.length} vertices from server data`);
+    }
+    
+    generateFallbackVertices() {
+        // Generate basic vertices when server mapping is not available
+        console.log('Using fallback vertex generation');
+        this.vertices = [];
+        
+        // Create a basic grid of vertices for testing
+        let vertexId = 1;
+        const rows = [7, 9, 11, 11, 9, 7]; // Standard Catan point distribution
+        
+        for (let row = 0; row < rows.length; row++) {
+            const rowWidth = rows[row];
+            for (let col = 0; col < rowWidth; col++) {
+                // Simple grid positioning
+                const offsetX = -(rowWidth - 1) * this.hexRadius * 0.5 * 0.75;
+                const x = this.centerX + offsetX + col * this.hexRadius * 0.75;
+                const y = this.centerY + (row - 2.5) * this.hexRadius * 0.866;
+                
+                this.vertices.push({
+                    id: vertexId,
+                    x: x,
+                    y: y,
+                    game_coords: [row, col],
+                    adjacent_points: [],
+                    adjacent_hexes: [],
+                    buildings: []
+                });
+                
+                vertexId++;
+            }
+        }
+        
+        console.log(`Generated ${this.vertices.length} fallback vertices`);
+    }
+    
+    // Get vertex by point ID
+    getVertexByPointId(pointId) {
+        return this.vertices.find(v => v.id === pointId);
+    }
+    
+    // Get vertex by coordinates (for backward compatibility)
+    getVertexByCoords(x, y, tolerance = 20) {
+        return this.vertices.find(v => {
+            const dx = v.x - x;
+            const dy = v.y - y;
+            return Math.sqrt(dx * dx + dy * dy) < tolerance;
+        });
+    }
+            
+    createBoard() {
+        // Create the game board with hexes and vertices
+        console.log('Creating game board...');
+        
+        // Clear any existing content
+        this.svg.innerHTML = '';
+        
+        // Create hexes first (either from server data or fallback)
+        this.createHexes();
+        
+        // Create vertices
+        this.createVertices();
+        
+        // Set initial transform
+        this.updateTransform();
+        
+        console.log('Game board created successfully');
+    }
+    
+    createHexes() {
+        // Create hexes on the board
+        // Use server data if available, otherwise fallback to GAMEDATA
+        let hexData;
+        if (this.currentGameState && this.currentGameState.hexes && this.currentGameState.hexes.length > 0) {
+            hexData = this.currentGameState.hexes;
+            console.log('Using hexes from game state');
+        } else if (this.boardMapping && this.boardMapping.hexes) {
+            hexData = this.boardMapping.hexes;
+            console.log('Using hexes from board mapping');
+        } else {
+            hexData = GAMEDATA.hexes;
+            console.log('Using fallback hex data from GAMEDATA');
+        }
+        
+        hexData.forEach(hex => {
+            this.createHex(hex);
+        });
+    }
+    
+    createBoard() {
+        // Clear existing content
+        this.svg.innerHTML = '';
+        
+        // Determine which hex data to use
+        let hexData;
+        if (this.currentGameState && this.currentGameState.hexes && this.currentGameState.hexes.length > 0) {
+            hexData = this.currentGameState.hexes;
+            console.log(`Using server hexes: ${hexData.length} hexes`);
+        } else {
+            hexData = GAMEDATA.hexes;
+            console.log(`Using default GAMEDATA hexes: ${hexData.length} hexes`);
+        }
+        
+        // Create hexes
+        hexData.forEach(hex => {
+            this.createHex(hex);
+        });
+        
+        // Create vertices
+        this.createVertices();
+        
+        // Create buildings only if we don't have current game state
+        // (when called directly, not from updateFromGameState)
+        if (!this.currentGameState) {
+            // Create settlements from GAMEDATA (fallback)
+            GAMEDATA.settlements.forEach(settlement => {
+                this.createSettlement(settlement);
+            });
+
+            // Create cities from GAMEDATA (fallback)
+            GAMEDATA.cities.forEach(city => {
+                this.createCity(city);
+            });
+
+            // Create roads from GAMEDATA (fallback)
+            GAMEDATA.roads.forEach(road => {
+                this.createRoad(road);
+            });
+        }
+        
+        this.updateTransform();
+    }
+    
+    createHex(hex) {
+        const vertices = this.getHexagonVertices(hex.q, hex.r);
+        const center = this.hexToPixel(hex.q, hex.r);
+        
+        // Calculate bounding rectangle for the hex
+        const minX = Math.min(...vertices.map(v => v.x));
+        const maxX = Math.max(...vertices.map(v => v.x));
+        const minY = Math.min(...vertices.map(v => v.y));
+        const maxY = Math.max(...vertices.map(v => v.y));
+        
+        // Create group for hex
+        const hexGroup = document.createElementNS('http://www.w3.org/2000/svg', 'g');
+        
+        // Create clipPath for hex
+        const clipPath = document.createElementNS('http://www.w3.org/2000/svg', 'clipPath');
+        clipPath.setAttribute('id', `clip-${hex.id}`);
+        
+        const pathData = vertices.map((vertex, index) => {
+            const command = index === 0 ? 'M' : 'L';
+            return `${command} ${vertex.x.toFixed(2)} ${vertex.y.toFixed(2)}`;
+        }).join(' ') + ' Z';
+        
+        const clipPathElement = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+        clipPathElement.setAttribute('d', pathData);
+        clipPath.appendChild(clipPathElement);
+        
+        // Add clipPath to defs
+        let defs = this.svg.querySelector('defs');
+        if (!defs) {
+            defs = document.createElementNS('http://www.w3.org/2000/svg', 'defs');
+            this.svg.appendChild(defs);
+        }
+        defs.appendChild(clipPath);
+        
+        // Create image that fills the hex
+        const image = document.createElementNS('http://www.w3.org/2000/svg', 'image');
+        image.setAttribute('href', `static/images/${RESOURCE_FILES[hex.type]}`);
+        image.setAttribute('x', minX);
+        image.setAttribute('y', minY);
+        image.setAttribute('width', maxX - minX);
+        image.setAttribute('height', maxY - minY);
+        image.setAttribute('preserveAspectRatio', 'xMidYMid slice');
+        image.setAttribute('clip-path', `url(#clip-${hex.id})`);
+        
+        hexGroup.appendChild(image);
+        
+        // Create hex element (for borders only)
+        const pathElement = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+        pathElement.setAttribute('d', pathData);
+        pathElement.setAttribute('class', `hexagon hex-${hex.type}`);
+        pathElement.setAttribute('data-hex-id', hex.id);
+        pathElement.style.fill = 'transparent';
+        
+        hexGroup.appendChild(pathElement);
+        this.svg.appendChild(hexGroup);
+        
+        // Add hex number (if not desert)
+        if (hex.number !== null) {
+            const numberElement = document.createElementNS('http://www.w3.org/2000/svg', 'text');
+            numberElement.setAttribute('x', center.x);
+            numberElement.setAttribute('y', center.y);
+            numberElement.textContent = hex.number;
+            numberElement.setAttribute('class', hex.number === 6 || hex.number === 8 ? 'hex-number red' : 'hex-number');
+            this.svg.appendChild(numberElement);
+        }
+        
+        // Add robber if present
+        if (hex.robber) {
+            this.createRobber(center.x, center.y, hex.id);
+        }
+    }
+    
+    createRobber(x, y, hexId) {
+        // Create robber group
+        const robberGroup = document.createElementNS('http://www.w3.org/2000/svg', 'g');
+        robberGroup.setAttribute('class', 'robber');
+        robberGroup.setAttribute('data-hex-id', hexId);
+        
+        // Create robber circle
+        const circle = document.createElementNS('http://www.w3.org/2000/svg', 'circle');
+        circle.setAttribute('cx', x);
+        circle.setAttribute('cy', y);
+        circle.setAttribute('r', 18);
+        
+        // Create robber text
+        const text = document.createElementNS('http://www.w3.org/2000/svg', 'text');
+        text.setAttribute('x', x);
+        text.setAttribute('y', y);
+        text.textContent = 'R';
+        text.setAttribute('class', 'robber-text');
+        
+        robberGroup.appendChild(circle);
+        robberGroup.appendChild(text);
+        this.svg.appendChild(robberGroup);
+    }
+    
+    createVertices() {
+        // Create vertices group
+        const verticesGroup = document.createElementNS('http://www.w3.org/2000/svg', 'g');
+        verticesGroup.setAttribute('id', 'vertices');
+        if (this.showVertices) {
+            verticesGroup.classList.add('vertices-visible');
+        }
+        
+        this.vertices.forEach(vertex => {
+            // Create vertex circle
+            const circle = document.createElementNS('http://www.w3.org/2000/svg', 'circle');
+            circle.setAttribute('cx', vertex.x);
+            circle.setAttribute('cy', vertex.y);
+            circle.setAttribute('r', 8);
+            circle.setAttribute('class', 'vertex');
+            circle.setAttribute('data-vertex-id', vertex.id);
+            
+            // Create vertex number text
+            const text = document.createElementNS('http://www.w3.org/2000/svg', 'text');
+            text.setAttribute('x', vertex.x);
+            text.setAttribute('y', vertex.y);
+            text.textContent = vertex.id;
+            text.setAttribute('class', 'vertex-number');
+            
+            verticesGroup.appendChild(circle);
+            verticesGroup.appendChild(text);
+        });
+        
+        this.svg.appendChild(verticesGroup);
+    }
+    
+    createSettlement(settlement) {
+        // Find vertex by ID (handle both string and number IDs)
+        const vertexId = parseInt(settlement.vertex);
+        const vertex = this.vertices.find(v => v.id === vertexId);
+        
+        if (!vertex) {
+            console.warn(`Could not find vertex ${settlement.vertex} for settlement`);
+            return;
+        }
+        
+        // Create settlement polygon (house shape)
+        const polygon = document.createElementNS('http://www.w3.org/2000/svg', 'polygon');
+        const points = [
+            [vertex.x, vertex.y - 12],      // top
+            [vertex.x - 8, vertex.y - 4],   // top-left
+            [vertex.x - 8, vertex.y + 8],   // bottom-left
+            [vertex.x + 8, vertex.y + 8],   // bottom-right
+            [vertex.x + 8, vertex.y - 4]    // top-right
+        ].map(p => p.join(',')).join(' ');
+        
+        polygon.setAttribute('points', points);
+        polygon.setAttribute('class', `settlement player${settlement.player}`);
+        polygon.setAttribute('data-settlement-id', settlement.id);
+        polygon.setAttribute('data-vertex-id', settlement.vertex);
+        
+        this.svg.appendChild(polygon);
+    }
+    
+    createCity(city) {
+        // Find vertex by ID (handle both string and number IDs)
+        const vertexId = parseInt(city.vertex);
+        const vertex = this.vertices.find(v => v.id === vertexId);
+        
+        if (!vertex) {
+            console.warn(`Could not find vertex ${city.vertex} for city`);
+            return;
+        }
+        
+        // Create city polygon (larger building)
+        const polygon = document.createElementNS('http://www.w3.org/2000/svg', 'polygon');
+        const points = [
+            [vertex.x, vertex.y - 16],       // top
+            [vertex.x - 12, vertex.y - 8],   // top-left
+            [vertex.x - 12, vertex.y + 12],  // bottom-left
+            [vertex.x + 12, vertex.y + 12],  // bottom-right
+            [vertex.x + 12, vertex.y - 8]    // top-right
+        ].map(p => p.join(',')).join(' ');
+        
+        polygon.setAttribute('points', points);
+        polygon.setAttribute('class', `city player${city.player}`);
+        polygon.setAttribute('data-city-id', city.id);
+        polygon.setAttribute('data-vertex-id', city.vertex);
+        
+        this.svg.appendChild(polygon);
+    }
+    
+    createRoad(road) {
+        // Find vertices by ID (handle both string and number IDs)
+        const fromId = parseInt(road.from);
+        const toId = parseInt(road.to);
+        
+        const fromVertex = this.vertices.find(v => v.id === fromId);
+        const toVertex = this.vertices.find(v => v.id === toId);
+        
+        if (!fromVertex || !toVertex) {
+            console.warn(`Could not find vertices ${road.from}->${road.to} for road`);
+            return;
+        }
+        
+        // Create road line
+        const line = document.createElementNS('http://www.w3.org/2000/svg', 'line');
+        line.setAttribute('x1', fromVertex.x);
+        line.setAttribute('y1', fromVertex.y);
+        line.setAttribute('x2', toVertex.x);
+        line.setAttribute('y2', toVertex.y);
+        line.setAttribute('class', `road player${road.player}`);
+        line.setAttribute('data-road-id', road.id);
+        line.setAttribute('data-from-vertex', road.from);
+        line.setAttribute('data-to-vertex', road.to);
+        
+        this.svg.appendChild(line);
+    }
+    
+    // Update board from game state (called when receiving updates from server)
+    updateFromGameState(gameState) {
+        console.log('Updating board from game state:', gameState);
+        
+        // Store the current game state
+        this.currentGameState = gameState;
+        
+        // Don't regenerate vertices - they're already loaded from server in init()
+        // this.generateVertices(); // <- This function doesn't exist!
+        
+        // Clear and rebuild board with new data (but not buildings)
+        this.svg.innerHTML = '';
+        
+        // Create hexes from game state
+        if (gameState.hexes && gameState.hexes.length > 0) {
+            console.log(`Creating ${gameState.hexes.length} hexes from server data`);
+            gameState.hexes.forEach(hex => {
+                this.createHex(hex);
+            });
+        }
+        
+        // Create vertices
+        this.createVertices();
+        
+        // Add buildings from server data
+        this.updateBuildings(gameState);
+        this.updateRobberFromGameState(gameState);
+        
+        // Update transform
+        this.updateTransform();
+    }
+    
+    updateBuildings(gameState) {
+        // Remove existing buildings
+        const existingBuildings = this.svg.querySelectorAll('.settlement, .city, .road');
+        existingBuildings.forEach(building => building.remove());
+        
+        // Add settlements from server data
+        if (gameState.settlements && gameState.settlements.length > 0) {
+            console.log('Adding settlements:', gameState.settlements);
+            gameState.settlements.forEach(settlement => {
+                this.createSettlement(settlement);
+            });
+        }
+        
+        // Add cities from server data
+        if (gameState.cities && gameState.cities.length > 0) {
+            console.log('Adding cities:', gameState.cities);
+            gameState.cities.forEach(city => {
+                this.createCity(city);
+            });
+        }
+        
+        // Add roads from server data
+        if (gameState.roads && gameState.roads.length > 0) {
+            console.log('Adding roads:', gameState.roads);
+            gameState.roads.forEach(road => {
+                this.createRoad(road);
+            });
+        }
+    }
+    
+    updateRobberFromGameState(gameState) {
+        // Remove existing robber
+        const existingRobber = this.svg.querySelector('.robber');
+        if (existingRobber) {
+            existingRobber.remove();
+        }
+        
+        // Add robber from server data
+        if (gameState.robber_position) {
+            // Find hex with robber position
+            const robberHex = gameState.hexes ? 
+                gameState.hexes.find(h => h.robber === true) : null;
+                
+            if (robberHex) {
+                const center = this.hexToPixel(robberHex.q, robberHex.r);
+                this.createRobber(center.x, center.y, robberHex.id);
+                console.log('Robber placed at hex:', robberHex.id);
+            }
+        }
+    }
+    
+    updateRobberPosition(newPosition) {
+        // Remove existing robber
+        const existingRobber = this.svg.querySelector('.robber');
+        if (existingRobber) {
+            existingRobber.remove();
+        }
+        
+        // Add robber to new position
+        const hex = GAMEDATA.hexes.find(h => h.id === newPosition);
+        if (hex) {
+            const center = this.hexToPixel(hex.q, hex.r);
+            this.createRobber(center.x, center.y, hex.id);
+        }
+    }
+    
+    // Zoom and pan functionality
+    handleZoom(e) {
+        e.preventDefault();
+        const delta = e.deltaY > 0 ? 0.9 : 1.1;
+        this.zoomLevel = Math.max(0.5, Math.min(3, this.zoomLevel * delta));
+        this.updateTransform();
+    }
+    
+    startDrag(e) {
+        this.isDragging = true;
+        this.lastMouseX = e.clientX;
+        this.lastMouseY = e.clientY;
+    }
+    
+    handleDrag(e) {
+        if (!this.isDragging) return;
+        
+        const deltaX = e.clientX - this.lastMouseX;
+        const deltaY = e.clientY - this.lastMouseY;
+        
+        this.panX += deltaX;
+        this.panY += deltaY;
+        
+        this.lastMouseX = e.clientX;
+        this.lastMouseY = e.clientY;
+        
+        this.updateTransform();
+    }
+    
+    endDrag() {
+        this.isDragging = false;
+    }
+    
+    updateTransform() {
+        this.svg.style.transform = `translate(${this.panX}px, ${this.panY}px) scale(${this.zoomLevel})`;
+    }
+    
+    // Control functions
+    zoomIn() {
+        this.zoomLevel = Math.min(3, this.zoomLevel * 1.2);
+        this.updateTransform();
+    }
+    
+    zoomOut() {
+        this.zoomLevel = Math.max(0.5, this.zoomLevel * 0.8);
+        this.updateTransform();
+    }
+    
+    resetZoom() {
+        this.zoomLevel = 1;
+        this.panX = 0;
+        this.panY = 0;
+        this.updateTransform();
+    }
+    
+    toggleVertices() {
+        this.showVertices = !this.showVertices;
+        const verticesGroup = this.svg.querySelector('#vertices');
+        if (verticesGroup) {
+            if (this.showVertices) {
+                verticesGroup.classList.add('vertices-visible');
+            } else {
+                verticesGroup.classList.remove('vertices-visible');
+            }
+        }
+        
+        // Update button text
+        const button = document.getElementById('toggleVertices');
+        if (button) {
+            button.textContent = this.showVertices ? '🔍' : '📍';
+        }
+    }
+    
+    // עדכון vertex IDs בהתבסס על מיפוי אמיתי מהשרת
+    updateVertexIDsFromMapping() {
+        if (!window.pointMapping || !this.vertices) {
+            console.warn('⚠️ לא ניתן לעדכן vertex IDs - חסר מיפוי או vertices');
+            return;
+        }
+        
+        console.log('🔄 מעדכן vertex IDs לפי המיפוי האמיתי...');
+        
+        // עבור על כל vertex ובדוק אם יש לו מיפוי מתאים
+        this.vertices.forEach((vertex, index) => {
+            // נסה למצוא התאמה במיפוי לפי מיקום יחסי או אינדקס
+            // זהו approx - במציאות צריך מיפוי מדויק יותר
+            
+            // משתמש באינדקס כתוצאת הדמוי
+            const mappedPointId = index + 1;
+            
+            // עדכון ה-ID של הvertex
+            vertex.originalId = vertex.id; // שומר את הID המקורי
+            vertex.id = mappedPointId; // מעדכן לID הנכון
+        });
+        
+        // עדכון התצוגה אם הvertices מוצגים
+        this.refreshVertexDisplay();
+        
+        console.log('✅ vertex IDs עודכנו בהתבסס על המיפוי');
+    }
+    
+    // רענון תצוגת vertices עם IDs מעודכנים
+    refreshVertexDisplay() {
+        const verticesGroup = this.svg.querySelector('#vertices');
+        if (!verticesGroup) return;
+        
+        // עדכון הטקסטים עם המספרים החדשים
+        const vertexTexts = verticesGroup.querySelectorAll('.vertex-number');
+        vertexTexts.forEach((text, index) => {
+            if (this.vertices[index]) {
+                text.textContent = this.vertices[index].id;
+            }
+        });
+        
+        // עדכון ה-data attributes
+        const vertexCircles = verticesGroup.querySelectorAll('.vertex');
+        vertexCircles.forEach((circle, index) => {
+            if (this.vertices[index]) {
+                circle.setAttribute('data-vertex-id', this.vertices[index].id);
+            }
+        });
+    }
+    
+    // Debug functions
+    logAllVertices() {
+        console.log('All vertices:', this.vertices);
+    }
+    
+    logVertexConnections() {
+        // Show examples of connected vertices
+        const examples = this.vertices.slice(0, 5);
+        examples.forEach(vertex => {
+            const connected = this.getConnectedVertices(vertex.id);
+            console.log(`Vertex ${vertex.id} connects to vertices: ${connected.join(', ')}`);
+        });
+    }
+    
+    getConnectedVertices(vertexId) {
+        // This would need implementation based on hex grid logic
+        // For now, return empty array
+        return [];
+    }
+}

pycatan/static/js/gameData.js

@@ -0,0 +1,154 @@
+// נתוני המשחק - אובייקט GAMEDATA (ברירת מחדל כאשר אין חיבור לשרת)
+const GAMEDATA = {
+    // משושים (19 משושים ברמת קושי רגילה)
+    hexes: [
+        // שורה עליונה (3 משושים)
+        { id: 1, q: 0, r: -2, type: 'wood', number: 11, robber: false },
+        { id: 2, q: 1, r: -2, type: 'sheep', number: 12, robber: false },
+        { id: 3, q: 2, r: -2, type: 'wheat', number: 9, robber: false },
+        
+        // שורה שנייה (4 משושים)
+        { id: 4, q: -1, r: -1, type: 'brick', number: 4, robber: false },
+        { id: 5, q: 0, r: -1, type: 'ore', number: 6, robber: false },
+        { id: 6, q: 1, r: -1, type: 'sheep', number: 5, robber: false },
+        { id: 7, q: 2, r: -1, type: 'wheat', number: 10, robber: false },
+        
+        // שורה אמצעית (5 משושים)
+        { id: 8, q: -2, r: 0, type: 'wood', number: 3, robber: false },
+        { id: 9, q: -1, r: 0, type: 'brick', number: 11, robber: false },
+        { id: 10, q: 0, r: 0, type: 'desert', number: null, robber: true },
+        { id: 11, q: 1, r: 0, type: 'wheat', number: 4, robber: false },
+        { id: 12, q: 2, r: 0, type: 'ore', number: 8, robber: false },
+        
+        // שורה רביעית (4 משושים)
+        { id: 13, q: -2, r: 1, type: 'ore', number: 8, robber: false },
+        { id: 14, q: -1, r: 1, type: 'sheep', number: 10, robber: false },
+        { id: 15, q: 0, r: 1, type: 'wood', number: 9, robber: false },
+        { id: 16, q: 1, r: 1, type: 'brick', number: 3, robber: false },
+        
+        // שורה תחתונה (3 משושים)
+        { id: 17, q: -2, r: 2, type: 'wheat', number: 2, robber: false },
+        { id: 18, q: -1, r: 2, type: 'sheep', number: 5, robber: false },
+        { id: 19, q: 0, r: 2, type: 'ore', number: 6, robber: false }
+    ],
+
+    // יישובים - מתחילים ריקים
+    settlements: [],
+
+    // ערים - מתחילים ריקות  
+    cities: [],
+
+    // דרכים - מתחילים ריקות
+    roads: [],
+
+    // מיקום השודד הנוכחי
+    robberPosition: 10,
+    
+    // שחקנים (תוסף חדש)
+    players: [
+        { id: 0, name: 'שחקן 1', victory_points: 2, total_cards: 5 },
+        { id: 1, name: 'שחקן 2', victory_points: 3, total_cards: 7 },
+        { id: 2, name: 'שחקן 3', victory_points: 1, total_cards: 4 },
+        { id: 3, name: 'שחקן 4', victory_points: 2, total_cards: 6 }
+    ],
+    
+    // מידע נוכחי על המשחק
+    current_player: 0,
+    current_phase: 'ACTION',
+    dice_result: [3, 4]
+};
+
+// מיפוי סוגי משאבים לקבצי התמונות
+const RESOURCE_FILES = {
+    'wood': 'Forest.png',
+    'brick': 'Hills.png', 
+    'sheep': 'Pasture.png',
+    'wheat': 'Fields.png',
+    'ore': 'Mountains.png',
+    'desert': 'Desert.png'
+};
+
+// מיפוי תכונות Tile ל-Hex בפורמט שלנו
+function tileToHex(tile) {
+    const tileTypeMap = {
+        'FOREST': 'wood',
+        'HILLS': 'brick',
+        'PASTURE': 'sheep', 
+        'FIELDS': 'wheat',
+        'MOUNTAINS': 'ore',
+        'DESERT': 'desert'
+    };
+    
+    return {
+        id: tile.id || tile.position,
+        q: tile.position ? tile.position[0] : 0,
+        r: tile.position ? tile.position[1] : 0, 
+        type: tileTypeMap[tile.type] || 'desert',
+        number: tile.token,
+        robber: tile.has_robber || false
+    };
+}
+
+// המרת GameState מPyCatan לפורמט שלנו
+function convertGameState(pyGameState) {
+    const converted = {
+        hexes: [],
+        settlements: [],
+        cities: [],
+        roads: [],
+        players: [],
+        robberPosition: null,
+        current_player: pyGameState.current_player || 0,
+        current_phase: pyGameState.current_phase || 'ACTION',
+        dice_result: pyGameState.dice_result || null
+    };
+    
+    // המר משושים
+    if (pyGameState.board && pyGameState.board.tiles) {
+        converted.hexes = pyGameState.board.tiles.map((tile, index) => tileToHex({
+            ...tile,
+            id: index + 1
+        }));
+    }
+    
+    // המר שחקנים
+    if (pyGameState.players) {
+        converted.players = pyGameState.players.map((player, index) => ({
+            id: index,
+            name: player.name || `שחקן ${index + 1}`,
+            victory_points: player.victory_points || 0,
+            total_cards: (player.cards && player.cards.length) || 0
+        }));
+    }
+    
+    // המר מבנים
+    if (pyGameState.buildings) {
+        pyGameState.buildings.forEach(building => {
+            if (building.type === 'settlement') {
+                converted.settlements.push({
+                    id: building.id,
+                    vertex: building.point_id,
+                    player: building.player + 1
+                });
+            } else if (building.type === 'city') {
+                converted.cities.push({
+                    id: building.id,
+                    vertex: building.point_id,
+                    player: building.player + 1
+                });
+            }
+        });
+    }
+    
+    // המר דרכים
+    if (pyGameState.roads) {
+        converted.roads = pyGameState.roads.map((road, index) => ({
+            id: index + 1,
+            from: road.start_point_id,
+            to: road.end_point_id,
+            player: road.player + 1
+        }));
+    }
+    
+    return converted;
+}

pycatan/static/js/main.js

@@ -0,0 +1,414 @@
+// Main file - Game initialization
+let catanBoard;
+let gameState = null;
+let eventSource = null;
+let pointMapping = null; // Point mapping - will be loaded from server
+let playerNames = {}; // Store player names from game
+
+// Global functions for control buttons
+function zoomIn() {
+    if (catanBoard) {
+        catanBoard.zoomIn();
+    }
+}
+
+function zoomOut() {
+    if (catanBoard) {
+        catanBoard.zoomOut();
+    }
+}
+
+function resetZoom() {
+    if (catanBoard) {
+        catanBoard.resetZoom();
+    }
+}
+
+function toggleVertices() {
+    if (catanBoard) {
+        catanBoard.toggleVertices();
+    }
+}
+
+// Toggle building costs modal
+function toggleBuildingCosts() {
+    const modal = document.getElementById('buildingCostsModal');
+    if (modal) {
+        modal.classList.toggle('show');
+    }
+}
+
+// Clear action log
+function clearActionLog() {
+    const logDiv = document.getElementById('action-log');
+    if (logDiv) {
+        logDiv.innerHTML = '<div class="info">Log cleared ✓</div>';
+    }
+}
+
+// טעינת מיפוי נקודות מהשרת
+function loadPointMapping() {
+    return fetch('/api/point_mapping')
+        .then(response => response.json())
+        .then(data => {
+            pointMapping = data;
+            // console.log('🗺️ Point mapping loaded:', `${data.total_points} points`);
+            // console.log('   Example: point 1 at', data.point_to_coords[1]);
+            
+            // Make mapping global so board.js can access it
+            window.pointMapping = pointMapping;
+            
+            return pointMapping;
+        })
+        .catch(error => {
+            console.error('❌ Error loading point mapping:', error);
+            // fallback - create basic mapping
+            pointMapping = {
+                point_to_coords: {},
+                coords_to_point: {},
+                total_points: 54,
+                all_points: Array.from({length: 54}, (_, i) => i + 1)
+            };
+            return pointMapping;
+        });
+}
+
+// חיבור ל-Flask server
+function connectToServer() {
+    console.log('🔗 Connecting to server...');
+    
+    // First load point mapping
+    loadPointMapping().then(() => {
+        console.log('✓ Point mapping loaded');
+        
+        // Now load game state
+        return Promise.all([
+            fetch('/api/game-state', {timeout: 5000}),
+            fetch('/api/actions')
+        ]);
+    })
+    .then(responses => {
+        return Promise.all(responses.map(r => {
+            if (!r.ok) throw new Error(`Server responded with ${r.status}`);
+            return r.json();
+        }));
+    })
+    .then(([gameStateData, actionsData]) => {
+        console.log('📥 Game state received from server:', gameStateData);
+        
+        // Check if state is empty (no hexes)
+        if (!gameStateData.hexes || gameStateData.hexes.length === 0) {
+            console.log('⚠️ Server state is empty, using GAMEDATA as fallback');
+            updateGameState(GAMEDATA);
+        } else {
+            updateGameState(gameStateData);
+        }
+        
+        // Store player names for later use
+        if (gameStateData.players) {
+            gameStateData.players.forEach((player, index) => {
+                playerNames[index] = player.name || `Player ${index + 1}`;
+            });
+        }
+        
+        // Load action history
+        if (actionsData && Array.isArray(actionsData)) {
+            console.log(`📥 Loaded ${actionsData.length} previous actions`);
+            actionsData.forEach(action => logAction(action));
+        }
+        
+        console.log('✓ Server connection established successfully');
+        
+        // Connect to real-time updates
+        connectToSSE();
+    })
+    .catch(error => {
+        console.error('❌ Error connecting to server:', error);
+        console.log('🔄 Using GAMEDATA as fallback');
+        updateGameState(GAMEDATA);
+    });
+}
+
+// Connect to Server-Sent Events for real-time updates
+function connectToSSE() {
+    try {
+        eventSource = new EventSource('/api/events');
+            
+            eventSource.onmessage = function(event) {
+                const data = JSON.parse(event.data);
+                // console.log('📡 Update from server:', data);
+                
+                if (data.type === 'game_update' || data.type === 'state_updated') {
+                    // Update player names if we get new player data
+                    if (data.payload.players) {
+                        data.payload.players.forEach((player, index) => {
+                            playerNames[index] = player.name || `Player ${index + 1}`;
+                        });
+                    }
+                    updateGameState(data.payload);
+                } else if (data.type === 'action_executed') {
+                    logAction(data.payload);
+                } else if (data.type === 'dice_roll') {
+                    logEvent(data.payload, 'log-dice');
+                } else if (data.type === 'resource_distribution') {
+                    logResourceDistribution(data.payload);
+                } else if (data.type === 'turn_start') {
+                    logEvent(data.payload, 'log-turn');
+                } else if (data.type === 'message') {
+                    logEvent(data.payload, 'info');
+                } else if (data.type === 'error') {
+                    logEvent(data.payload, 'error');
+                }
+            };
+            
+            eventSource.onerror = function(error) {
+                console.error('❌ Error in SSE connection:', error);
+            };
+            
+        console.log('✅ Connected to real-time updates');
+    } catch (error) {
+        console.warn('⚠️ Unable to connect to SSE:', error);
+    }
+}
+
+// Update game state
+function updateGameState(newState) {
+    gameState = newState;
+    
+    if (catanBoard) {
+        catanBoard.updateFromGameState(gameState);
+        
+        // Update vertex IDs if we have mapping
+        if (pointMapping) {
+            catanBoard.updateVertexIDsFromMapping();
+        }
+    }
+    
+    updateGameInfo(gameState);
+}
+
+// Update player information display
+function updateGameInfo(state) {
+    const gameInfoDiv = document.getElementById('game-info');
+    if (!gameInfoDiv) return;
+    
+    // Preserve expanded state
+    const expandedPlayers = new Set();
+    document.querySelectorAll('.player-info.expanded').forEach(el => {
+        expandedPlayers.add(el.dataset.playerId);
+    });
+    
+    let html = '<h3>📋 Game Info</h3>';
+    
+    if (state.players) {
+        state.players.forEach((player, index) => {
+            const activeClass = state.current_player === index ? 'active' : '';
+            const isExpanded = expandedPlayers.has(String(index)) ? 'expanded' : '';
+            const playerColors = ['#FF4444', '#4444FF', '#44FF44', '#FFAA00'];
+            const playerColor = playerColors[index % 4];
+            
+            // Get player name from stored names or use default
+            const playerName = playerNames[index] || player.name || `Player ${index + 1}`;
+            
+            // Format cards lists
+            let cardsHtml = '';
+            if (player.cards_list && player.cards_list.length > 0) {
+                // Count cards by type
+                const cardCounts = {};
+                player.cards_list.forEach(card => {
+                    cardCounts[card] = (cardCounts[card] || 0) + 1;
+                });
+                
+                cardsHtml += '<div><strong>Resources:</strong><ul class="card-list">';
+                for (const [card, count] of Object.entries(cardCounts)) {
+                    cardsHtml += `<li>${card}: ${count}</li>`;
+                }
+                cardsHtml += '</ul></div>';
+            } else {
+                cardsHtml += '<div><em>No resource cards</em></div>';
+            }
+            
+            let devCardsHtml = '';
+            if (player.dev_cards_list && player.dev_cards_list.length > 0) {
+                // Count dev cards by type
+                const devCardCounts = {};
+                player.dev_cards_list.forEach(card => {
+                    devCardCounts[card] = (devCardCounts[card] || 0) + 1;
+                });
+                
+                devCardsHtml += '<div style="margin-top:5px;"><strong>Development:</strong><ul class="card-list">';
+                for (const [card, count] of Object.entries(devCardCounts)) {
+                    devCardsHtml += `<li>${card}: ${count}</li>`;
+                }
+                devCardsHtml += '</ul></div>';
+            }
+            
+            html += `
+                <div class="player-info ${activeClass} ${isExpanded}" data-player-id="${index}" onclick="togglePlayerInfo(this)" style="border-left-color: ${playerColor};">
+                    <h4>👤 ${playerName}</h4>
+                    <div class="player-resources">
+                        <strong>🏆 VP:</strong> ${player.victory_points || 0} | 
+                        <strong>🎴 Cards:</strong> ${player.total_cards || 0}
+                    </div>
+                    <div class="player-resources">
+                        <strong>🏘️:</strong> ${player.settlements || 0} |
+                        <strong>🏛️:</strong> ${player.cities || 0} |
+                        <strong>🛣️:</strong> ${player.roads || 0}
+                    </div>
+                    <div class="player-cards">
+                        ${cardsHtml}
+                        ${devCardsHtml}
+                    </div>
+                </div>
+            `;
+        });
+    }
+    
+    if (state.current_phase) {
+        html += `<div style="margin-top: 10px; padding: 10px; background: rgba(52, 152, 219, 0.1); border-radius: 6px;"><strong>📍 Current Phase:</strong> ${state.current_phase}</div>`;
+    }
+    
+    gameInfoDiv.innerHTML = html;
+}
+
+// Toggle player info visibility
+window.togglePlayerInfo = function(element) {
+    element.classList.toggle('expanded');
+}
+
+// Log action
+function logAction(actionData) {
+    const logDiv = document.getElementById('action-log');
+    if (!logDiv) return;
+    
+    const actionElement = document.createElement('div');
+    
+    // Determine class based on action type if needed, or just success/error
+    let className = actionData.success ? 'success' : 'error';
+    let prefix = actionData.success ? '✓' : '✗';
+    
+    // Add specific classes for certain actions
+    if (actionData.success) {
+        if (actionData.action_type && actionData.action_type.includes('BUILD')) {
+            className = 'log-build';
+            prefix = '🔨';
+        }
+    }
+    
+    actionElement.className = className;
+    const timestamp = actionData.timestamp || new Date().toLocaleTimeString('en-GB', { hour12: false });
+    actionElement.textContent = `${prefix} ${actionData.message}`;
+    
+    appendToLog(logDiv, actionElement);
+}
+
+// Log generic event
+function logEvent(data, className) {
+    const logDiv = document.getElementById('action-log');
+    if (!logDiv) return;
+    
+    const element = document.createElement('div');
+    element.className = className;
+    
+    const timestamp = data.timestamp || new Date().toLocaleTimeString('en-GB', { hour12: false });
+    
+    // Add emoji prefix based on type
+    let prefix = '';
+    if (className === 'log-dice') prefix = '🎲';
+    else if (className === 'log-turn') prefix = '➤';
+    else if (className === 'info') prefix = 'ℹ️';
+    else if (className === 'error') prefix = '⚠️';
+    
+    element.textContent = `${prefix} ${data.message}`;
+    
+    appendToLog(logDiv, element);
+}
+
+// Log resource distribution specifically
+function logResourceDistribution(data) {
+    const logDiv = document.getElementById('action-log');
+    if (!logDiv) return;
+    
+    const timestamp = data.timestamp || new Date().toLocaleTimeString('en-GB', { hour12: false });
+    
+    // If we have detailed distributions, log them
+    if (data.distributions) {
+        for (const [player, resources] of Object.entries(data.distributions)) {
+            if (resources && resources.length > 0) {
+                const element = document.createElement('div');
+                element.className = 'log-resource';
+                
+                // Count resources
+                const counts = {};
+                resources.forEach(r => counts[r] = (counts[r] || 0) + 1);
+                
+                const resourceStr = Object.entries(counts)
+                    .map(([res, count]) => `${count}×${res}`)
+                    .join(' ');
+                
+                element.textContent = `📦 ${player}: ${resourceStr}`;
+                appendToLog(logDiv, element);
+            }
+        }
+    } else {
+        // Fallback to generic message
+        const element = document.createElement('div');
+        element.className = 'log-resource';
+        element.textContent = `📦 ${data.message}`;
+        appendToLog(logDiv, element);
+    }
+}
+
+// Helper to append to log and scroll
+function appendToLog(container, element) {
+    container.appendChild(element);
+    
+    // Keep only last 100 items
+    while (container.children.length > 100) {
+        container.removeChild(container.firstChild);
+    }
+    
+    // Scroll to bottom
+    container.scrollTop = container.scrollHeight;
+}
+
+// Game initialization
+document.addEventListener('DOMContentLoaded', async function() {
+    console.log('🎲 Starting Catan board with server connection...');
+    
+    try {
+        // Create board instance (async)
+        catanBoard = new CatanBoard();
+        window.catanBoard = catanBoard; // Expose to window for console access
+        
+        // Wait for board initialization
+        if (catanBoard.init && typeof catanBoard.init === 'function') {
+            console.log('⏳ Waiting for board initialization...');
+            await catanBoard.init();
+            console.log('✓ Board initialized successfully');
+        }
+        
+        // Connect to server
+        connectToServer();
+        
+        console.log('✅ Catan board created successfully!');
+        console.log('🎮 Usage instructions:');
+        console.log('   - Click on hex to move robber');
+        console.log('   - Use mouse wheel to zoom');
+        console.log('   - Drag mouse to pan');
+        console.log('   - Click 📍 to see vertex numbers');
+        
+    } catch (error) {
+        console.error('❌ Error initializing board:', error);
+        // Try to create simple board anyway
+        catanBoard = new CatanBoard();
+        connectToServer();
+    }
+});
+
+// Cleanup on close
+window.addEventListener('beforeunload', function() {
+    if (eventSource) {
+        eventSource.close();
+    }
+});

pycatan/static/js/manual_mapping.js

@@ -0,0 +1,240 @@
+// Manual Mapping Logic
+class ManualMapper extends CatanBoard {
+    constructor() {
+        super();
+        this.mapping = {
+            hexes: {},
+            points: {}
+        };
+        this.currentId = 1;
+        this.mode = 'hex'; // 'hex' or 'point'
+        this.history = [];
+    }
+
+    async init() {
+        await this.initManual();
+    }
+
+    async initManual() {
+        // Generate visual board from scratch
+        this.generateVerticesFromHexes();
+        this.createBoard();
+        this.setupMappingListeners();
+        this.updateUI();
+        
+        console.log("=== GAME LOGIC EXPECTATIONS ===");
+        console.log("Paste the output from 'python print_game_logic.py' here for reference if needed.");
+    }
+
+    setupMappingListeners() {
+        console.log("Setting up mapping listeners...");
+        
+        // Use event delegation on the SVG to catch all clicks
+        this.svg.addEventListener('click', (e) => {
+            console.log("Click detected on:", e.target.tagName, e.target.className);
+            
+            // Handle Hex Click
+            if (this.mode === 'hex') {
+                // Check if we clicked the hexagon path directly
+                if (e.target.classList.contains('hexagon')) {
+                    this.handleHexClick(e.target);
+                    return;
+                }
+                
+                // Check if we clicked the image inside the hex group
+                if (e.target.tagName === 'image' && e.target.parentNode) {
+                    const group = e.target.parentNode;
+                    const hexPath = group.querySelector('.hexagon');
+                    if (hexPath) {
+                        this.handleHexClick(hexPath);
+                        return;
+                    }
+                }
+            }
+            
+            // Handle Point Click
+            if (this.mode === 'point') {
+                if (e.target.classList.contains('vertex')) {
+                    this.handlePointClick(e.target);
+                    return;
+                }
+            }
+        });
+        
+        // Mode switching
+        document.querySelectorAll('input[name="mode"]').forEach(radio => {
+            radio.addEventListener('change', (e) => {
+                this.mode = e.target.value;
+                this.currentId = this.getNextId();
+                this.updateUI();
+            });
+        });
+    }
+
+    getNextId() {
+        const map = this.mode === 'hex' ? this.mapping.hexes : this.mapping.points;
+        let id = 1;
+        while (map[id]) id++;
+        return id;
+    }
+
+    handleHexClick(element) {
+        // In manual mapping, we use the visual ID (from generateVerticesFromHexes) as a temporary key
+        // But wait, generateVerticesFromHexes assigns IDs 1-19 arbitrarily.
+        // We want to assign OUR ID (1, 2, 3...) to this visual element.
+        
+        // The element has data-hex-id which is the visual ID.
+        // We want to map: User Chosen ID -> Visual Coordinates (q, r)
+        
+        // Find the hex data
+        const visualId = parseInt(element.getAttribute('data-hex-id'));
+        const hexData = this.vertices.find(v => v.adjacent_hexes.includes(visualId)) 
+                        ? GAMEDATA.hexes.find(h => h.id === visualId) 
+                        : null; // This is tricky, we need to find the hex object
+        
+        // Actually, we can just find it in GAMEDATA.hexes by ID since createBoard used that
+        const hex = GAMEDATA.hexes.find(h => h.id === visualId);
+        
+        if (this.mapping.hexes[this.currentId]) {
+            alert(`Hex ${this.currentId} already mapped!`);
+            return;
+        }
+
+        // Save mapping
+        this.mapping.hexes[this.currentId] = {
+            q: hex.q,
+            r: hex.r
+        };
+
+        // Visual feedback
+        element.classList.add('mapped');
+        
+        // Add text label
+        const center = this.hexToPixel(hex.q, hex.r);
+        const text = document.createElementNS('http://www.w3.org/2000/svg', 'text');
+        text.setAttribute('x', center.x);
+        text.setAttribute('y', center.y);
+        text.textContent = this.currentId;
+        text.setAttribute('class', 'hex-number mapped-text');
+        text.setAttribute('pointer-events', 'none');
+        this.svg.appendChild(text);
+
+        this.history.push({
+            type: 'hex',
+            id: this.currentId,
+            element: element,
+            textElement: text
+        });
+
+        this.currentId++;
+        this.updateUI();
+    }
+
+    handlePointClick(element) {
+        const visualId = parseInt(element.getAttribute('data-vertex-id'));
+        const vertex = this.vertices.find(v => v.id === visualId);
+
+        if (this.mapping.points[this.currentId]) {
+            alert(`Point ${this.currentId} already mapped!`);
+            return;
+        }
+
+        // Save mapping
+        this.mapping.points[this.currentId] = {
+            x: vertex.x,
+            y: vertex.y
+        };
+
+        // Visual feedback
+        element.classList.add('mapped');
+        
+        // Update text
+        // Find the text element associated with this vertex
+        // It's the next sibling in our DOM structure
+        const text = element.nextElementSibling;
+        if (text && text.classList.contains('vertex-number')) {
+            text.textContent = this.currentId;
+            text.classList.add('mapped-text');
+            text.style.opacity = 1;
+        }
+
+        this.history.push({
+            type: 'point',
+            id: this.currentId,
+            element: element,
+            textElement: text,
+            originalText: visualId
+        });
+
+        this.currentId++;
+        this.updateUI();
+    }
+
+    undoLast() {
+        const last = this.history.pop();
+        if (!last) return;
+
+        if (last.type === 'hex') {
+            delete this.mapping.hexes[last.id];
+            last.element.classList.remove('mapped');
+            last.textElement.remove();
+            if (this.mode === 'hex') this.currentId = last.id;
+        } else {
+            delete this.mapping.points[last.id];
+            last.element.classList.remove('mapped');
+            last.textElement.textContent = last.originalText;
+            last.textElement.classList.remove('mapped-text');
+            if (this.mode === 'point') this.currentId = last.id;
+        }
+        this.updateUI();
+    }
+
+    getExpectedCoords(id, type) {
+        let count = 0;
+        
+        if (type === 'hex') {
+            const rows = [3, 4, 5, 4, 3];
+            for (let r = 0; r < rows.length; r++) {
+                if (id <= count + rows[r]) {
+                    const col = id - count - 1;
+                    return `Row ${r}, Col ${col}`;
+                }
+                count += rows[r];
+            }
+        } else {
+            const rows = [7, 9, 11, 11, 9, 7];
+            for (let r = 0; r < rows.length; r++) {
+                if (id <= count + rows[r]) {
+                    const col = id - count - 1;
+                    return `Row ${r}, Col ${col}`;
+                }
+                count += rows[r];
+            }
+        }
+        return "Done";
+    }
+
+    updateUI() {
+        console.log("Updating UI", this.currentId, this.mode);
+        document.getElementById('nextId').textContent = this.currentId;
+        const hint = this.getExpectedCoords(this.currentId, this.mode);
+        const hintEl = document.getElementById('coordsHint');
+        if (hintEl) {
+            hintEl.textContent = hint;
+            hintEl.style.color = this.mode === 'hex' ? '#e74c3c' : '#2980b9';
+        }
+    }
+
+    exportMapping() {
+        const output = JSON.stringify(this.mapping, null, 2);
+        document.getElementById('output').value = output;
+        console.log("Mapping exported:", this.mapping);
+    }
+}
+
+// Initialize
+const mapper = new ManualMapper();
+
+// Global functions for buttons
+window.undoLast = () => mapper.undoLast();
+window.exportMapping = () => mapper.exportMapping();

pycatan/statuses.py

@@ -0,0 +1,33 @@
+# different statuses in the Game module
+# skips 0 and 1 because there are already equal to True and False
+class Statuses:
+
+    # the action was successfully completed
+    ALL_GOOD = 2
+
+# the action cannot be completed because:
+
+    # the player does not have the correct cards
+    ERR_CARDS = 3
+    # a building is blocking the action
+    ERR_BLOCKED = 4
+    # the point given is not on the board
+    ERR_BAD_POINT = 5
+    # the road's points are not connected
+    ERR_NOT_CON = 6
+    # the building in not connected to any of the player's buildings
+    ERR_ISOLATED = 7
+    # the player is trying to use a harbor they are not connected to
+    ERR_HARBOR = 8
+    # the player is trying to use a building that does not exist
+    ERR_NOT_EXIST = 9
+    # the player is trying to use a building that does not belong to them
+    ERR_BAD_OWNER = 10
+    # the player is trying to build a city on another city rather than a settlement
+    ERR_UPGRADE_CITY = 11
+    # there are not enough cards in the deck to perform this action
+    ERR_DECK = 12
+    # the input given is missing components/invalid
+    ERR_INPUT = 13
+    # when running the testing module, an error was found
+    ERR_TEST = 14

pycatan/templates/index.html

@@ -0,0 +1,107 @@
+<!DOCTYPE html>
+<html lang="en" dir="ltr">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Catan - Game Simulation</title>
+    <link rel="stylesheet" href="{{ url_for('static', filename='css/style.css') }}">
+</head>
+<body>
+    <div class="game-container">
+        <!-- Header -->
+        <div class="game-header">
+            <h1>🎲 Catan - Game Simulation</h1>
+            <p class="subtitle">Settlers of Catan - Web Visualization</p>
+        </div>
+        
+        <div class="content-wrapper">
+            <!-- Left Sidebar - Game Info -->
+            <aside class="sidebar sidebar-left">
+                <div id="game-info" class="game-info">
+                    <h3>📋 Game Info</h3>
+                    <div class="loading">Loading...</div>
+                </div>
+            </aside>
+            
+            <!-- Center - Board -->
+            <main class="board-wrapper">
+                <!-- Board Container -->
+                <div class="board-container" id="boardContainer">
+                    <!-- Board Controls -->
+                    <div class="board-controls">
+                        <button onclick="zoomIn()" class="control-btn" title="Zoom In">🔍+</button>
+                        <button onclick="zoomOut()" class="control-btn" title="Zoom Out">🔍−</button>
+                        <button onclick="resetZoom()" class="control-btn" title="Reset View">⌂</button>
+                        <button id="toggleVertices" onclick="toggleVertices()" class="control-btn" title="Show Vertices">📍</button>
+                        <button id="toggleInfo" onclick="toggleBuildingCosts()" class="control-btn" title="Building Costs">ℹ️</button>
+                    </div>
+                    
+                    <!-- Game Board -->
+                    <svg id="catan-board" width="100%" height="100%">
+                        <!-- Hexes and game elements will be added here by JavaScript -->
+                    </svg>
+                    
+                    <!-- Building Costs Modal -->
+                    <div id="buildingCostsModal" class="modal hidden">
+                        <div class="modal-content">
+                            <div class="modal-header">
+                                <h3>Building Costs</h3>
+                                <button class="modal-close" onclick="toggleBuildingCosts()">✕</button>
+                            </div>
+                            <div class="modal-body">
+                                <table class="costs-table">
+                                    <thead>
+                                        <tr>
+                                            <th>Building</th>
+                                            <th>Resources Required</th>
+                                            <th>VP</th>
+                                        </tr>
+                                    </thead>
+                                    <tbody>
+                                        <tr>
+                                            <td>Road</td>
+                                            <td>1 Brick + 1 Lumber</td>
+                                            <td>—</td>
+                                        </tr>
+                                        <tr>
+                                            <td>Settlement</td>
+                                            <td>1 Brick + 1 Lumber + 1 Wheat + 1 Sheep</td>
+                                            <td>1</td>
+                                        </tr>
+                                        <tr>
+                                            <td>City</td>
+                                            <td>3 Ore + 2 Wheat</td>
+                                            <td>2</td>
+                                        </tr>
+                                        <tr>
+                                            <td>Dev Card</td>
+                                            <td>1 Ore + 1 Sheep + 1 Wheat</td>
+                                            <td>1*</td>
+                                        </tr>
+                                    </tbody>
+                                </table>
+                                <p class="costs-note">* VP awarded only for Victory Point dev cards</p>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            </main>
+            
+            <!-- Right Sidebar - Action Log -->
+            <aside class="sidebar sidebar-right">
+                <div class="log-header">
+                    <h3>📜 Action Log</h3>
+                    <button class="clear-log-btn" onclick="clearActionLog()" title="Clear Log">🗑️</button>
+                </div>
+                <div id="action-log" class="action-log">
+                    <div class="info">Waiting for updates...</div>
+                </div>
+            </aside>
+        </div>
+    </div>
+
+    <script src="{{ url_for('static', filename='js/gameData.js') }}"></script>
+    <script src="{{ url_for('static', filename='js/board.js') }}"></script>
+    <script src="{{ url_for('static', filename='js/main.js') }}"></script>
+</body>
+</html>