NAME

Games::Maze - Create Mazes as Objects.

SYNOPSIS

 use Games::Maze;

 $m1 = Games::Maze->new();
 $m2 = Games::Maze->new(dimensions => [12,7,2]);
 $m3 = Games::Maze->new(dimensions => [12,7,2],
                        cell => 'Hex');

 $m1->make();
 $m1->solve();
 print $m1->to_ascii();
 print $m1->to_hex_dump();

 %maze_attr = $m1->describe();

DESCRIPTION

Simply put, this package create mazes. You may use the Games::Maze package to create 3-dimensional rectangular or hexagonal mazes. Mazes are objects that you can manipulate using the available methods.

Maze Object Methods

new([<attribute> => value, ...])

Creates the object with its attributes. Current attributes are:

'form'

Default value: 'Rectangle'. The shape of the entire maze. Currently 'Rectangle' is the valid for all mazes, 'Hexagon' is valid for the {cell => 'Hex'} class of mazes.

'cell'

Default value: 'Quad'. The shape of the maze's cells. Valid values are 'Quad' and 'Hex'.

'dimensions'

Default value: [3, 3, 1]. The number of columns, rows, and levels in the maze. The minimum values for mazes of form 'Rectangle' are [2, 2, 1].

The minimum values for mazes of form 'Hexagon' are [2, 1, 1] because the columns and rows values represent slightly different things. The hexagon form is shaped with the the 'points' North and South, and the vertical sides East and West. The rows count represents the size of the vertical sides, and the columns count represents the length of the diagonal sides.

'entry'

default value: [rand(), 1, 1]. The entry point [column, row, level] of the maze. Columns, rows, and levels all start at 1. Currently only the column value is used, the other values are set to 1.

'exit'

default value: [rand(), rows, levels]. The exit point [column, row, level] of the maze. Columns, rows, and levels all start at 1. Currently only the column value is used, the row value is either calculated if form => 'Hexagon' or set to the last row number, and the level value is set to the last level number.

'upcolumn_even'

Default value: 0. Determines whether, in a {cell => 'Hex', form => 'Rectangle'} maze, the first (and third and fifth..) column is the upwards column, or if the second (and fourth and sixth...) column is upwards. By default, the odd number columns are the ones shifted upwards.

This parameter will be ignored for the {cell => 'Quad'} mazes, and is set automatically for the {form => 'Hexagon'} mazes, as the center column is always the 'up' column for such mazes.

'start'

default value: [rand(), rand(), rand()]. The random walk's starting point [column, row, level] when making the maze. Columns, rows, and levels all start at 1.

'fn_choosedir'

Default value: internal function. Reference to a function that selects a single direction from a list, which is used to create the maze. The function expects a reference to an array of directions, and a reference to a three-element array that holds the column, row, and level number. A simple example would be

        sub first_dir
        {
                return ${$_[0]}[0];
        }

which would simply return the first direction in the array of directions, ignoring all else. If that's a little cryptic, it could also be written as

        sub first_dir
        {
                my($direction_ref, $position_ref) = @_;

                return ${$direction_ref}[0];
        }

If all directions were available, they would be passed in almost-sorted order: [North, West, South, East, Ceiling, Floor] for cell =>'Quad' mazes, [North, NorthWest, SouthWest, South, SouthEast, NorthEast, Ceiling, Floor] for cell => 'Hex' mazes. This would mean that first_dir() would always return North unless it wasn't on the list, whereupon the next available direction would be tried.

The direction values are available by using their variable names: $Games::Maze::North, $Games::Maze::NorthWest, $Games::Maze::West, et cetera.

'generate'

Default value: 'Random'. Currently read-only. The method used to generate the paths of the maze.

'connect'

Default value: 'Simple'. Currently read-only. The path connections. A simply-connected maze has only one path between any two points; a multiply-connected maze has one or more paths.

make

 $obj->make();

Perform a random walk through the walls of the grid. This creates a simply-connected maze.

solve

 $obj->solve();

Finds a solution to the maze by examining a path until a dead end is reached.

unsolve

 $obj->unsolve();

Erase the path from the maze that was created by the solve() method.

reset

Resets the maze cells to their clean, unbroken state. You should not normally need to call this method, as the other methods will call it when needed.

describe

 %maze_attributes = $obj->describe();

Returns as a hash the attributes of the maze object.

internals

 %maze_internals = $obj->internals();

Returns as a hash the 'hidden' internal values of the maze object, excepting the maze cell values, which can be retrieved via the to_hex_dump method.

to_ascii

Translate the maze into a string of ascii 7-bit characters. If called in a list context, return as a list of levels. Otherwise returned as a single string, each level separated by a single newline.

Currently, this is the only method available to view the maze. It uses underscores, both slash characters, and vertical bars to represent the walls of the maze. The letters 'c', 'f', and 'b' represent passages through the ceiling, floor, or both, respectively. The asterisk represents the path, which will only be present after invoking the solve() method.

to_hex_dump

Returns a formatted hexadecimal string all of the cell values, including the border cells.

If called in a list context, returns a list of strings, each one representing a level. If called in a scalar context, returns a single string, each level separated by a single newline.

EXAMPLES

 use Games::Maze;

 #
 # Create and print the maze and the solution to the maze.
 #
 my $minos = Games::Maze->new(dimensions => [15, 15, 3]);
 $minos->make();
 print "\n\nThe Maze...\n", scalar($minos->to_ascii());
 $minos->solve();
 print "\n\nThe Solution...\n", scalar($minos->to_ascii()), "\n";

 #
 # We're curious about the maze properties.
 #
 my %p = $minos->describe();

 foreach (sort keys %p)
 {
    if (ref $p{$_} eq "ARRAY")
    {
        print "$_ => [", join(", ", @{$p{$_}}), "]\n";
    }
    else
    {
        print "$_ => ", $p{$_}, "\n";
    }
 }

 exit(0);

AUTHOR

John M. Gamble may be found at jgamble@cpan.org

cpanm Games::Maze

perl -MCPAN -e shell
install Games::Maze