D&D 5th Edition Simulation Engine

A comprehensive simulation engine implementing D&D 5th Edition rules with multiple interface options.

🏗️ Architecture

This project uses dnd-5e-core v0.4.0 package for all D&D 5e game logic. Most games import from dnd-5e-core for entities, combat, spells, equipment, etc.

See docs/ARCHITECTURE_JEUX.md for detailed architecture documentation.

🆕 New Features (dnd-5e-core v0.4.0)

• ✨ ClassAbilities - Automatic application (Extra Attack, Rage, Sneak Attack, etc.)
• 🎭 RacialTraits - Automatic application (Darkvision, Fey Ancestry, Lucky, etc.)
• ⚡ Conditions System - Auto-detection and display (Poisoned, Restrained, Paralyzed, etc.)
• 🎁 Magic Items - 10+ predefined items (Ring of Protection, Wand of Magic Missiles, etc.)
• 🎭 Multiclassing - Full multiclass support with spell slot calculation

All frontends using dnd-5e-core benefit from these features automatically!

Available Versions

1. Console Version ✅ Uses dnd-5e-core

Full D&D 5th Edition rules implementation with character creation and combat simulation.

Run using:

• Recommended: python ./main.py (requires Terminal and Python ≥ 3.10.0)
• Debug mode: python ./main_pexpect.py (for IDE debugging, may have minor display issues)

Console Version Manual

2. Ncurses Version ✅ Uses dnd-5e-core

Text-based interface (ncurses) - ncurses adaptation of main.py with full D&D 5e features.

Run using:

• python ./main_ncurses.py

Features:

• Castle services (Tavern, Inn, Temple, Trading Post, Training Grounds)
• Dungeon exploration with combat
• Character creation and party management
• Inventory management

Ncurses Version Manual

3. Pygame Suite ✅ Uses dnd-5e-core

Complete graphical game with multiple modules:

Main Menu: python ./dungeon_menu_pygame.py

Modules:

• dungeon_pygame.py - Dungeon exploration and combat
• boltac_tp_pygame.py - Boltac's Trading Post (buy/sell equipment)
• monster_kills_pygame.py - Monster kill statistics

Features:

• Spell casting
• Inventory management
• Melee & ranged combat (D&D 5th Edition rules)
• Graphical interface with mouse support

Pygame Version Documentation

4. Tkinter Version ❌ Standalone (simplified D&D rules)

Basic arena with simplified custom D&D rules (does not use dnd-5e-core).

• Single-character dungeon exploration
• Multiple dungeon levels
• Treasure collection
• Simplified D&D ruleset implementation

Run using:

• python ./dungeon_tk.py

Tkinter Version Manual

5. PyQt5 Version ✅ Uses dnd-5e-core

Graphical interface using Qt Designer framework with full D&D features except training grounds.

Run using:

• python pyQTApp/wizardry.py

PyQt5 Version Manual

5. RPG Pygame Demo ❌ Standalone (simplified D&D rules)

Basic gameplay with collision detection (Simplon gamejam inspired)

Run using:

• python ./lab_games/rpg_pygame.py

RPG Demo Manual

6. Ncurses Version ❌ Standalone (simplified D&D rules)

Text-based arena with basic combat and enemy movement

Run using:

• python ./lab_games/rpg_ncurses.py

Ncurses Version Manual

Installation

For End Users (Recommended)

Download pre-built executables from GitHub Releases:

• Windows: dnd-console-1.0-windows.exe, dnd-pygame-1.0-windows.exe
• macOS: dnd-console-1.0-macos, dnd-pygame-1.0-macos
• Linux: dnd-console-1.0-linux, dnd-pygame-1.0-linux

Just download and run - no installation required!

For Developers

Prerequisites

• Python 3.10+
• pip

Installation Steps

1. Clone repositories:

git clone https://github.com/codingame-team/dnd-5e-core.git
git clone https://github.com/codingame-team/DnD-5th-Edition-API.git

2. Install dnd-5e-core:

cd dnd-5e-core
pip install -e .

OR install from PyPI:

pip install dnd-5e-core>=0.4.0

Note: This project requires dnd-5e-core version 0.4.0 or higher to benefit from all features (ClassAbilities, RacialTraits, Conditions, Magic Items, Multiclassing).

3. Install game dependencies:

cd ../DnD-5th-Edition-API
pip install -r requirements-dev-new.txt

4. Run games:

python main.py                    # Console version
python main_ncurses.py            # Ncurses version
python dungeon_menu_pygame.py     # Pygame version
python dungeon_tk.py              # Tkinter version
python pyQTApp/wizardry.py        # PyQt5 version

Building Executables

Quick Build

macOS/Linux

./build_all.sh

Windows

build_all.bat

Executables will be in dist/ folder.

Manual Build (Advanced)

See docs/GUIDE_DEPLOIEMENT.md for detailed instructions.

---

📁 Project Structure

DnD-5th-Edition-API/
├── main.py                   # Console version (main frontend)
├── main_ncurses.py           # Ncurses interface
├── dungeon_pygame.py         # Pygame dungeon crawler
├── dungeon_menu_pygame.py    # Pygame main menu
├── dungeon_tk.py             # Tkinter version
├── ui_helpers.py             # UI utility functions
│
├── pyQTApp/                  # PyQt5 application
│   ├── wizardry.py           # Main PyQt interface
│   └── Castle/               # Castle modules
│       ├── Inn_module.py
│       ├── Tavern_module.py
│       └── ...
│
├── docs/                     # Documentation
│   ├── ARCHITECTURE_JEUX.md  # Architecture guide
│   └── GUIDE_DEPLOIEMENT.md  # Deployment guide
│
├── manual/                   # User manuals
│   ├── manual_console_version.md
│   ├── manual_ncurses_version.md
│   └── ...
│
├── tests/                    # Test scripts
│   ├── README.md
│   └── test_*.py
│
├── archive/                  # Development history
│   └── README.md
│
├── data/                     # Game data
├── images/                   # Graphics
├── sounds/                   # Audio files
└── sprites/                  # Sprite assets

See INDEX.md for complete navigation guide.

🧪 Testing

Run all tests:

pytest tests/

Run specific test:

python tests/test_dnd_core.py

Validate migration:

python tests/validate_migration.py

See tests/README.md for details on all test scripts.

Old Installation Methods (Legacy)

Binary Installation (Old Method)

1. Install PyInstaller:

   pip install pyinstaller

2. Run platform-specific installer:

• macOS/Linux: ./install.sh
• Windows: install.bat

Development Installation

Required: Python 3.11+

Option 1: IDE Installation (Recommended)

Use IntelliJ PyCharm 2022.3 Community Edition's package manager

Option 2: Manual Installation

1. Update pip:

pip install --upgrade pip

2. Install dependencies:

pip install -r requirements.txt