wadptr - compression tool for .wad files
wadptr [options] [ -c | -u | -l ] wadfile...
wadptr is a tool for compressing Doom .wad files. It takes advantage of the structure of the WAD format and some of the lumps stored inside it to merge repeated data.
wadptr has three separate subcommands:
List contents of the specified WAD, showing detail about which lumps are compressed or merged with other lumps.
Compress the specified .wad file.
Uncompress the specified .wad file.
wadptr has several additional options:
Write the output .wad file to the given filename, instead of overwriting the original file.
Quiet mode. Normal output that is printed when compressing or decompressing files is suppressed, making wadptr work more like a normal Unix tool that only prints output when an error occurs.
Disables WAD lump merging (see the compression schemes section below). Cannot be used with uncompress mode.
Disables sidedef packing (see the compression schemes section below). In uncompress mode, this disables sidedef unpacking.
Disables graphic squashing (see the compression schemes section below). In uncompress mode, this disables graphic unsquashing.
Disables blockmap stacking (see the compression schemes section below). In uncompress mode, this disables blockmap unstacking.
Enables extended BLOCKMAP size limit, for WADs targeting limit-removing source ports. This effectively doubles the limit, but the resulting lump will not work with vanilla Doom.
Enables extended sidedef count limit, for WADs targeting limit-removing source ports. This effectively doubles the limit, but the resulting lump will not work with vanilla Doom.
Print version number.
The following are some brief technical details about how wadptr's .wad file compression works:
WAD files sometimes contain the same lump repeated multiple times. An example is that in doom2.wad, some of the music tracks are repeated for multiple levels (eg. D_ROMERO and D_ROMER2). Since the WAD directory format contains a pointer to the location of the lump within the .wad file, multiple lumps that contain the same data can be merged to point to the same data. This behavior can be disabled using the -nomerge option.
Doom's levels are constructed out of lines called linedefs. Each linedef can have one or two sidedefs which contain data about which texture to show on that side of the linedef. Since it's common for many linedefs to use the same textures, these identical sidedefs can be merged and shared by multiple linedefs. This behavior can be disabled using the -nopack option.
Doom's graphics format splits images into vertical columns. A table stores the offset of each column within the lump. Sometimes an image can contain the same identical column multiple times. These identical columns can be merged together and the table offsets changed to point to the same data. This compression scheme works most effectively on images that are either very simple, based on repeating patterns, or those containing flat fields of a single color. This behavior can be disabled using the -nosquash option.
A precomputed table named the blockmap is used for collision detection; it divides up each level into 128x128 blocks and indexes which lines appear in each block. Often, different blocks contain the same identical set of lines. This compression scheme saves space by merging identical blocks together. This behavior can be disabled using the -nostack option.
To see an example of wadptr used in a very effective way, see miniwad, a minimalist Doom-compatible IWAD file that is less than 250KiB in size:
When packing sidedefs, linedefs with special types always get unique sidedefs that are not shared with any other linedefs. This is to avoid problems with animated walls, such as:
Scrolling walls; if multiple scrolling wall linedefs share the same sidedef, these walls will all scroll faster than normal. Non-scrolling walls that share the same sidedef will also scroll unintentionally.
Wall switches; if multiple switch lines share the same sidedef, pressing one will animate all others.
wadptr's behavior is maybe excessively cautious in that it applies to any and all special lines, but since only very few linedefs in a typical level are special lines this is judged to be a reasonable tradeoff.
However, if wadptr repacks the sidedefs on a level that was already packed by another, less cautious, tool, the resulting sidedefs lump may be slightly larger than the original. While counterintuitive given the purpose of the program is to make WADs smaller, this is almost certainly what you want to happen; other tools that do sidedef packing less cautiously may cause unintended visual glitches to occur.
The -c command will compress a WAD file and the -u command can then be used to restore the original uncompressed file. However, the decompressed file may not exactly match the original file byte-for-byte. For example, some editors already pack sidedefs, and sometimes WAD files include junk data that wadptr will discard. If for some reason it's important to retain the original file, you should therefore make sure to to either back up the original file before using wadptr, or use the -o command line option to write to a different file.
For compatibility reasons, wadptr's blockmap stacking is deliberately very conservative. Far more aggressive techniques can be used to shrink blockmap lumps further, particularly for large levels that run up against the blockmap size limit. If you need this, check out ZokumBSP:
Some levels are so large that it is impossible to unpack their sidedefs or unstack their blockmap without exceeding the limits of the Doom level format. If this happens when uncompressing a level, "failed" will be shown in the program output for that lump and the original (compressed) lump will be copied into the output file unchanged. The -extblocks and -extsides command line arguments can be specified to use the extended limits instead of the vanilla limits, but the resulting levels will only work in a limit-removing source port.
Some level editors get confused by packed sidedefs. If your level editor has problems, use -u to uncompress the file before editing.
Here are some examples for how to invoke the program:
Compress foo.wad, overwriting the original file.
Uncompress foo.wad, overwriting the original file.
Compress foo.wad but write the resulting file to newfoo.wad.
Bugs can be reported to the GitHub issue tracker:
deutex(6), bsp(6), yadex(6), eureka(1), chocolate-doom(6)
wadptr was originally written in 1998 by Simon Howard as a command-line program for MS-DOS. Simon continues to maintain the project. The first version worked as an adjunct to deutex(6), but with the 2.x series it changed to a standalone tool. Andreas Dehmel ported the program to several different Unix systems and also to RISC OS. The source code was recently (writing in 2023) overhauled and cleaned up.
Doom is a first-person shooter (FPS) game released by id Software in 1993 that has consistently topped lists of the best video games of all time. It retains an active modding community to this day that continues to develop new levels and reinvent the game in new and amazing ways.
Copyright © 1998-2023 Simon Howard, Andreas Dehmel
This program 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.
This program 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.