peng 0.32 - Portable Shiplist Compiler

Introduction

peng is a portable replacement for "Penguin": a program to manipulate VGA Planets™ 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.

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:

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™ 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:

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.