Metadata-Version: 2.4
Name: dnd-5e-core
Version: 0.1.8
Summary: Complete D&D 5e Rules Engine: Official encounter tables, gold rewards, 332 monsters, 319 spells, standalone loaders. 100% offline, UI-agnostic.
Home-page: https://github.com/codingame-team/dnd-5e-core
Author: D&D Development Team
Author-email: D&D Development Team <dev@codingame-team.com>
Maintainer-email: D&D Development Team <dev@codingame-team.com>
License: MIT
Project-URL: Homepage, https://github.com/codingame-team/dnd-5e-core
Project-URL: Documentation, https://github.com/codingame-team/dnd-5e-core/blob/main/README.md
Project-URL: Repository, https://github.com/codingame-team/dnd-5e-core
Project-URL: Source Code, https://github.com/codingame-team/dnd-5e-core
Project-URL: Issues, https://github.com/codingame-team/dnd-5e-core/issues
Project-URL: Bug Tracker, https://github.com/codingame-team/dnd-5e-core/issues
Project-URL: Changelog, https://github.com/codingame-team/dnd-5e-core/blob/main/CHANGELOG.md
Project-URL: Quick Start, https://github.com/codingame-team/dnd-5e-core/blob/main/QUICK_START_DATA.md
Project-URL: Examples & Demos, https://github.com/codingame-team/DND5e-Test
Project-URL: Full Applications, https://github.com/codingame-team/DnD-5th-Edition-API
Keywords: dnd,dungeons-dragons,d&d,5e,rpg,tabletop,game-engine,character-sheet,combat-engine,spells,monsters,encounter-builder,dmg,challenge-rating,gold-rewards,standalone,offline
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Games/Entertainment :: Role-Playing
Classifier: Topic :: Games/Entertainment :: Turn Based Strategy
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Requires-Dist: flake8>=4.0; extra == "dev"
Requires-Dist: requests-mock>=1.9.3; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# dnd-5e-core

## 📖 About

**Complete D&D 5th Edition Rules Engine** - A comprehensive Python package implementing all core D&D 5e mechanics and official rules. UI-agnostic design works with any interface (pygame, web, CLI, Qt). Includes 8.7MB of bundled JSON data (2000+ files) with 332 monsters, 319 spells, and complete game rules. **100% standalone** - no external APIs required, works offline!

