GDParchis 🎲 🏆

GDParchis is a modern 3D adaptation of the traditional Parchís board game, built with Godot Engine 4.7 featuring native Wayland support on Linux, Windows desktop executables, and Android APK packages.

---

🌟 Key Features

• 📐 Polymorphic Board Variants:
  • 🔺 3-Player Triangular Board (Board3): Symmetrical 3-arm triangular board geometry with 3 players (Yellow 🟡, Blue 🔵, Red 🔴), 78 custom squares, and a 6-sided mitered wooden frame.
  • 🟦 4-Player Classic Board (Board4): Classic 4-arm cross board geometry with 4 players (Yellow 🟡, Blue 🔵, Red 🔴, Green 🟢) and 104 squares.
  • ⬡ 6-Player Hexagonal Board (Board6): Symmetrical 6-arm hexagonal board geometry with 6 players (Yellow 🟡, Blue 🔵, Red 🔴, Green 🟢, Grey 🩶, Pink 🩷), 150 custom squares, and a 6-sided mitered wooden frame.
  • 🛑 8-Player Octagonal Board (Board8): Symmetrical 8-arm octagonal board geometry with 8 players (Yellow 🟡, Blue 🔵, Red 🔴, Green 🟢, Grey 🩶, Violet 💜, Orange 🟠, Cyan 🩵), 208 custom squares, and an 8-sided mitered wooden frame.
• 🎮 Flexible Game Modes: Configure 2, 3, 4, 6, or 8 players with any combination of Human or AI (Artificial Intelligence) players.
• 🎲 Comparative Starting Roll: Simultaneous display of all initial dice rolls to determine the starting player, with automatic tie-breaker round management.
• 📐 Official Parchís Rules Enforcement:
  • Leaving home requires rolling a 5.
  • Strict 2-piece capacity limit per square.
  • Barrier / Bridge formation with 2 pieces of the same color and mandatory barrier break rules on rolling a 6.
  • Safe squares and Home Exit squares.
  • Automatic bonus moves: +20 for capturing an opponent piece and +10 for reaching the goal square.
• 📜 Match History Viewer: Persistent match recording (user://game_history.json) logging winners, duration, turn counts, and roll logs stored in standard OS user data locations (~/.local/share/gdparchis/ on Linux, %APPDATA%\gdparchis\ on Windows).
• 🛠️ Developer 3D Calibration Suite (management.py --calibration): Real-time interactive 3D piece dragging, 5% proportional scaling, 3D route line path visualizer with filled directional arrows, camera zoom/pan, multi-step undo (Ctrl+Z), and JSON dataset persistence.
• 🧪 Automated Testing Suite: Integrated 54-test GDScript headless testing system with a 99.6% Code Coverage Engine.
• 🐧 Multiplatform Distributions: Native Linux binary/PCK, Windows .exe, and Android .apk.

---

📸 Screenshots & Board Variants

🎮 Game Interface

Main Menu	Starting Dice Roll
Player count, color selection, custom names, and AI settings	Simultaneous dice comparison and tie-breaker rounds

---

📐 Board Variants

🔺 3-Player Triangular Board (Board3)	🟦 4-Player Classic Board (Board4)
Symmetrical 3-arm triangular board (78 squares) with custom wooden frame	Classic 4-arm cross board (104 squares) with 4 players

⬡ 6-Player Hexagonal Board (Board6)	🛑 8-Player Octagonal Board (Board8)
Symmetrical 6-arm hexagonal board (150 squares) with 6 players	Symmetrical 8-arm octagonal board (208 squares) with 8 players

---

🛠️ Setup & Running

System Requirements

• Linux: X11 or Wayland (Godot 4.7+). Supports native binary and PCK package.
• Windows: Windows 10/11 (64-bit).
• Android: Android 7.0+ (ARM64 / x86_64).
• Python: 3.10+ (for the management CLI script management.py).

Development Execution

To run the game in development mode using Godot:

python3 management.py --play

Developer 3D Calibration Tool

To launch the interactive 3D piece and route calibration suite:

python3 management.py --calibration

---

🧪 Automated Testing & Code Coverage

The project features a headless GDScript test suite that runs without opening a graphical window:

python3 management.py --test

---

📦 Building Executables & Distributions

Export packages for Linux, Windows, and Android using the CLI:

# Export Linux, Windows (.exe), and Android (.apk)
python3 management.py --export

Output distributions are generated in dist/:

• 🐧 Linux: dist/Linux/gdparchis-<VERSION>.x86_64 & dist/Linux/gdparchis-<VERSION>.pck
• 🪟 Windows Desktop: dist/Windows/gdparchis-<VERSION>.exe
• 🤖 Android: dist/Android/gdparchis-<VERSION>.apk

---

📚 Documentation Links

• 📘 User Manual: Full guide on game rules, controls, calibration suite, and interface mechanics.
• 🔬 Testing System Documentation: Technical details on unit testing, headless state simulator, and coverage engine.
• ⚙️ Godot 4.7 Environment Guide: Environment settings, local export templates, and coding standards.
• 📱 Android Setup Guide: Gentoo Portage dependencies, Android SDK installation, and APK signing steps.

---

📄 License

This project is licensed under the GNU General Public License v3.0 (GPLv3).