PyMazeBuilder

Generate perfect mazes with Python using a growing tree algorithm and dungeons with rooms connected by corridors.

Installation

pip install pymazebuilder

Maze

█████████████████████
█░░░░░░░░░█░░░░░░░░██
██░░░░░░░░█░█████░███
█░░░░░░░░░░░█░░██░░░█
█░░░░░░░░░█░█░█████░█
█░░░░░░░░░█░░░█░░░█░█
█░░░░░░░░░█████░█░█░█
███░░░░██░░░░░░░█░░░█
███░███████████████░█
█░░░█░░░░░█░░░░░░░░░█
█░███░███░█░█████████
█░█░░░███░█░█░░░░░░░█
█░█░███░█░█░█░█████░█
█░█░██░░█░█░░░█░░██░█
█░█░██░░█░█████░███░█
█░░░█░░░░░░░█░░░░░█░█
█░███░░░░░░░█░███░█░█
█░██░░█░░░░░█░█░░░█░█
█░███░█░█████░█░███░█
█░░░░░█░░░░░░░█░░░░░█
█████████████████████

Dungeon

█████████████████████
█████████████████████
█░░░░░░░░░░░░░░░░████
█░░░░██████████░░████
█░░░░█░░░░░░░░░░░████
█░░░░░░░░░░░░░█░░████
██░██████████░█░░████
██░██████████░█░░████
██░█████████░░░░░████
██░█████░░░░░░░██████
██░░░░░░░░██░░░██████
██░░██░░░░███████████
█░░░░░░░░░███████████
█░░░░░░░░░███████████
█░░░░░░░░░███████████
█░░░░░███████████████
█░░░░░███████████████
█░░░░░███████████████
█░░░░░███████████████
█████████████████████
█████████████████████

Generated data structure

    {
        grid: [
          [
            Cell {
              x: 0,
              y: 0,
              exits: [],
              blocked: true,
              displayed: false,
              visited: false
            },
            ...
          ]
        ]
        rooms: [
            Room {
                x: 0,
                y: 0,
                width: 0,
                height: 0
            }
        ]
    }

Quick use

Example

Generate a maze

python main.py

Generate a dungeon

python main.py --type=dungeon

The built-in renderer is a simple ASCII renderer which prints the maze to the console.

from pymazebuilder.generators.generator_manager import GeneratorManager
from pymazebuilder.generators.maze import MazeGenerator
from pymazebuilder.renderer import Renderer
data = GeneratorManager(
    [
        {
            "generator": MazeGenerator,
            "options": {"width": 10, "height": 10, "floors": 1},
        },
    ]
)
data.generate()
Renderer(data)

Randomization

utils.py contains a random class which handles all random number generation and can be seeded.

Generator classes

Generator classes can be passed as an optional array of objects to the maze generator.

The shape of this data structure is as follows:

[
    {
        generator: <generator class>,
        options: <options object>
    },
    ...
]

Generator (src/pymaze/generator.py) will iterate over each generator class and instantiate it.

Example

The following example shows how to generate a maze with rooms using the provided room generator.

(also see src/pymaze/main.py)

from pymazebuilder.generators.generator import Generator
from pymazebuilder.generators.renderer import Renderer

Generator([
    {
        'generator': MazeGenerator,
        'options': {
            ...
        }
    },
    {
        'generator': RoomGenerator,
        'options': {
            ...
        }
    },
    {
        'generator': StairsGenerator,
        'options': {
            ...
        }
    }
])

Renderer(generator)

Multi-floor maze

Use the floors option to generate a multi-floor maze.

Use the src/generators/stairs.py generator to connect the floors with stairs.

Floor 0
█████████████████████
█░██░░░░░██░░░░░░░░░█
█░███░█░███░░░░░█░█░█
█░░░█░█░░░░░█░░░█░█░█
███▼█░█░█████████░█░█
█░░░█░█░░░█░░░░░█░███
█░███░███░█░███░█░███
█░█░░░░██░█░█░░░█░░░█
█░█░█████░█░█░█░█░░░█
█░█░░░░░█░███░█░█░░░█
█░█░░██░█░███░█░█░░░█
█░█░░░█░█░░░░░█░░░█░█
█░███░█░███░░░░░█░█░█
█░██░░█░░░░░░░█░░░█░█
█░███████████░█░███░█
█░░░█░░░█░░░█░░░█░░░█
███░█░█░█░█░█████░█░█
███░░░█░█░█░░░░░░░█░█
█░█████░█░███░░░░░█░█
█░░░░░░░░░██░░░░░░░░█
█████████████████████
Floor 1
█████████████████████
█░░░░░░░░░█░░░░░░░░██
██░░░░░░░░█░█████░███
█░░░░░░░░░░░█░░██░░░█
█░░▲░░░░░░█░█░█████░█
█░░░░░░░░░█░░░█░░░█░█
█░░░░░░░░░█████░█░█░█
███░░░░██░░░░░░░█░░░█
███░███████████████░█
█░░░█░░░░░█░░░░░░░░░█
█░███░███░█░█████████
█░█░░░███░█░█░░░░░░░█
█░█░███░█░█░█░█████░█
█░█░██░░█░█░░░█░░██░█
█░█░██░░█░█████░███░█
█░░░█░░░░░░░█░░░░░█░█
█░███░░░░░░░█░███░█░█
█░██░░█░░░░░█░█░░░█░█
█░███░█░█████░█░███░█
█░░░░░█░░░░░░░█░░░░░█
█████████████████████

▲ = stairs going up
▼ = stairs going down
█ = wall
░ = floor

Custom generator classes

Custom generators should match the following pattern.

class SomeGenerator:
    def __init__(data: dict, options: dict):
        # do something with the data object
        self.data = data
        self.data["some_property"] = "some value"

See src/pymaze/room.py and src/pymaze/maze.py for complete examples along with a list of optional arguments that each class takes.

License

GNU GPL 3

Contributors

• @w4ffl35