File	Date	Author	Commit
ChangeLog	2007-04-27	streu	[a28575] Uploaded version 0.32:
Makefile	2007-04-27	streu	[a28575] Uploaded version 0.32:
README	2007-04-27	streu	[a28575] Uploaded version 0.32:
README.html	2007-04-27	streu	[a28575] Uploaded version 0.32:
peng.1	2007-04-27	streu	[a28575] Uploaded version 0.32:
peng.c	2007-04-27	streu	[a28575] Uploaded version 0.32:
peng.dtd	2005-01-22	streu	[5d1c81] - added XML output format
peng.h	2007-04-27	streu	[a28575] Uploaded version 0.32:
peng.xsl	2005-01-22	streu	[5d1c81] - added XML output format

Read Me

                     peng 0.32 - Portable Shiplist Compiler

Introduction

   peng is a portable replacement for "Penguin": a program to manipulate VGA
   Planets(TM) ship lists and related definition files.

   It uses (almost) the same file format as Penguin 1.x and 2.x (you can feed
   Penguin input files into this one to get the same results), and can be
   used to compile ship lists for Host 3.x and PHost 3.x and later. Ship
   lists for earlier PHost versions must be pconverted, this program uses the
   normal DOS file format.

   In addition, peng contains a unique new algorithm to work around checksum
   problems.

  A word ahead

   This documentation assumes you know what you're doing. You can totally
   mess up a game by using bogus specification files. You will ruin the game
   when you do so in mid-game: most programs can't cope with ship lists that
   change behind their back.

   Remember the universal rule: Always make backups!

  Table of Contents

     * Usage
     * File Formats
     * File Contents
     * Checksums
     * Compiling
     * Versions
     * License
     * Program Author

Usage

   The basic command line format is

        peng [-options] [directory]

   Options must include one of -d, -r, -t, -X, -h or -V.

   +------------------------------------------------------------------------+
   | -d | --decompile        | Select decompile mode: convert ship list     |
   |    |                    | into a number of text files                  |
   |----+--------------------+----------------------------------------------|
   | -r | --recompile        | Select recompile mode: convert text files    |
   |    |                    | into binary ship list definition files       |
   |----+--------------------+----------------------------------------------|
   |    |                    | Select table mode: convert ship list into a  |
   | -t | --table            | number of tables, intended to be easily      |
   |    |                    | readable by players                          |
   |----+--------------------+----------------------------------------------|
   |    |                    | Select XML mode: convert ship list into a    |
   | -X | --xml              | set of XML files which can be postprocessed  |
   |    |                    | into HTML, new input files, etc.             |
   |----+--------------------+----------------------------------------------|
   | -h | --help             | Show brief help text and exit                |
   |----+--------------------+----------------------------------------------|
   | -V | --version          | Show version number and exit                 |
   |----+--------------------+----------------------------------------------|
   |    |                    | Increase verbosity. Specify many times to    |
   | -v | --verbose          | make it more verbose. Default is silent      |
   |    |                    | operation                                    |
   |----+--------------------+----------------------------------------------|
   |    |                    | Don't load existing ship list, make ship     |
   |    |                    | list from scratch. With -d, this just writes |
   | -f | --from-scratch     | out a set of blank template files, with -r,  |
   |    |                    | this compiles a ship list from complete text |
   |    |                    | files (i.e. the files must contain all       |
   |    |                    | items).                                      |
   |----+--------------------+----------------------------------------------|
   | -1 |                    | Select Penguin v1.x file format.             |
   |----+--------------------+----------------------------------------------|
   | -2 |                    | Select Penguin v2.x file format (default).   |
   |----+--------------------+----------------------------------------------|
   | -s | --single-file      | Select single-file mode.                     |
   |----+--------------------+----------------------------------------------|
   | -a | --allow-non-ascii  | Permit non-ASCII characters in names.        |
   |----+--------------------+----------------------------------------------|
   | -c | --ignore-checksums | Ignore checksums. See below!                 |
   |----+--------------------+----------------------------------------------|
   | -x | --extra-checksums  | Try extra hard making checksums. See below!  |
   |----+--------------------+----------------------------------------------|
   |    |                    | Spaces in data files become underscores in   |
   | -u | --use-underscores  | text files, and vice versa. This is the      |
   |    |                    | default in Penguin 2.x mode.                 |
   |----+--------------------+----------------------------------------------|
   |    |                    | Spaces in data files do not become           |
   | -U | --no-underscores   | underscores in text files, names are not     |
   |    |                    | modified. This is the default in Penguin 1.x |
   |    |                    | mode.                                        |
   +------------------------------------------------------------------------+

   Note that, in good old Unix tradition, peng does not output anything to
   the screen when everything is okay. You must use -v to see what's going
   on. On error, peng will output a message to standard error, and return a
   nonzero exit status.

   peng will only process complete ship lists. You have to give it all the
   .dat files, and all the text files for recompile mode. There's no way to
   process just the hullspec file, for example.

