PENGUIN.EXE v1.2 August 1995

CONTENTS
========
1. Notice
2. Introduction
3. Installation
4. Note on data file management
        4.1 DATA.COM & Creating new data sets 
        4.2 DATA.COM & Changing to different data sets
5. Introduction continued
6. The basics: A description of each data file, and it's function  
        6.1 HULLSPEC.DAT
        6.2 TRUEHULL.DAT
        6.3 TORPSPEC.DAT & BEAMSPEC.DAT
        6.4 ENGSPEC.DAT
7. A note on checksums
8. Using PENGUIN

1. NOTICE
=========
Use these programs at your own risk. I will accept no reponsibilty for
lost data or damage.

Everything is free. I'm not the sort of worthless nobody that expects people
to pay $15 for something this ridiculously simple. :)

I'm not a lawyer, but I'm sure I have to say something like "VGA Planets 
is a game by Tim Wisseman" or somesuch ... and I just did


2. INTRODUCTION
===============
PENGUIN converts all the .DAT (data) files into specially formatted text 
files. You edit the text files at your leisure (in any ASCII text editor), 
and then use PENGUIN to convert them back into data files. The program
is very easy to use. However to get maximum effect from PENGUIN you should
read this whole document, and try to understand how it works.


3. INSTALLATION 
===============
Well PENGUIN doesn't actually need installing, you can put it anywhere you 
like. The only thing required by PENGUIN are these files:
HULLSPEC.DAT
TORPSPEC.DAT
BEAMSPEC.DAT
ENGSPEC.DAT
TRUEHULL.DAT

NOTE: You should make a backup of all these files and keep them safe.


4. NOTE ON DATAFILE MANAGEMENT
==============================
When playing a game of VGA Planets, you MUST use the same set of data files
for the entire game. If you change the data VGA Planets uses in the middle
of the game then there will be SEVERE problems. Most importantly the host 
program will go insane trying to figure out what is happening, and the Tim 
continuum will be out in force! (it will have the same effect on PHOST 
games). USE THE SAME DATA FOR THE EACH GAME, NEVER SWAP FILES MID-GAME!

This means you'll have to create a whole planets directory for each game of 
VGA Planets with different data files. This is fine if you don't mind having 
planets.exe (etc ....) duplicated all over your hard drive, but it isn't very 
efficient. If you don't want to waste your storage space then DATA.COM is 
here to help you! However is NOT needed for the operation of PENGUIN, so you 
don't have to use it at all.

To make DATA.COM work put it in the same directory as your PLANETS.EXE and
make a subdirectory called ALTDATA.

----4.1---- DATA.COM && CREATING NEW DATA SETS
Whenever you create a new set of data files pick an identification key to 
go with your customised data. The key must be 3 characters maximum, and can 
only use characters which DOS will accept in a filename.
Now type: DATA ADD <key>
For example: DATA ADD abc
DATA.COM will copy your custom data into the ALTDATA directory, and rename
all the files with your key as the extension. If you do this for all your
data then you will build up a small library of data, which you can switch
between.

----4.2---- DATA.COM && CHANGING TO DIFFERENT DATA SETS
To switch between the sets of data files in your library, just type:
DATA <key>
For example: DATA abc
Where key is the key you used with "DATA ADD". DATA.COM will replace the 
current data files with the data files associated with the given key.

I recommend you use DATA.COM with the ADD parameter now on the original data
files (the ones supplied with Planets). Use a key like "tim" (for Tim 
Wisseman) or something you'll remember easily. Now whenever you want to 
change back to the original files all you have to do is type DATA tim

The files that DATA.COM deals with are:
HULLSPEC.DAT
TORPSPEC.DAT
BEAMSPEC.DAT
ENGSPEC .DAT
TRUEHULL.DAT
XYPLAN  .DAT 

The first 5 files are the only ones dealt with by PENGUIN. The last file 
(XYPLAN.DAT) holds all the map information used by Planets. It is in 
DATA.COM because you might want to use different maps with different ships. 
There are plenty of good map editors around for you to make your own maps 
with. If you don't use alternative maps then don't worry about it, the normal 
map will be copied with all your data.


5. INTRODUCTION (continued)                                        
===========================
As you've probably gathered by now, I'm not a great writer. I am now going 
to try and explain how my program works, but I doubt I'll do a very good job. 
If you like PENGUIN, then do me a favour and rewrite this file for me. :)
My email address is at the bottom .... 

When I say "normally" what I mean is "if we are using the unaltered original
files". I think that's all.