[![PyPI version](https://badge.fury.io/py/dnd-5e-core.svg)](https://pypi.org/project/dnd-5e-core/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A complete Python package implementing D&D 5th Edition core rules and mechanics, including **official encounter system**, **gold rewards**, **experience tables**, and **standalone character/monster loaders**.

This package contains **all game logic** for D&D 5e and is **UI-agnostic** - use it with pygame, ncurses, web, Qt, or any other interface.

## 🎮 Examples & Frontends

**Looking for examples or complete applications?**

- **[DnD5e-Test](https://github.com/codingame-team/DND5e-Test)** - Demonstration scripts and examples
  - 10+ combat scripts with random character generation
  - Official D&D 5e encounter builder examples
  - Character and monster creation demos
  - All scripts work standalone with just `pip install dnd-5e-core`

- **[DnD-5th-Edition-API](https://github.com/codingame-team/DnD-5th-Edition-API)** - Complete applications
  - Full-featured ncurses interface (terminal-based)
  - Pygame dungeon crawler with real-time combat
  - PyQt5 Wizardry-style interface
  - Character management, inventory, shops, and more

## ✨ New in Version 0.1.8

**📝 Enhanced PyPI Documentation**:
- Updated description highlighting all v0.1.7 features
- Added links to example projects and full applications
- Better showcasing of standalone capabilities

**🎯 All Features from v0.1.7** (fully documented):
- **Gold Rewards System**: Official treasure tables from DMG (levels 1-20)
- **Encounter Builder**: DMG-compliant encounter generation with balanced difficulty
- **Standalone Loaders**: Character and monster loading without external dependencies
- **All D&D 5e Rules**: 100% of core mechanics in the package

**🎮 Integrated D&D 5e Data**: The package includes **8.7 MB of D&D 5e JSON data** (2000+ files):
- **332 monsters** with complete stats and abilities
- **319 spells** with full descriptions and mechanics
- **65 weapons** with damage, properties, and ranges
- **30 armors** with AC calculations
- **237 equipment items**
- Plus: races, classes, traits, features, and more!

**🐉 Extended Monsters from 5e.tools**: Access to **89+ additional monsters**:
- Monsters not in the official API (Orc Eye of Gruumsh, Goblin Boss, etc.)
- 47 monsters with complete actions and abilities implemented
- Support for downloading monster tokens/images
- Advanced search and filtering capabilities

**📦 100% Standalone** - No external API or database required - all data is bundled and **auto-detected**.

## Features

### Complete D&D 5e Implementation

**Core Mechanics:**
- **Entities**: Monster and Character classes with full D&D 5e mechanics
- **Races & Subraces**: All official races with ability bonuses, traits, proficiencies
- **Classes**: All character classes with spellcasting, proficiencies
- **Equipment**: Weapons (with properties, ranges), Armor (AC calculation), Potions
- **Spells**: Complete spellcasting system with spell slots, cantrips, DC
- **Combat**: Actions, Multi-attacks, Special Abilities, Conditions
- **Abilities**: Six core abilities (STR, DEX, CON, INT, WIS, CHA) with modifiers
- **Saving Throws**: Full saving throw system with proficiencies

**Official D&D 5e Rules (NEW in v0.1.7):**
- **📊 Encounter Tables**: Official DMG encounter tables (levels 1-20)
- **💰 Gold Rewards**: Treasure per encounter from DMG
- **⚔️ Challenge Rating**: Accurate encounter difficulty calculation
- **📈 Experience System**: XP tables and level progression
- **🎲 Encounter Builder**: Generate balanced encounters by party level

**Standalone Utilities (NEW in v0.1.7):**
- **Character Generator**: Create random characters without external dependencies
- **Monster Loader**: Load monsters from bundled data or API
- **Data Collections**: Access all D&D 5e data easily

### Integrated Data

- **✅ Bundled JSON Data**: 2000+ D&D 5e data files included (8.7 MB)
- **✅ Auto-Detection**: No configuration needed - data is found automatically
- **✅ Offline Mode**: Works without internet connection
- **✅ Complete**: Monsters, spells, weapons, armors, classes, races, and more
- **✅ Extended**: 89+ additional monsters from 5e.tools

## Installation

```bash
pip install dnd-5e-core
```

Or for development:

```bash
git clone https://github.com/codingame-team/dnd-5e-core.git
cd dnd-5e-core
pip install -e .[dev]
```

## Quick Start

### NEW in v0.1.7: Standalone Character & Monster Loaders

```python
from dnd_5e_core.data import simple_character_generator, load_monsters_database

# Generate random characters without external dependencies
fighter = simple_character_generator(level=5, class_name="fighter", name="Conan")
wizard = simple_character_generator(level=5, class_name="wizard")

print(f"{fighter.name} - Level {fighter.level} {fighter.class_type.name}")
print(f"HP: {fighter.hit_points}/{fighter.max_hit_points}")

# Load all monsters at once
monsters = load_monsters_database()
print(f"Loaded {len(monsters)} monsters")
```

### NEW in v0.1.7: Official D&D 5e Encounter System

```python
from dnd_5e_core.mechanics import (
    select_monsters_by_encounter_table,
    get_encounter_gold,
    ENCOUNTER_TABLE,
    XP_LEVELS
)

# Generate balanced encounter for a level 5 party
party_levels = [5, 5, 4, 6]
monsters, encounter_type = select_monsters_by_encounter_table(
    encounter_level=5,
    available_monsters=monsters_db,
    allow_pairs=True
)

print(f"Encounter: {encounter_type}")
print(f"Monsters: {[m.name for m in monsters]}")

# Get gold reward
gold = get_encounter_gold(5)
print(f"Treasure: {gold} gp")

# Check XP table
xp_for_level_5 = XP_LEVELS[5]
print(f"XP needed for level 5: {xp_for_level_5}")
```

### Load D&D 5e Data

```python
from dnd_5e_core.data import load_monster, list_monsters, load_spell

# List all available monsters
monsters = list_monsters()
print(f"Total monsters: {len(monsters)}")  # 332

# Load a specific monster
goblin = load_monster('goblin')
print(f"Name: {goblin['name']}")
print(f"HP: {goblin['hit_points']}")
print(f"CR: {goblin['challenge_rating']}")

# Load a spell
fireball = load_spell('fireball')
print(f"Spell: {fireball['name']}, Level: {fireball['level']}")
```

**Note**: Data directory is **auto-detected** - no configuration needed!

### Create a Character

```python
from dnd_5e_core.entities import Character
from dnd_5e_core.races import Race
from dnd_5e_core.classes import ClassType
from dnd_5e_core.abilities import Abilities

# Load race and class from API
race = Race.load_from_api("elf")
class_type = ClassType.load_from_api("wizard")

# Create abilities
abilities = Abilities(
    strength=10,
    dexterity=14,
    constitution=12,
    intelligence=16,
    wisdom=13,
    charisma=8
)

# Create character
wizard = Character(
    name="Gandalf",
    race=race,
    class_type=class_type,
    abilities=abilities,
    level=1,
    hit_points=8,
    max_hit_points=8,
    gold=100
)

# Equip weapon
from dnd_5e_core.equipment import Weapon
staff = Weapon.load_from_api("quarterstaff")
wizard.inventory.append(staff)
staff.equipped = True

print(f"{wizard.name} - Level {wizard.level} {wizard.race.name} {wizard.class_type.name}")
print(f"AC: {wizard.armor_class}, HP: {wizard.hit_points}/{wizard.max_hit_points}")
```

### Create a Monster

```python
from dnd_5e_core.entities import Monster

# Load from API
orc = Monster.load_from_api("orc")

print(f"{orc.name} - CR {orc.challenge_rating}")
print(f"AC: {orc.armor_class}, HP: {orc.hit_points}")
print(f"Actions: {[a.name for a in orc.actions]}")
```

### Extended Monsters from 5e.tools (New!)

```python
from dnd_5e_core.entities import get_extended_monster_loader

# Load the monster loader
loader = get_extended_monster_loader()

# Search for monsters
goblins = loader.search_monsters(name_contains="goblin", min_cr=1, max_cr=3)
print(f"Found {len(goblins)} goblin variants")

# Get a specific monster with full data
orc_eye = loader.get_monster_by_name("Orc Eye of Gruumsh")
print(f"{orc_eye['name']} - CR {orc_eye['cr']}")
print(f"HP: {orc_eye['hp']['average']}, Source: {orc_eye['source']}")

# Get statistics
stats = loader.get_stats()
print(f"Total extended monsters: {stats['total']}")
print(f"Sources: {list(stats['by_source'].keys())}")

# Download monster tokens
from dnd_5e_core.utils import download_monster_token

download_monster_token("Orc Eye of Gruumsh", source="MM", save_folder="tokens")
```

### Combat System

```python
from dnd_5e_core.combat import CombatSystem

combat = CombatSystem()

# Add participants
combat.add_character(wizard)
combat.add_monster(orc)

# Start combat
combat.start()

# Combat round
while not combat.is_finished():
    current_actor = combat.current_turn()

    if isinstance(current_actor, Character):
        # Character attacks monster
        target = combat.get_monsters()[0]
        action = current_actor.actions[0]
        damage = current_actor.attack(target, action)
        print(f"{current_actor.name} attacks {target.name} for {damage} damage!")

    elif isinstance(current_actor, Monster):
        # Monster attacks character
        target = combat.get_characters()[0]
        action = current_actor.actions[0]
        damage = current_actor.attack(target, action)
        print(f"{current_actor.name} attacks {target.name} for {damage} damage!")

    combat.next_turn()

winners = combat.get_winners()
print(f"Combat finished! Winners: {[w.name for w in winners]}")
```

### Spellcasting

```python
from dnd_5e_core.spells import Spell

# Character must have spellcasting ability
if wizard.is_spell_caster:
    # Load spell from API
    fireball = Spell.load_from_api("fireball")

    # Check if can cast
    if wizard.can_cast(fireball):
        # Cast spell at target
        damage = wizard.cast_attack(orc, fireball)
        print(f"{wizard.name} casts Fireball on {orc.name} for {damage} damage!")

        # Saving throw
        if orc.saving_throw(dc_type=fireball.dc_type, dc_value=wizard.dc_value):
            print(f"{orc.name} succeeded saving throw!")
```

## Architecture

This package follows **separation of concerns**:

### What this package DOES:
- All D&D 5e game rules and mechanics
- Character/Monster creation and management
- Combat resolution and damage calculation
- Spell casting and effects
- Equipment management
- Saving throws, ability checks
- Experience and leveling
- Data loading from D&D 5e API

### What this package DOES NOT do:
- User interface (no pygame, no ncurses, no GUI)
- Game loop management
- Graphics rendering
- Sound effects
- Input handling
- Save file management (provides serialization only)

### Your application provides:
- UI layer (console, GUI, web, etc.)
- Game state management
- User input handling
- Rendering and display
- Save/load game state using provided serialization

## Usage in Your Project

```python
# Your game imports dnd-5e-core for game logic
from dnd_5e_core.entities import Character, Monster
from dnd_5e_core.combat import CombatSystem

# You provide the UI
import pygame  # or curses, or tkinter, or web framework

# Game loop (you control this)
while running:
    # Handle input (your code)
    key = get_user_input()

    # Call game logic (dnd-5e-core)
    if key == "attack":
        damage = player.attack(monster)

    # Render (your code)
    render_game_state(player, monster)
```

## Data Sources

The package can load data from:
1. **D&D 5e API** (https://www.dnd5eapi.co/) - Default
2. **Local JSON files** - For offline mode
3. **Custom data** - Implement your own loader

## Testing

```bash
pytest tests/
```

## Documentation

See `/docs` folder for detailed documentation:
- Entity System
- Combat Mechanics
- Spellcasting System
- Equipment Guide
- **Extended Monsters from 5e.tools** - See [EXTENDED_MONSTERS_MIGRATION.md](docs/EXTENDED_MONSTERS_MIGRATION.md)
- API Reference

## License

MIT License - See LICENSE file for details

## Contributing

See CONTRIBUTING.md for guidelines.

## Credits

Based on D&D 5th Edition rules © Wizards of the Coast.
This is a fan-made implementation for educational purposes.
