txt2esp4
~~~~~~~~
by Peter C. Capasso

	This program reads in a text file (a script, if you will) and outputs
a valid esp file.  The syntax of the language is crude but effective.  This
program is intended for people who create mods and are comfortable doing 
programmer-like things.  :)
	The limitations of this program are simply this:

  1) Only one interior cell will be created in the esp file.  This can be
     gotten around by running the program with one script for each cell
     and then combining the plug-ins in TESAME.
  2) Only references to objects can be used.  New objects cannot be
     defined in the language.   This can be gotten around by defining them
     in a another plug-in and the combining the two plug-ins in TESAME or
     with espjoin.  This is not as bad a limitation as you would expect.
     Try running the sample script file through txt2esp3 and then view the
     results in the TESCS.

	A sample script "room_source3.txt" is included.  When run through
txt2esp3, this will yeild a plug-in containing a very small dwemer dungeon.
	My intent here is that someone out there who is good with dungeon
generating algorithms but who is bad with file format handling will find this
useful for their projects.  They can focus on the algorithm, just spit out
simple text files, and pass them to txt2esp3 to make esps, then combine them
in TESAME and have quicky-generated places to explore!


1. Usage
~~~~~~~~
	To use the program, pop open a dos shell and type

 txt2esp3 <input_file> <output_file> "new cell name"

where new cell name is your desired cell name.  This must be in quotes.


2. Language
~~~~~~~~~~~
	Here are the five commands in the language:

1 reference "object id" 1 <0 0 0> <0 0 0>
   This will create a reference to the specified object id.  Quotes must
   be around the object id.  This is followed by a float from 0.5 to 2.0,
   which is the scaling (resizing) factor.  This is followed by a 3-vector
   which indicates the 3-d rotation of the placed reference, in degrees.  The
   second 3-vector is the location of the reference.  Please note that
   commas are not used inside the vectors.  The coordinates of the
   3-vectors must be integers.  This command is used for references
   to these object types:
     static
     leveled creature (not just a creature)
     activator
     container
     non-teleporting door
     light
   
 2 npc_ref "npc object id" 1 <0 0 225> <384 304 -128>
     same syntax as "reference" statement, but used only for placing
     references to NPCs.

 3 creature_ref "creature id" 1 <0 0 0> <-704 -384 -127>
     same as "reference", but used for only for placing creatures.
     Do not use for leveled cretures

 4 tel_door_ref "door object id" 1 <0 0 0> <0 0 0>  <0 0 0> <0 0 0> "destination interior cell"
     Same syntax as the "reference" command except for the addition of two
     vectors and a quoted string.  The third 3-vector is the rotation of the
     destination marker (indicating its direction) and the 4th 3-vector is the
     location of the destination marker.  The quoted string names the
     destination Interior cell.  To teleport to an exterior cell, do not put
     the quoted string.

 5 ; this line is a comment
 
     A comment is a line started by a semi colon.  Note that a comment must
     be on a line by itself.  It cannot be combined with any other command.
     A command can not be broken into two lines.


3. shout outs
~~~~~~~~~~~~~
	This program was inspired by Jim Adam's genmod.
	Erik Benerdal's TESAME was used for checking the output of this
program and for ascertaining certain fine points of the esp file format.
	I could not have created this program without the Morrowind ESP
Format file that was created by Erik Benerdal and Jim Adam.  Thanks
guys!


4. Legal crap
~~~~~~~~~~~~~
	The source code is included.  Feel free to use it in your programs,
just mention where you got it!  Let's go make some mods!

Peter C. Capasso


5. difference from txt2esp3
~~~~~~~~~~~~~~~~~~~~~~~~~~~
	This newer version of the program now randomly sets the color and
brightness of the ambient lighting, sunlight, and fog.  The random number seed
is saved to a file ("randhold.dat") between runs.  The reason I did this is
that the random number generator is seeded by the time, which only updates
once a second.  When calling the old version of this program from a bat file
to make multiple cells, it would run so fast that some or all of the cells
were run with the same random number seed, which would result in all of the
cells having the same lighting and fog!  The stored random seed fixes this.