6. THE BASICS: A DESCRIPTION OF EACH DATA FILE, AND IT'S FUNCTION
=================================================================

----6.1---- HULLSPEC.DAT
This file contains all the data about each hull. By data I mean things like
the amount of each mineral needed to build it, the number of crew, the size
of the cargo bay ..... etc.
There are 105 different hull slots. Each slot holds the data for one hull 
design and each slot has a unique number (from 1 to 105), the first slot 
is number 1 and the last is number 105. So when I refer to "hull numbers" I
am talking about the hull design held in that slot of HULLSPEC.DAT

I hope that isn't too confusing ... if it was then, trust me, it'll get 
worse! :)

Here is a little point you will need to note for later:
Hull number 1 is "normally" the OUTRIDER CLASS SCOUT. (It is normally the 
design held in the first hull slot of HULLSPEC.DAT)
Hull number 33 is normally the DETH SPECULA CLASS DESTROYER. Deth Speculas
are normally cloaking ships.

When we say that the Deth Specula can cloak, what we really mean is hull
33 can cloak. You might ask what's the difference .... well there's none
*IF* we're using the normal data files, but what if we swap the data in 
slots 1 & 33 around? 
Now the Outrider becomes hull 33, and the Deth Specula becomes hull 1. Is 
the Deth Specula still a cloaking ship? No. The cloaking ship will still be 
hull 33, even though hull 33 is now the design for an Outrider. You can try 
this for yourself, once you've read how.

----6.2---- TRUEHULL.DAT
This file holds all the information VGA Planets needs to decide which ships
each race can build. Each race gets 20 hull slots. Each hull slot holds a 
hull number. All 20 slots don't have to be used. For example: the Cyborg 
only use 15 hull slots. The remaining 5 are simply left as 0 (blank).
When you try to build a ship Planets looks at your race, then at all the hull 
numbers stored for your race in TRUHULL.DAT. If the hull number isn't 0 (and 
you have the minerals + money to build that hull number) it displays that 
hull for you to see.
This means that by changing the hull numbers stored in TRUEHULL.DAT you
can completely change which ships are available to each race.

NOTE: It would be wise to note that if you swap two hulls around in 
HULLSPEC.DAT (like we did in the previous example), the hull numbers 
will still be the same in TRUEHULL.DAT. So in the example from 6.1:
The Feds would still only be able to build hull 1 (now the Deth Specula), 
and the Bird Men would still build hull 33 (the cloaking Outrider). If 
you wanted the Federation to have the cloaking Outrider, then you would
have to change TRUEHULL.DAT so that under race 1 (the Feds) it had
hull number 33 instead of hull number 1.

----6.3---- TORPSPEC.DAT & BEAMSPEC.DAT
These two files hold all the information Planets uses for the weapons. 
BEAMSPEC.DAT holds all the beam weapon data, and TORPSPEC.DAT holds all 
the torpedo tube data. TORPSPEC.DAT also stores how much a torpedo of a
particular type costs.

There are 10 types of Beam weapon and 10 types of Torpedo tube.

----6.4---- ENGSPEC.DAT
This file holds all the data Planets uses for engines. This data includes
how much fuel each engine uses at each warp setting.

There are 9 types of engine.


7. A NOTE ON CHECKSUMS
======================
When Planets loads the its data it performs a checksum calculation on the 
files. If the result of this calculation isn't just right, then Planets 
will quit back to DOS and inform you that the data files have been tampered 
with.
Penguin automatically corrects the checksum when it saves new data files. 
Penguin uses an alogrithm which emulates the original files very closely, 
so Planets will never know the difference. However under certain (rare) 
conditions penguin will be unable to correct the checksum; Penguin will
advise you of what to do if such a situation should arise.


8. USING PENGUIN
================
Penguin has two modes; decompile and recompile. In decompile mode penguin
will convert HULLSPEC.DAT, TORPSPEC.DAT, BEAMSPEC.DAT, ENGSPEC.DAT and 
TRUEHULL.DAT into formatted text files. These text files can be loaded into
any ASCII editor (like EDIT.COM; the MS-DOS editor, or NOTEPAD; Windows text
editor). In recompile mode penguin turns all the text files back into
data files.
To run penguin in decompile mode type:
PENGUIN /d
To run penguin in recompile mode type:
PENGUIN /r

Here are the filenames of the converted data files:
HULLSPEC.DAT ------> HULLDAT.TXT
TORPSPEC.DAT ------> TORPDAT.TXT
BEAMSPEC.DAT ------> BEAMDAT.TXT
ENGSPEC .DAT ------> ENGDAT .TXT
TRUEHULL.DAT ------> TRUEDAT.TXT

