*****************************************
* HOW TO GENERATE YOUR OWN FORMAT FILES *
*****************************************

Update 5/13/01: In the 'Size' section, you may now also append a "b" or "h" to
the number to indicate that the text output of that varible should be in
binary or hexadecimal, respectively. See the readme.txt file for more info.

Update 5/12/01: In the 'Size' section of each variable, you may put an optional
"xNumber" clause to indicate that there are Number times of the variable in
a row (this is true for portrait pointers in units.dat). See the readme.txt file
for more info.

Update 3/31/00: I've added format files for all the .dats except for 
portdata.dat. But all of them except for images, units, flingy, sprites, 
sfxdata, mapdata, and upgrades only have 'dummy' entry lists right now. 
(They'll decompile, but you'll get the entries as 'Entry 000', 'Entry 001', etc.)
So your task is to find real entry lists and then put them in the correct spots. :)
And re-ID any variable names if they're wrong. (Formats should be 100% exact, since
they're from the EXE)

Note: this is for advanced users only (especially those who want to
help complete AZ :).

The format of the format files like 'units' is pretty simple. At the top
you can place notes to yourself/others or whatever. Then you need a line
with the following tag:

[INIT DATA]

After this tag you need to define two variables, numVars and numEntries.
numVars is the total number of variables there are in the .dat file
(total EVEN IF some of the variables are not used for all the entries).
numEntries is the total number of entries. (Not all variables have to
have values for every entry). I.E., for units.dat the numVars is 54
because there are 54 variables (at least that's what the EXE tells me :)
and numEntries is 912 (there are only 228 'real' units but the EXE says
that there are 912 values for some of the variables so that's what I'm
going with for now; it will probably change since the format may just be
wierd). So you'll have something like this:

[INIT DATA]
numVars=54
numEntries=912

After that you need to define all the variables in the .dat. Make a tag:

[VAR DATA]

and then fill in the data below it. Each variable needs 4 entries, a name,
a size, a number, and an offset. Something like this:

01Name=Graphic
  Size=1
  Numb=228
  Offset=0
  
It doesn't matter what you call the variables on the left-hand side, just
make sure they're in order and that you have 4 for every variable.
(and make sure all the variables are in the order in which the dat holds
them) So you could just as easily have the following:

myname=Graphic
thissize=1
number=228
startingoffset=0

But its a good idea to place a number in front of the first name to help 
you keep count.

The name is just the label that the variable will have in the produced
text files. Make sure you don't have trailing spaces; they will get read
into part of the name if you do (e.g., 'Graphic   ' will be read as
'Graphic   ' and is different than 'Graphic'). The size is the number of
bytes that each value of that variable type holds. Right now, only 1,
2, and 4 byte values (byte, short, double) are recognized. I don't think
you really need others, but I may be wrong. Number is the number of values
there are in the variable block. Usually this will be the same as the
numEntries value since you have one value for each entry, but sometimes
dat files only have some variables for some of the entries and not others.
Offset is the starting offset of the entries for which the variable should
start counting at. (Think of this as the number of entries to 'skip' before
the variable starts) Normally the offset will be 0 since the variable
starts at the first entry (and thus skips 0). But for some dat files, like
sprites.dat, some of the variables will not be present in the higher 106
or so entries, so the offset would be 106.

Here is an example for a hypothetical 'Stupidity' variable that is held by
96 units but skips the first 4 units (Terran Marine, Terran Ghost, 
Terran Vulture, Terran Goliath) -- and thus is present on unit number
4 to unit number 99 (if we start counting units from 0). And this variable
is 2 bytes long:

09Name=Stupidity
  Size=2
  Numb=96
  offset=4
  
Finally, after all the variables are entered, you need a entries tag:

[ENTRY DATA]

and then below that you need to fill in all the entry names for each entry
in this .dat file. E.G. for units,

0=Terran Marine
1=Terran Ghost
2=Terran Vulture
3=Terran Goliath
4=Goliath Turret
5=Terran Siege Tank (Tank Mode)
6=Tank Turret (Tank Mode)
7=Terran SCV
8=Terran Wraith
.
.
.

Again, the stuff on the left-hand side are ignored and are only there to
help you keep count. you could just as easily have:

=Terran Marine
=Terran Ghost
You're Special :)=Terran Vulture
=Terran Goliath
.
.
.

Or something like that, but you would probably loose count somewhere. List
files for entries to dats are abundant alread. Look for them in other CS
programs or on the net. It'll save you a lot of work. :) Also, make sure
you don't have any duplicate variable and/or entry names. And no '=' signs
in names and make sure they're less than 63 characters long. Again, be
sure NOT to place trailing space after entry names. And make sure they're
in order. But you already know that don't you? :)

That's all. I'll be adding optional marcos later (hopefully), but the
format won't change much (just additions to the top, if any) so you can
be sure that if you make one of these it will always work with future
releases of AZ.

- DI