RDGen 1.0.1
A reusable 2D dungeon generator for Python projects
License: MIT
Requires Python: >=3.6

# Dungeon Generator

A reusable dungeon generator for Python projects.

## Features

- Generates random dungeon layouts with rooms and corridors.
- Ensures non-overlapping rooms.
- Connects rooms with corridors using a minimal spanning tree algorithm.
- Places doors at room entrances.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Installation

```bash
pip install RDGen
```

## Importable Functions

### 'generate_rooms'

Generates non-overlapping rooms in a dungeon grid.

**Syntax**:
```Python

grid, rooms = generate_rooms(num_rooms, min_width, max_width, min_height, max_height, grid_width, grid_height, buffer=1)
```
Parameters:
- num_rooms (int): Number of rooms to generate.
- min_width (int): Minimum width of a room.
- max_width (int): Maximum width of a room.
- min_height (int): Minimum height of a room.
- max_height (int): Maximum height of a room.
- grid_width (int): Width of the dungeon grid.
- grid_height (int): Height of the dungeon grid.
- buffer (int, optional): Buffer space around rooms to prevent adjacency. Defaults to 1.

Returns:
- grid (list of list of str): The dungeon grid represented as a 2D list of characters.
- rooms (list of dict): Details of the rooms generated. Each room is a dictionary with keys:
- - 'x' (int): X-coordinate (column) of the room's top-left corner.
- - 'y' (int): Y-coordinate (row) of the room's top-left corner.
- - 'width' (int): Width of the room.
- - 'height' (int): Height of the room.

### 'connect_rooms'

Connects the rooms in the dungeon grid by creating corridors and placing doors

```Python
connect_rooms(grid, rooms, door_chance)
```

Parameters:
- grid (list of list of str): The dungeon grid generated by generate_rooms.
- rooms (list of dict): The list of rooms generated by generate_rooms.
- door_chance (float): The probability (between 0.0 and 1.0) of placing a door at the corridor ends.

Returns:
- None: Modifies the grid in place by adding corridors ('#') and doors ('+').


## Usage Example

### Basic Dungeon Generation

```Python
from RDGen import generate_rooms, connect_rooms

# Define parameters
num_rooms = 10
min_width = 5
max_width = 8
min_height = 5
max_height = 8
grid_width = 50
grid_height = 30
door_chance = 0.5

# Generate the dungeon rooms and grid
grid, rooms = generate_rooms(
    num_rooms=num_rooms,
    min_width=min_width,
    max_width=max_width,
    min_height=min_height,
    max_height=max_height,
    grid_width=grid_width,
    grid_height=grid_height
)

# Connect the rooms with corridors
connect_rooms(
    grid=grid,
    rooms=rooms,
    door_chance=door_chance
)

# Print the dungeon grid
for row in grid:
    print(''.join(row))
```

### Visualizing the Dungeon
To visualize the dungeon in the terminal using colors (Requires the colorama libary):

```Python
from RDGen import generate_rooms, connect_rooms
from colorama import init, Fore, Style

# Initialize colorama
init()

# Define parameters
num_rooms = 15
min_width = 4
max_width = 8
min_height = 4
max_height = 8
grid_width = 60
grid_height = 40
door_chance = 0.3

# Generate the dungeon
grid, rooms = generate_rooms(
    num_rooms=num_rooms,
    min_width=min_width,
    max_width=max_width,
    min_height=min_height,
    max_height=max_height,
    grid_width=grid_width,
    grid_height=grid_height
)

# Connect the rooms
connect_rooms(
    grid=grid,
    rooms=rooms,
    door_chance=door_chance
)

# Define cell representations with colors
cell_symbols = {
    'W': Fore.GREEN + '#' + Style.RESET_ALL,     # Walls
    '.': Fore.WHITE + '.' + Style.RESET_ALL,     # Rooms
    '#': Fore.CYAN + '.' + Style.RESET_ALL,      # Corridors
    '+': Fore.YELLOW + '+' + Style.RESET_ALL,    # Doors
}

# Print the grid with colors
for row in grid:
    line = ''.join(cell_symbols.get(cell, ' ') for cell in row)
    print(line)
```

### Understanding the Dungeon Grid
The dungeon grid is a 2D list of characters where each character represents a type of tile:
- 'W': Wall (unexplored or solid area)
- '.': Room floor
- '#': Corridor floor
- '+': Door

You can use this grid to visualize or render the dungeon in various ways, such as:
- Printing to the Console
- Graphical Rendering: use a graphics library (e.g., pygame, matplotlib) to render the dungeon visually.
- Game Integration: Incorporate the grid into your game's map system, where each character corresponds to a tile type.

## Example: Painting the Dungeon
Here's how you can use the grid to 'paint' the dungeon in a more visual manner:
```Python
import matplotlib.pyplot as plt
import numpy as np

# Convert the grid to a NumPy array for easier manipulation
grid_array = np.array(grid)

# Create a color map
color_map = {
    'W': 0,   # Walls
    '.': 1,   # Room floors
    '#': 2,   # Corridors
    '+': 3    # Doors
}

# Map the grid characters to color indices
grid_colors = np.vectorize(color_map.get)(grid_array)

# Define the color palette
cmap = plt.cm.get_cmap('Accent', 4)  # 4 discrete colors

# Plot the dungeon
plt.figure(figsize=(10, 8))
plt.imshow(grid_colors, cmap=cmap, origin='upper')
plt.colorbar(ticks=range(4), label='Tile Type')
plt.clim(-0.5, 3.5)
plt.title('Dungeon Layout')
plt.axis('off')
plt.show()
```

NOTE: You'll need to install matplotlib to run this example:
```bash
pip install matplotlib # install matplotlib using pip
```