To explain about these files, I am going to make up some imaginary data
and pretend it is part of HULLDAT.TXT (all the files use the same format,
so you can apply this example to any of them):
------ START OF EXAMPLE ------
Ship number >a[ 1 ]
            ^^^^^^^ this is an assignment brace. 
              
Hull name           >b[SQUINTY CLASS TRANSPORT        ]
                       ^^^^^^^^^^ some braces contain text (like this one)
Picture ID number   >c[ 1 ]                                              
                        ^ most braces contain numbers (like this one)
Tritanium           >e[ 10 ]
                    ^^^    ^ data ALWAYS goes between the 2 square braces 

Duranium            >f[ 10 ]
                    ^ this character tells penguin that the following
                      information is part of an assignment brace
Molybdenum          >g[ 10 ]
                     ^ this character is always a letter of the alphabet
                       and it tells penguin what type of data is in the
                       brace. This is assignment brace "g"
Cost                >q[ 50 ]
^^^^ A heading

END OF FILE
^^^^^^^^^^^ All the files end with this statement.
------ END OF EXAMPLE   ------

As you can see the file consists of a series of ASSIGNMENT BRACES. Each
brace encloses a piece of data.

The files are always produced with headings like "Cost", these are there 
to tell you what the data in the assignment brace is. They are NOT needed 
for penguin to recompile the data.

When recompiling penguin will ignore everything that isn't in an assignment 
brace. For instance this example could be rewritten as: 
>a[1]>b[SQUINTY CLASS TRANSPORT]>c[1]>e[10]>f[10]>g[10]>q[50]
Penguin will understand that perfectly well and recompile normally.

In my example I have "missed out" quite a few assignment braces. Assignment
braces "h" to "p" are not written in. This is perfecty ok. When penguin 
recompiles it will insert values from the current HULLSPEC.DAT file to
fill in the gaps. 

------ EXAMPLE ------
Hull number  >a[ 1 ]                   
Cost         >q[ 10 ]                  
------ END OF EXAMPLE ------

This would tell penguin that you wish to change the cost of hull number 1 
to 10, but leave all the other data the same.

To swap 2 designs around (hull, weapon or engine - it doesn't matter) all
you have to do is swap the numbers in their "a" (">a[]") braces. So to 
swap a Squinty class transport with hull 33 all you do is change the 
number in the Squinty's "a" brace to 33, and the number in hull 33's brace
to 1.
NOTE: for this to work you can't miss out any assignment braces on 
either design. All the braces between "a" and the highest brace for that
file should be there. The only exception to this is in HULLDAT.TXT; there
is NEVER a "d" brace (>d[]). This is nothing to worry about, it is 
deliberate. NEVER create "d" braces in HULLDAT.TXT.

To swap hull ownership lists (in TRUEHULL.DAT/TRUEDAT.TXT) you do the 
same thing, only you swap the race numbers.

NOTE ON CHANGING FUEL USAGE IN ENGDAT.TXT:
To find the actual fuel usage you must divide by the square of the warp 
speed. For example if it says:
Warp 9  >p[ 8100 ]
Then you must divide 8100 by 81 (the square of the warp speed, 9). This
gives you the number 100. Think of this number as the "efficiency rating"
of the engine; The higher the number the more inefficient the engine is
at that warp speed. In Tim Wissemans original data engines were never rated 
at less than 100 efficiency, but there is no reason why they can't be.

*********************************************************
* When editing the text files always follow these rules *
*********************************************************
1. You can add your own comments to the file anywhere EXCEPT between the 
   square braces.
2. You can write anything in the file, as long as it doesn't use any of 
   these three characters:

                "["     "]"   and   ">"

3. Don't play with the actual assignment braces. Although penguin has been
   written to cope with all sorts of oddities, it is better not to tempt
   fate. :)

4. Try not to put text in a number brace. This will have "unpredictable"
   results.

If you fail to follow these rules Penguin will probably crash. (it may
destroy all your data files as well)

***** END OF FILE

That's it, I can't think of anything more to say. I have gone over
everything in lots of detail, and I hope I haven't confused you. If I've 
made a mistake please tell me.

One last thing, I'd like to thank my beta tester Jeff Mitchell. There may 
have been more, but they never said anything so they don't get a mention :-)

Christopher Stewart
<cstewarta@cix.compulink.co.uk>
