**************************
ARSENAL ZERO v. 1.2b README
**************************

by:      DI
contact: jp@magnus99.dhs.org
site:    http://www.camsys.org
         http://www.campaigncreations.com
license: GPL, see license.txt

Release Notes:

5/13/01 - Added a base expansion hack to allow representation of values in
          binary and hexadecimal (e.g., binary is useful for flags). In
          the azf format file, append a "b" or an "h" to the Size variable
          to have output of that varible be in that base (when in 
	  dat->text mode). In the editable text file, these values will
	  have a "b" or "h" appended to them. That indicates that they
	  are either binary or hexadecimal values respectively. See the
	  new "units" file for an example. BTW, the azf format files in
	  this package are the files with no extension like "units."

5/12/01 - Small hack to fix the problem with the wierd formatted varibles 
          in units.dat. Portrait vars work correctly now. The updated
          azf format file spec is this:

          In the size section of each variable, you may add "xNumber"
          where "Number" is the number of repeats. For example, the
          portraits section (I think) has 2 repeats in each var so
          you would put "size=2x2" meaning the var size is 2 bytes,
          but there are 2 of them for each unit. Similarily, the other
          variable which used to have 912 entries, really only had
          228, but had 4 repeats for each var (thus it is "size=2x4").

          In the text output files, they will appear as comma
          separated lists (e.g., "varName=1,2,3,4"). Simple enough.

        - I need someone to recompile the GUI version with Borland
          C++ Builder since I don't have that right now (this console
          version was cross-compiled for win32 on linux). The sources are 
	  in the arsenal-zero-bcb5proj.zip file). You *may* have to replace:

          "<strstream>"  with  "<sstream>"
          "strstream"    with  "stringstream"

	  in the files az.cpp az.h.

          (in that order, without the quotes). Just do a search and
          replace. This is because the headers I had named string
          streams differently than Borland's implementation. You will
          know you have to do this if you get lots of errors relating
          to strstream, etc. when you attempt to compile.

4/4/00 - I recompiled the source with Borland C++. 2 bytes smaller :) but now
         to also supports windows long file names. Not much to talk about
         but hey. :)
       - Mac users can also find a Macinosh port of AZ at:
         http://customs.macstarcraft.com/utils/
       - Compiled az.cpp with DJGPP, Borland C++ (command-line),
         MS Visual C++, and Code Warrior (all latest versions as of this date)
         Email me if you're still having problems.

This program is not meant for easy or simple use; it was meant to be stable
and versatile enough to be used by those who really need it and as a module
for larger programs. I have tried to include a little more 'step by step'
documention that appears when you run the program than most DOS applications
though.

Arsenal Zero (here on out, AZ) takes raw .dat files and generates a more editable
ini-like text file. So instead of a stream of bytes, you can edit something like:

[Marine]
Hit Points=402928
Shields=100
Armor=0
.
.
.

[Ghost]
Hit Points=23423
.
.
.

Etc. After you finish editing it, you can have AZ transform it back into a
normal .dat file.

**********
* USAGE: *
**********

az input_file format_file [-w][-r] [output_file]

Run the program with no arguments for further explanation. Basically you give AZ
an input file that's either a .dat file (with a .dat extention) or a text file
that was generated by AZ and also a format file which tells AZ how many variables
and entries are in the .dat and what their mneumonic names are. (As of v. 1.0
I've only included the format file for units.dat which is called 'units' -- no
extention, so just 'az myinputfile units' would use it correctly -- but you can
look at it -- its just a text file -- and make corresponding ones for the other
.dat files if you know the format) Example that works with the files AZ was
packaged with:

az units.dat units

This should generate a file called units.txt that you can edit. When you want to
transform it back into a units.dat file:

az units.txt units output_file.dat

Output file is optional, but if you don't include it AZ will write the binary out
as units.dat and overwrite the original unless you change the name of your text
file manually.

************
* EDITING: *
************

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) Ignore this if it didn't make any sense. :)

By default, when you generate a text file, there will be tips at the top about
editing it. Read them. :P In general, I tried to make the parser pretty friendly,
but I made it from scratch, so its not really all that sophisticated that it will
always 'do the right thing.' Try to say within the original bounds.

Remember: this is a text file! This means you can use all kinds of text editor
macros and other fun stuff on it. No GUI required. :)

Also, important to note that the values on the righthand side are the EXACT
conversions from their byte brothers in the .dat. This means that there will be
some values that will seem kind of wierd to you. For example, unit hit points in
units.dat is actually shifted 8 bits, so the value that shows up is 2^8 times
the actual amount that is shown in game. Also, you may have difficulty accessing
the bit-pattern flags like the special abilities (normally the check-box list
in Arsenal III). To edit them properly, you will have to look up a spec sheet,
calculate the bit-pattern yourself then convert it to decimal.

As I said, this is not for beginners! This is for people who need a non-corrupt
.dat file. Eventually I plan on writing a preprocessing macro that will do a lot
of the conversions for you, like shifting the hitpoint bits automatically and
separating out the bit flags. Hey, this is a text file; anyone can do it! :)
Finally, make sure you do not accidently delete a variable entirly for an entry
or have make a variable for an entry which isn't supposed to have one. The former
error will make the value default to 0, the later will probably cause a crash
when you try to compile. AZ WILL check that you have all the entries in the .dat.

(BTW, a units.dat file currently generates 912 entries with the ones past 228
basically empty except for 1 or 2 variables. This is not an error. This is the
format I ripped strait from the EXE, but I think that it reads some of these
sections specially, so I'll have to look into that further -- or someone could
help me ID that stuff -- see the 'units' format file for more info)

****************
* DISTRIBUTION *
****************

This program is GPL'd and the source code should have been included. Though this is
my first C++ program ever (and I mean EVER, I even skipped the tradition 
'hello world' gig :), I tried to leave it pretty portable so someone could write
a Mac port or something. The only thing really integrated is that I used file
streams to generate the input and output of the text/binary files. But you can
edit the other conveniently tagged I/O functions to completely change how the
interface is handled otherwise. Or, you can just use the Dat class I made, since
that really is the meat of the program. But it still uses file streams to get input
and output. (Yeah, I hate streams too, but I'm learning C++ remember? :)

(Now that I think about it, a Mac port might take a bit more work because the .dat
files are still stored in Little Endian notation on the Mac but the standard read/write
functions for file I/O might process the values in Motorola order... :| )

- DI
