QPakMan 0.66 README

by Andrew Apted. October 2008

INTRODUCTION

QPakMan is a command-line (text only) program for managing the PAK and WAD files used by the games Quake, Quake II and Hexen II.

COMMON TASKS

1. Listing the contents of PAK and WAD files:

   qpakman -list pak1.pak qpakman -list gfx.wad

Shows all the lumps contained in the PAK or WAD file. The first big number (prefixed by +) is the offset of the lump (in hexadecimal) and the second number is the lump size.

In the WAD format there is a type letter for each lump, shown after the size and before the name. Here is a list of all the types (only 'M' and 'P' are common) :

  M  :  Miptex texture
  P  :  PIC image
  x  :  unknown / invalid

  C  :  Color palette
  L  :  Label
  S  :  Sound
  T  :  QTex

2. Unpacking a PAK file:

qpakman -extract pak0.pak

The entire contents of the PAK file are extracted into the current folder. If a file already exists, it will NOT be overwritten (unless the -force option is given).

Certain files (such as Quake LMP files, Quake II WAL files) will be converted to PNG image format during unpack. This can be suppressed with the -raw option.

3. Creating a PAK file:

   qpakman FILES.... -o dest.pak

All the specified files are stored in a newly created PAK file. Folders can be given and their contents are recursively added to the PAK.

Certain files will be converted from PNG format to a custom format during the packing process. In particular, files in the "gfx/" folder are converted to LMP (Quake and Hexen II only), and files in the "textures/" folder are converted to WAL format (Quake II only). The -raw option prevents this.

[[TODO: palette.lmp & fontsize.lmp]]

4. Unpacking a WAD file:

   qpakman -extract textures.wad

The whole contents of the WAD file are extracted as PNG images into the current folder. If a file already exists, it will NOT be overwritten (unless the -force option is present).

Certain Quake texture names begin with a symbol which is not suitable in filenames, e.g. "*lava" or "+2shoot". Therefore QPakMan will convert them to a prefix (four letters and '_') while unpacking, and reconvert to a symbol while packing, as per the following table:

  *   star_
  +   plus_
  -   minu_
  /   divd_

There are also textures which contain "full bright" pixels, palette colors in the range 224-255 which are never drawn darker (e.g. in shadows). To support this feature, QPakMan saves textures containing full bright pixels with a "_fbr" suffix (for example "tlight03_fbr.png"), and will only use full bright pixels while packing if that suffix is present.

5. Creating a textures WAD:

   qpakman IMAGES... -o textures.wad

All the specified images are converted to MIPTEX (Quake's texture format) and stored in a newly created WAD file. Currently the input images must be in PNG format.

See the notes above about filename conventions.

6. Creating the GFX.WAD file:

   qpakman IMAGES... -o GFX.WAD

This stores the images as PIC format in a newly created file called "GFX.WAD" (upper or lower case does not matter). If you want to use a different output name, the -pic option must also be given to enable conversion to PIC format.

Conversion to PIC format uses all colors in the palette (no special treatment of full bright pixels).

7. Making a texture wad for editing:

   qpakman -maketex *.pak -o textures.wad

This creates a texture WAD which a quake editor (like Quark or GTKradiant) needs to work properly. You need to specify the PAK files for the full game (Quake I or Hexen II). It can also process individual BSP files.

COMMON OPTIONS

Options have a short form (like -g) and a long form (-game), it doesn't matter which one you use. Some options take a value or keyword after them, which must be separated from the option by a space (like: -game hexen2).

-g -game XXX This specifies which game the PAK or WAD is for. It sets the default palette and might affect how lumps are converted.

             Usable keywords are:
                q1   quake1   h2   hexen2
                q2   quake2   hak  haktoria

-c -colors XXX Lets you load a different palette than the default one (even when -game is used).

             Must be followed by a filename for the
             palette.  It can be either raw format
             (768 bytes) or text format (768 numbers).

-f -force Forces extracted files to overwrite any existing file with the same name. Normally QPakMan will not overwrite existing files when extracting from a PAK or WAD.

-r -raw Prevents conversion of lumps (especially from/to PNG images) while packing or unpacking a PAK file.

-p -pic When creating a WAD, stores the images in Quake PIC format instead of MIPTEX format.

             NOTE: this option is automatically enabled
             when the output file is called "gfx.wad"
             (or "GFX.WAD", case is not significant).

             NOTE 2: the CONCHARS and TINYFONT lumps
             are special, and are always created as a
             raw blocks of pixels.

LESS COMMON TASKS

1. Creating an inverse palette lump for Hexen II:

   qpakman -game h2 -o invpal.lmp

2. Creating an inverse palette lump for Quake II:

   qpakman -game q2 -o 16to8.dat

3. Making the tint tables for Hexen II:

   qpakman -game h2 -o tinttab.lmp qpakman -game h2 -o tinttab2.lmp

COPYRIGHT and LICENSE

Copyright (C) 2008 Andrew Apted

QPakMan is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

QPakMan is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

CONTACT DETAILS

Email: ajapted@gmail.com

Forum: http://openarena.ws/board/index.php?topic=1710.0