File Formats

   Normally, a ship list consists of five .dat files. Each of these files
   corresponds to a Penguin text file:

        +--------------------------------------------------------------+
        |  .dat file   |  text file  |       Contents        | Records |
        |--------------+-------------+-----------------------+---------|
        | beamspec.dat | beamdat.txt | Beam weapons          | 10      |
        |--------------+-------------+-----------------------+---------|
        | engspec.dat  | engdat.txt  | Engines               | 9       |
        |--------------+-------------+-----------------------+---------|
        | hullspec.dat | hulldat.txt | Starship hulls        | 105     |
        |--------------+-------------+-----------------------+---------|
        | torpspec.dat | torpdat.txt | Torpedoes             | 10      |
        |--------------+-------------+-----------------------+---------|
        | truehull.dat | truedat.txt | Hull/Race assignments | 11      |
        +--------------------------------------------------------------+

   The .dat files consist of a number of records, each defines one
   beam/engine/hull/torpedo/race.

   In single-file mode, all information is contained in one big single file.
   This may make manipulation of the ship list easier.

  Penguin v2.x Format

   Text files have a regular format, much like pconfig.src. For example, a
   hulldat.txt file might contain

 Hull            = 1
 Name            = OUTRIDER_CLASS_SCOUT__________
 Picture         = 9
 Tritanium       = 40
 Duranium        = 20
 Molybdenum      = 5

   Each line assigns a value. The first assignment, Hull=1 selects the hull
   we're talking about. For beams, torps, engines and truehull entries it
   would be an assignment to Beam, Tube, Engine and Player, respectively. The
   subsequent lines modify the hull entry. Note how spaces have been replaced
   by underscores. peng will convert these into spaces when reading the file.
   This conversion is done by default in Penguin v2 mode, for compatibility
   with Penguin. You can use -U to turn it off if you wish.

   You can assign to many records at once by specifying a range in the first
   assignment. For example, sadistic hosts would do

 Hull = 1,105
 Name = I won't tell you

   to name all ship types alike.

   Lines starting with a "#" sign are ignored (comments).

    Differences

   Penguin 2.x supports conditional and incremental assignments
   ("modifiers"). peng does not implement these, and I don't plan to add
   them. In my opinion, they're too much work for too little gain.

   peng does not ignore all whitespace as Penguin does, so you don't need to
   write underscores everywhere.

  Penguin v1.x Format

   The text files have a more unconventional but still quite regular format
   (actually, it is much less hassle to parse). For example, the above
   hulldat.txt entry would be

 Ship number >a[ 1 ]

 Hull name           >b[OUTRIDER CLASS SCOUT          ]
 Picture ID number   >c[ 9 ]
 Tritanium           >e[ 40 ]
 Duranium            >f[ 20 ]
 Molybdenum          >g[ 5 ]

   The funky >a[ foo ] constructs are what Penguin calls "assignment brace":
   The greater-than sign followed by a letter tells the shiplist compiler
   what value we're talking about, the value itself follows between two
   square brackets. Everything else is ignored, so you can easily add
   comments to your files. Just make sure your comments do not contain ">" or
   "[".

   The "a" brace always specifies the record number (1 is first), the
   following braces contain the actual values.

  General Notes

   Some fields contain text, most contain numbers. Just look at such a sample
   file to get the idea.

   peng does not impose any restrictions on the contents of the text files.
   In particular, you need not specify all values, and you need not do
   assignments in any particular order. When recompiling text files, peng
   reads the .dat files, and then processes the text files. When you just
   want to change a single value, you can thus just write that particular
   entry. To make the Outrider cost 50T, make a hulldat.txt file that just
   contains >a[1]>e[50] (v1 format). This is not recommended, though.

   By default, peng will not permit non-ASCII characters (umlauts, accents
   and such) in names. This is to maximize the portability of your ship list
   (remember that Planets is played on DOS, Windows and other operating
   systems that interpret these characters differently). If you wish, deep
   from your heart, to have these characters in your files, use the -a
   option.

   When you start recompilation from scratch (peng -rf), peng starts with
   everything zero and does not read the original specification files (maybe
   you don't have them at all). The text files should then contain all
   values.

   Table mode (peng -t) will write out four files hulls.txt, beams.txt,
   torps.txt and engines.txt in a compact, tabular format. When you made a
   new ship list, you can give these files to your players for reference or
   to print out.

   XML mode (peng -X) will write out five files hullspec.xml, beamspec.xml,
   torpspec.xml, engspec.xml, and truehull.xml. The required DTD peng.dtd is
   included with the peng distribution; the file format should be
   self-explanatory. You may want to use -U to get rid of underscores in the
   files. peng uses iso-8859-1 in the character set declaration, no matter
   what character set is actually being used. This causes the names to be
   passed through XML processors 1:1, even if they actually use some other
   encoding. If you use normal ASCII characters only, the character set
   declaration has no effect at all.

   peng cannot read XML files directly. However, the peng distribution
   archive contains an XSLT stylesheet peng.xsl which translates XML output
   into a v2-format input file.

  Single-File Mode

   peng 0.3 supports the new single-file mode. In this mode, peng does not
   use the individual files (hulldat.txt, engdat.txt etc.). Instead, all
   information is written to or read from a single file.

   Actually, peng will write to standard output or read from standard input
   in this mode. You have to redirect that using your operating system's
   shell. For example, the following command will decompile a ship list into
   a file plist25.txt:

 peng -ds >plist25.txt

   The following command will recompile that ship list into a set of
   specification files for VGA Planets:

 peng -rfs <plist25.txt

   Note the -s switch in both command lines.

   In decompile mode, peng will output the ship list with % section
   delimiters. For example, in v2 mode, the output file will start with

 % truehull

 Player  = 1
 Ships   = 1,16,4,6,5,17,9,104,10,13,3,11,12,8,7,18,20,105,0,0

   Here, % truehull is the section delimiter.

   In recompile mode, peng will read back such a file. The following section
   delimiters are accepted:

     * beams (beam weapon definitions)
     * engines (engine definitions)
     * hulls (hull definitions)
     * torps (torpedo system definitions)
     * truehull (hull/player assignments)

   Sections starting with an unknown delimiter (for example, %hullfunc or
   %phost) will be ignored. Although it is possible to use single-file mode
   with Penguin v1 format, it is recommended to use it only with v2 format,
   which is the default.

   In XML mode, peng will output one big XML document. Likewise, in table
   mode, one big text file will be made.

File Contents

   Note that peng does absolutely no checking whether what you enter is
   correct and will work. What you see is what you get.

  Beamspec, Torpspec

   The beamspec file defines the beam weapons, the torpspec file defines the
   torpedoes.

   Kill, Damage
           To interpret these values, you should know the combat formulas.
           For more information, see the PHost documentation (which is true
           also for Tim's Host). Note that, unless alternate combat is being
           used, the Kill/Damage values for torpedoes are doubled internally,
           so a 20/20 torp has twice as much impact as a 20/20 beam. In
           addition, beam effects are scaled with the charge status. Only the
           first salvo will actually use the values defined here, the next
           ones will have smaller impacts.

   Torp Costs
           The torpedo mineral costs are fixed to 1TDM. You can only specify
           the monetary cost.

  Hullspec

   The hullspec file defines the starship hulls.

   Picture Id / Picture
           This specifies the index into resource.pln resp. Winplan's bmp
           directory. Only use picture values here that already occur in the
           standard configuration. In order to know what pictures do occur in
           the standard ship list, just decompile it and see yourself. You
           can also poke around in Winplan's BMP directory and check the
           vplXXX.bmp files.

   Brace d / "Unused"
           Normally, there never is a d brace. The value at that place is not
           used by any part of the VGA Planets(TM) system. You can provide a
           "d" brace resp. an assignment to "Unused" if you wish.

   Masses
           Reportedly, certain Winplan versions will not believe that a ship
           has a mass of 5000 or more. So please make sure that no ship can
           be heavier than that. The maximum mass of a ship is Mass plus
           CargoSpace plus FuelTank (Unladen ship mass plus Cargo room plus
           Fuel tank capacity in v1.x terms), plus Beam weapons times mass of
           the heaviest beam, plus Torpedo tubes times mass of heaviest
           torpedo launcher.

   Special hull functions are not stored in this file. The original programs
   have hull functions hard-coded to certain hull numbers, some others use
   hullfunc.txt. The hard-coded functions are:

            Hull function                         Hull numbers
   Cloaking                        21, 22, 25, 26, 27, 28, 29, 31, 32, 33,
                                   36, 38, 43, 44, 45, 46, 47
   Advanced cloaking               29, 31
   Hyperdrive                      51, 77, 87
   Gravitonic Accelerators         44, 45, 46
   Bioscanners                     9, 84, 96
   Alchemy (3 Sup -> Mineral)      105
   Alchemy (Sup + Mineral -> Fuel) 104
   Alchemy (Sup -> Fuel)           97
   Terraform (heat to 50F)         3
   Terraform (cool to 50F)         8
   Terraform (heat to 100F)        64
   Decloaks                        7
   Glory device                    39, 41
   Gambling                        42
   Chunneling                      56
   Imperial Assault                69
   Ram scoop                       96

  Engspec

   This file defines the nine engines.

   Fuel usage
           The fuel usage is specified for each warp speed. The values give
           the fuel usage for a 100000 kt ship that moves one turn at the
           specified speed. The values generally tabulated are these values
           divided by Warp^2 (fuel usage per light year): that way, it is
           easier to see that a standard Transwarp Drive uses the same amount
           of fuel for each speed.
           In version 2.x format, you can specify nine assignments of the
           form FuelUsage = Warp, Usage.

  Truehull

   The truehull.dat file specifies for each player what hulls he can build.
   Each player can build up to 20 hull types.

   Each of the 20 slots for each player contains an index into the hullspec
   file (1 to 105). The hulls appear in the very same order as here on the
   ship build screen. So you should arrange the ships in order of increasing
   tech level, like in the standard list.

   When a race shall be able to build fewer than 20 hulls, the last slots are
   zero. There shall not be any zeroes in the middle of the list (note again
   that peng does not validate your input!). When you use v2.x format,
   assignments are automatically padded with zeroes. In v1.x format, you have
   to zero them out manually.

   A hull that has no "link" from truehull.dat can not be built. It can still
   exist in the game if someone (an add-on, perhaps) hacks it into the host
   data files, though.

   Master (universe creation) programs that give players free ships generally
   give them the first two ships from this list; you probably want to
   consider that when arranging slots.

    SRace / PlayerRace games

   Normally, the truehull.dat file is indexed by player number. In games with
   non-standard race assignments, the file must be modified accordingly: if
   player 1 plays Birds, he should get the Bird Men ship set, not the
   Federation set he would normally get.

     * SRace users follow the instructions from the SRace documentation.
     * PHost users can use peng to set up such a game. Just copy the
       PlayerRace assignment from pconfig.src to truedat.txt and recompile
       the ship list. peng will generate a modified truehull file.

   Note that, when all players use VPA and/or PCC in your PHost game, you
   need not modify your truehull file; you can instead simply enable
   MapTruehullByPlayerRace in pconfig.src and use a standard truehull file.

Checksums

   The specification files must fulfil certain checksums. Otherwise, the
   standard clients will refuse to use them. peng automatically tries to
   ensure that using the unused bytes in the files. If it exits with a
   checksum error, it was unable to find a combination of the unused bytes
   that yield a valid checksum. In that case, you have three choices (not
   necessarily in this order of preference):

     * Ignore the problem. When you invoke peng with the -c option, it will
       skip all checksum related stuff. The generated ship list will then
       probably not be usable by planets.exe and probably some other
       programs, too. Third-party clients generally have no problems with
       this.
     * Make peng try harder. When you invoke it with the -x option, peng will
       manipulate the files in a nonstandard way to achieve correct
       checksums:

          * it will modify the contents of the d braces ("Unused" values) in
            the hullspec file.
          * it will pad names with null bytes, not spaces. Strictly speaking,
            this violates the file format specs, but it works most of the
            time (as we know now, VPA older than 3.63 will not display ship
            build bills completely if your ship list requires lots of these
            spaces to fix the checksums).

     * Modify your ship list. When the checksum difference shown by peng is
       positive (i.e. the actual checksum is too big), do some of the
       following:

          * convert lower-case names into upper case
          * increase values just below 256/512/768 to just above

       When the difference is negative, do the opposite.

Compiling

   Compiling peng is pretty easy. There is no compile-time configuration. All
   you need to do is to type make. You probably have to edit the options
   specified in the Makefile when you are not using gcc. peng should compile
   with any ANSI C compiler.

Versions

   0.1 (June 2002)
           Initial version, Penguin v1 format

   0.2 (July 2002)
           Adds Penguin v2 format

   0.3 (January 2005)
           Adds XML format and single-file mode

   0.31 (February 2005)
           Adds long option names
           Fixes operation with 16-bit compilers

   0.32 (April 2007)
           Fix: -X quotes special characters correctly

License

   peng is (c) copyright 2002-2007 by Stefan Reuther.

   This program is free software; you can redistribute it and/or modify it
   under the following conditions:

    1. Redistributions of source code must retain the above copyright notice,
       this list of conditions and the following disclaimer.
    2. Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in the
       documentation and/or other materials provided with the distribution.
    3. All modifications to the source code must be clearly marked as such.
       Binary redistributions based on modified source code must be clearly
       marked as modified versions in the documentation and/or other
       materials provided with the distribution.
    4. The names of the program author(s) may not be used to endorse or
       promote products derived from this software without specific prior
       written permission.

   THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS OR
   IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
   NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
   INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
   (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
   SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
   CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
   LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
   OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
   SUCH DAMAGE.

Program Author

   Stefan Reuther, software developer

   Email: Streu@gmx.de

   WWW: http://phost.de/~stefan/
   Here you also get Planets Command Center, a full-scale client program. But
   you already knew that, did you?

   I also try to read alt.games.vga-planets and maus.spiele.planets.

   The templates for decompiling (-d) have been stolen from Penguin. Penguin
   is a freeware DOS program that does the same as this one, by Christopher
   Stewart. The table templates (-t) have been heavily inspired by the PList
   documentation.

     ----------------------------------------------------------------------

    Stefan - Streu@gmx.de

   Last modified: Thu Apr 26 21:53:17 CEST 2007