Skip to content

README.md

Latest commit

 

History

History
264 lines (195 loc) · 7.21 KB

README.md

File metadata and controls

264 lines (195 loc) · 7.21 KB

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
  1. 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).

  1. Install game dependencies:
cd ../DnD-5th-Edition-API
pip install -r requirements-dev-new.txt
  1. 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
  1. Install dependencies:
pip install -r requirements.txt