CavGen3, by Blockhead aka Peter Capasso

	This is a random dungeon generator written in C.  It generates
cave dungeons for Morrowind.  Source code is included.  The output is a bit
monotonous but I've released it anyway just to show that cave auto-generation
is possible without having to make new meshes & NIFs.
	This is a command line (DOS) (windows console) program.  There is no
gui.  To use this program, it is assumed that you have a fair grasp of DOS
and are fairly comfortable with the Morrowind mod editor (TESCS).


Quick "I hate reading manuals" usage of CavGen
----------------------------------------------
	Make a new directory.  Put all the files in there.  Don't forget
espjoin.exe and txt2esp4.exe (separate downloads)!  Open a DOS and cd to that
directory.  Type

 cavgen3 my_dungeon 3 "My Dungeon"

	After it runs, type

 try

	After that runs, switch to explorer (or your favorite file manager)
and copy my_dungeon.esp to the data files directory off of Morrowind.  Load
it up in the editor and add doors connecting one of the cave dungeon cells
and the outside world.  Save it.  Exit the editor.  Run Morrowind.  Activate
the plugin.  Play.


	Now the longer more detailed information, for those not in quite as
much of a hurry.


Whats New
---------
	Version three adds the -l and -sl command line options, for vertical
multi-level dungeons.   A new command has been added to the INI file parser;
the "delete-temps" command causes the temp files to be deleted when the bat
file is run.


Installing CavGen
-----------------
	Make a new directory.  Unzip all files to that directory.  If you
haven't downloaded txt2esp4 and espjoin, go get them.  Put them in the same
directory with cavgen.  Open a DOS whenever you want to use cavgen.  Note, if
you have ImpGen, DaeGen, DweGen or Om_Gen already, you might want to keep the
cavgen files in that same directory.  ImpGen, DaeGen, DweGen, OM_gen, and
cavgen use separate INI files so there will be no INI file name collision.
The source for all the *gen programs all use a file called hacks.h but the
file is identical so don't worry about this file name collision when you unzip
the files.


Using CavGen
------------
 cavgen3 <base outfile name> <size> <base cell name> [-t] [-m] [-c] [-nt]
 [-l #] [-sl #]

where '#' represents a number.

	Base Outfile name is the name that you want to use for all of the text
files and esp files.  It must not have spaces in it.  Do not specify the file
extension ... cavgen will add that.
	Size controls the number of cells generated.  Setting this to 1 will
generate one cell.  Setting this to 2 will generate a dungeon three cells by
three cells, for a total of nine cells.  Take the size number, double it,
subtract 1, and then square it to get the total cell count of the output
dungeon.  Here's a table that ought to make it clearer (set your text reader
to a non-proportional font like Courier to see the table correctly):

 size  cells on a side  total cell count
 ----  ---------------  ----------------
  1           1                 1
  2           3                 9
  3           5                25
  4           7                49
  5           9                81
  6          11               121
  7          13               169
 99         197             38809

	99 is the upper limit.  You should never have to use that.  I'm afraid
to try it.  The dungeon would be too big.  It might not fit on the hard
drive.
	Base cell name is the cell name that you want the interior cells to
have in the game.  This base name, plus the cell coordinates, will form a
unique name for each cell.  This can have spaces in it, as long as you put
quotes around it.  If you do not uses spaces, quotes are not necessary.
	-t, -m -c, -nt -l -sl are optional command line switches to set
options for cave dungeon generation.  They can be used in any combination.
	The -t option turns off treasure generation.  When this is set, there
will be no crates, bags, small chests, etc. in the dungeon.  Any clutter that
is placed on top of crates (like those squat candles) will not be created
either.
	The -m option turns off monster generation.  When this is set, no
monsters are placed in the dungeon.
	The -c option turns off clutter generation.  This turns off anything
that is not monster or treasure.  When this is set, there will be no lights in
the dungeon (aside from lights on crates, if treasure is left on).  Version 2
of cavgen actually does not generate any clutter so this option has no effect.
This command line option was left in because I will eventually add clutter
generation to a future version of cavgen.
	Using all three options at the same time will generate a dungeon that
is a bare stone maze, ready for whatever manual decoration you wish to do!  :D
	The -nt (no twisty) option will force nub removal to always be 2
passes.  This results in almost all of the dead end corridors being removed.
This makes the dungeon less twisty but will help your in-game frame rate a
little bit.  Without the option, the program randomly determines the
twistyness for each cell.
	The -l option allows the dungeon to extend vertically down, similar to
the way GenMod works.  Any number from 1 to 99999999 is allowed, although I
would not recommend trying 99999999.  I haven't!.
	Note: the cell with coordinates (0, 0) will always have inter-level
connections.  Other cells only have a 1 in three chance of having an up
connection and and 1 in 3 change of having a down connection.
	The -sl option allows the number of the first level to be set.  So if
