# Dungeon Explorer

A modular text-based adventure game written in Python.

## Features

- **Multiple Difficulty Levels**: Easy, Normal, Hard, Nightmare
- **Achievement System**: 15+ achievements to unlock
- **Turn-based Combat**: Strategic combat with equipment bonuses
- **Shop System**: Buy weapons, armor, potions, and accessories
- **Multiple Enemies**: Goblins, Skeletons, Orcs, Dragons, and more
- **Inventory Management**: Collect and use items
- **Score System**: Compete for high scores with difficulty multipliers

## Installation

```bash
# From the output directory
pip install -e .

# Or run directly
python run_game.py
```

## Usage

```bash
# Run the game
python -m dungeon_explorer

# Run tests
python -m dungeon_explorer --test
```

## Project Structure

```
dungeon_explorer/
├── __init__.py      # Package initialization
├── __main__.py      # Module entry point
├── config.py        # Game configuration and constants
├── player.py        # Player class and stats
├── enemies.py       # Enemy definitions and behavior
├── items.py         # Item definitions and shop system
├── achievements.py  # Achievement tracking system
├── combat.py        # Combat mechanics
├── rooms.py         # Room definitions and navigation
├── ui.py            # User interface functions
├── game.py          # Main game loop
└── tests.py         # Unit tests
```

## Architecture

### Modules

| Module | Purpose |
|--------|---------|
| `config` | Game constants, difficulty settings, balance values |
| `player` | Player state, inventory, stats, scoring |
| `enemies` | Enemy types, stats, behaviors |
| `items` | Item definitions, shop, equipment effects |
| `achievements` | Achievement definitions and tracking |
| `combat` | Turn-based combat system |
| `rooms` | Room logic and navigation |
| `ui` | Display and input handling |
| `game` | Main game loop orchestration |

### Key Classes

- `Player`: Manages player state, inventory, and progression
- `Enemy`: Represents enemy instances in combat
- `CombatSystem`: Handles combat encounters
- `AchievementManager`: Tracks and awards achievements
- `Room`: Base class for dungeon rooms
- `Game`: Main game controller

## Extending the Game

### Adding New Enemies

Edit `enemies.py`:

```python
ENEMIES["new_enemy"] = EnemyStats(
    name="New Enemy",
    hp=50,
    damage=25,
    gold=40,
    xp=20,
    tier=EnemyTier.UNCOMMON,
    description="A fearsome new foe.",
)
```

### Adding New Items

Edit `items.py`:

```python
ITEMS["new_item"] = Item(
    id="new_item",
    name="New Item",
    description="Does something cool.",
    item_type=ItemType.WEAPON,
    price=100,
    effects={"damage_bonus": 20},
)
```

### Adding New Achievements

Edit `achievements.py`:

```python
ACHIEVEMENTS["new_achievement"] = Achievement(
    id="new_achievement",
    name="New Achievement",
    description="Do something special",
    icon="🎯",
    category=AchievementCategory.CHALLENGE,
    points=50,
)
```

### Adding New Rooms

Edit `rooms.py`:

```python
class NewRoom(Room):
    def __init__(self):
        super().__init__("new_room", "New Room", "Description")

    def enter(self, player: Player) -> RoomResult:
        # Room logic here
        return RoomResult("next_room")
```

## Testing

Run the test suite:

```bash
python -m dungeon_explorer --test
```

Tests cover:
- Configuration loading
- Player mechanics
- Enemy behavior
- Item effects
- Achievement tracking
- Combat system
- Room navigation

## License

MIT License - feel free to modify and distribute.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Submit a pull request
