Welcome, as it were, to townmaze release 1.1.

Just typing "townmaze" at the command line will do an example maze for
you, once the program has been compiled and installed (see README).

Typing "townmaze help" at the command line will get you an error
message (Read it fast on a 25 line screen!) and then a  "usage"
display about 22 lines high, describing each of the parameters and
their limits.

You might want to try both of these before reading the rest of this
document.

What you see in a townmaze:

It should be obvious, but the symbols in the townmaze output are "#"
for walls or solid rock, "-" or "|" for horizontal or vertical doors,
and " " (blank), for streets and room interiors.

This program is not, in essence, a game, but instead a tool to use in
making games.  What it does is to lay out a city after the fashion of
the top level of Bard's Tale I.  You can then use this city layout in
either a paper and pencil dungeon crawling game, or as part the design
of a 3D computer dungeon crawling game. You can even (see
townpgmr.doc) install this code into such a game to create city maze
layouts on demand. 

Townmaze has a rich variety of parameters, to let you vary your city
in size, shape, building density, and complexity.  The parameters are
entered at the command line in standard Unix fashion, as "dash, flag
letter, space, value" sets, like

	townmaze -h 23 -w 77 -g 4 -l 2 -c 0 -u 0 -s 750 -r 123456789

Except for the "r" parameter, the values shown are the defaults, and
if the parameter and its value are omitted from the command line, the
above defaults are used.  The exception "r", the random number seed,
is read off the system clock unless it is overridden by a command line
parameter. 

Here is what the parameters mean.


 P A R A M E T E R S

 -h mazeheight         -- vertical size of the maze, in characters

 -w mazewidth          -- horizontal size of the maze, in characters

 -g mazegates          -- number of streets to start at the city wall

 -l leftgates          -- number of the gates to leave doors leading
                          outside from the city (the rest are turned
                          back into city wall)

 -c mazecourts         -- number of streets to start away from the city
                          wall in the city interior

 -u mazeunused         -- number of cells to leave unused (solid rock)
                          in the maze; these cells will be inaccessible

 -s mazestraightness   -- times per thousand to retry on average before
                          accepting a random cell that makes a street
                          turn rather than go straight

 -r randomseed         -- use to get the same maze again; replaces clock
                          seed; seed used is reported in the header for use
                          in a repeat run.

The maze is normally written to the screen (more exactly, to "standard
output"), and benefits a lot from screens that can show more than 25
lines and more than 80 characters; the more room townmaze has to work,
the better job it can do.  The maze is sized in characters, but it
really exists in cells, it takes several characters to draw a single
cell.  In the Bard's Tale I game, the main level was 32 by 32 cells.
In townmaze, that is a maze 65 by 65 characters, since it takes two
rows of characters to make each cell, plus one extra row for the last
wall, each way. 

Thus, a really effective way to use townmaze is to capture and print
its output on paper, to get bigger, more interesting mazes.

Townmaze will make a maze as big as your computer will provide the
memory needed for storing the maze and a corresponding list of cells,
and should fail gracefully if you ask for a maze bigger than your
computer can hold.

As mentioned, townmaze has a rich variety of parameters, and the best
way to understand what they do is to try them; they interact with one
another, so that there is no simple description of what results in the
maze as you vary each one, but here's an approximation. 

The -h and -w parameters just make the maze bigger; that's easy enough.

Townmaze works by building a maze that is solid room cells with no
doors, then changing a few room cells to street cells, then knocking
out more room cells to make street cells until all the streets are
connected and all the room cells have a door. Room cells get a door
when they are adjacent to at least one street cell.

The -g parameter tells how many of the starting street cells will be
on the border of the maze, next to the city wall.  To start with, each
of these cells is given a door which is a gate through the city wall.
Lots of these "gate" cells help break up the street that otherwise runs
all around the perimeter of the city to provide doors to the border
cells.

When the straightness parameter is very strict, rows of room cells
often run from each side of a gate toward the middle of town, like the
ones in Bard's Tale I did.  There need not be any gate cells at all,
in which case your town will have a street that runs all around the
outside.  Presumably then you would put the biggest treasures and
nastiest monsters in the middle of town, unlike Bard's tale, which put
them near the corners.

The -l parameter tells how many of the gates will survive; the rest get
turned back into city wall.  This lets you enjoy the complex border of
a city with lots of gate cells, without having lots of, or even any,
real gates leaving town.

A town maze must start with at least one street somewhere, so the -c
("courtyard") parameter lets you start streets in the interior of the
town, instead of the border.  Interesting things happen if you do 1
courtyard and no gates, and also if you do maximums of courtyards and
gates, and all other combinations.  In general, lots of courtyards
makes for a less dense, more "gangly" city structure with lots of
cul de sacs.

Townmaze with just those parameters tends to create long runs of rooms
snaking about the town.  To give more elaborate structures, and still
have all rooms accessible, it is necessary to leave some cells unused.
The -u ("unused") parameter tells how many unused cells to allow.  The
limit is low, because the rule is that a street cannot be adjacent to
an unused cell, which means unused cells make it hard to connect all
the streets together.  By forcing at least three cells between unused
cells, this connectivity is assured, but doing this means only about
2% of the interior cells can be unused cells.  Unused cells tend to
allow room structures with three or four "arms", rather than just
linear snaking structures, and give the town a more interesting
appearance.

The most important parameter affecting the appearance of the towns
designed by townmaze is -s, the straightness parameter.  It can take
values from 0 (don't worry about straightness) to 998 (try as hard
as possible to make streets run straight).  Townmaze implements this
straightness by repeatedly trying a random room to see if it will let
a street run straight, so straightness has a profound effect on the
time it takes townmaze to design a town.  A set of parameters that
allows a town to be drawn in a few seconds with a straightness of 0,
will take about the same number of minutes with a straightness of 996,
for example.

Nonetheless, the city streets wander around a lot, and knock out lots
of extra rooms, leading to sparse looking towns, until the highest
levels of straightness are used.  This isn't all bad, as the empty
space is like some of the big open courtyards in Bard's Tale I; you
can play with this parameter until you get the appearance you like.

The -r parameter allows you to generate the same town maze repeatedly.

If the townmaze program is installed with the HEADER definition turned
on, then above the maze output you will see a line showing the
parameters for this run, including "seed", typically eight or nine
digits.  If you feed this seed value back in as the value of the -r
parameter, you will get the identical maze again.  Even without the
HEADER turned on, you can enter your own choices of seed until you
find the town maze that suits your needs, then run townmaze again with
the same parameters to save the maze to a file, to print it, or, if
you install the software in a computer game, to be able to use a level
over and over without having to store its design explicitly in the
game. 

As of release 1.1, townmaze does lots of error reporting on parameter
entry, before dumping the usage display. There is a file called
townmaze.test (a csh or AmigaOS script) which will test every error
message from the parameter reading routine. It's kind of tedious, but
you might want to run it once to make sure your installation is working
as it was intended to do.

I hope you have fun with my toy.

Copyright 1991, Kent Paul Dolan,
PO Box 390755, Mountain View, CA, USA, 94039-0755