you want your dungeon to have levels 100 to 200, you'd type something along
the lines of:

 cavgen3 my_file 3 "My Dungeon" -l 100 -sl 100


	After running cavgen, you'll have one text file for each cell of your
dungeon.  There will also be a single list (.txt) file and a single .bat file.
If you run the bat file, it will call txt2esp4 and espjoin to convert all of
the text files into esp files and then use the list file join those esp files
into one final esp file.
	Move the esp file into the data files directory off of your Morrowind
directory.
	Now all you need to do now to play the plugin is add doors to and from
the dungeon (using the regular Construction Set).  The temporary text files
and temporary esp files can be deleted, as can the list file and the .bat
file.


Ini file
--------
	When cavgen runs, it looks for a file called "cavgen.ini".  The
program expects this ini file to be in the current directory.  It will run
without the ini file but will complain about it.  You may never have to change
this file, but in case you do, here is how it is laid out.
	The cavgen.ini file consists of five sections, "files",
"leveled_creatures", "crate", "bag" and "small_chest".  Each section starts
with its section name in square brackets and ends with an empty line.  There
must be an empty line between sections.  There must not be an empty line
between lines within a section.
	The files section can name *one* already-existing esp file to include
into your dungeon.  This is where you could create custom leveled creature
lists or containers in the regular TESCS editor that comes with the game.
The syntax is:

 include_esp_file yourEspfilenamehere

	Also in the files section is the "out_bat_file" command, which allows
you to specify the name of the .bat file that om_gen creates.  The
"out_list_file" command allows the name of the list file to be specified.
This name change will be reflected correctly inside the bat file.
	Also in the files section is the "delete_temps" command.  Putting this
command in the ini file will cause cavgen to write del commands to the bat
file to delete all of the temporary files except for the list file and the bat
file.  To not delete temp files, remove the "delete_temps" line from the ini.

	The leveled_creatures section allows you to specify up to 20 leveled
creatures, each on its own line.  The program will pick from among these with
equal priority.  So if you wanted one creature to appear more often, put it in
more than one time.  Only leveled creatures can be specified here, not
specific creatures.

	The crate section allows you to specify up to 20 crate container
objects.  Any container can be used, so long as it uses the same NIF as
crate_02_pos or crate_01_pos.

	The bag section is like the crate section, except bags (sacks, the
game calls them).  Again, as long as it uses the same NIF as com_sack_02_pos,
any container can be specified here.

	The small_chest section is like the crate section.  As long as it
uses the same NIF as chest_small_02_misc01, any container can be used here.


Known Bugs/Problems
-------------------
	The clutter generating routines that I have been using for all of
these generators don't work for caves.  I've removed the clutter generation
subroutines from cavgen2.  Eventually, I will write a new clutter generator
for a future version of cavgen.
	The treasure and monster placement is rather sparse.  This is because
the tile grid size for caves is large.  The cave 4way piece is 4 times the
size of the imperial & Velothi & Blue Mournhold tiles and two times the size
of the daedric and Old Mournhold tiles.  I'll have to recode the treasure
routines in a future version of cavgen.
	Caves made by cavgen are rather monotonous.  The addition of a new
clutter subroutine to add mushrooms, lights, and rock formations will
hopefully fix this in future versions.  As it is now, don't expect to just
run cavgen and have a fun dungeon: you'll need to add more clutter and lights
and ambience.


Legal Crap
----------
	Do whatever you want with it.  Upload/copy it where ever.  Just try
to mention my name if you can.  :)
	The program runs fine on my computer but your mileage may vary.  You
use this program at your own risk!


Extra Notes
-----------
	CavGen reads from and writes to a four byte file called
"seedhold.dat".  This is simply the random number seed from the last run, to
be mixed with the system time on the next run.  This file is also used by
txt2esp4.  The reason for this file is that the seed for the random generator
is gotten from a time function that only updates to the nearest second, so
that if you run a program twice in one second, both runs have the same random
number seed.  Use of the seedhold.dat file gets around this.
	Other dungeon styles (tile sets) have been created as separate
programs, because they each vary the algorithm in little ways.  To write a
general algorithm would be a pain in the neck and would invite error.
	Feedback, comments, etc. on CavGen are best posted on the Elder
Scrolls forums in the mods & plugins section.
	This is version 2 of the .c program.  Unlike ImpGen, this program was
not ported from a POV-Ray script (it was instead copied from daegen3.c and
then modified).
	I could not have created this program without the Morrowind ESP
Format file that was created by Erik Benerdal and Jim Adam.  Thanks
guys!
	Thanks to Jim Adam for creating GenMod, which inspired this program.
If you have not already downloaded it, go get it!  It's up to version 2.1 as
of this writing and more features are planned for version 2.2.
	Thanks to all of the suggestions/comments from the crowd on the
Bethesda modding forum.  :)

