Text File
This is the readme file for
the first release of
WADCOMP.EXE and EXTRACT.EXE
(also includes LIST.EXE)
07-25-1995
Written by Serge Smirnov
(sxs111@po.cwru.edu)
Don't let the size of this document discourage you from looking at it. It's
provided mainly as a reference. A quick look at the sample .bat files may
well explain it all for you. However, do read the first two sections before
you try anything.
Table of Contents
-----------------
Disclaimer -- I am not responsible for anything...
Statement of purpose -- who and what the programs are for
List of files included
Program descriptions -- explains how they work in great detail
General usage notes -- applicable to all three programs
Known problems
Bug reports/comments -- how to contact the author
Credits
Copyrights/permissions
DISCLAIMER
==========
The programs included in this .zip file are freeware. Use them
however you like, but I am not to be held responsible for any damage they
do. YOU DO NOT HAVE MY PERMISSION TO USE THESE PROGRAMS FOR ANY PURPOSE FOR
WHICH THE LAW WOULD SUPERSEDE THIS DISCLAIMER. BY USING ANY OF THE PROGRAMS
YOU ARE INDICATING THAT YOU ACCEPT THESE TERMS.
ID SOFTWARE IS IN NO WAY AFFILIATED WITH THIS PROJECT, AND THEY CANNOT BE
EXPECTED TO PROVIDE ANY TECHNICAL SUPPORT FOR IT.
STATEMENT OF PURPOSE
====================
EXTRACT.EXE and WADCOMP.EXE are two utilities for compiling WAD files.
Together, these two programs should let you build a "custom" WAD file.
WADCOMP.EXE is the actual "compiler", and EXTRACT.EXE is a powerful tool for
extracting stuff from WAD files. You will find them especially useful if
you want to manipulates WADs in a way other programs won't let you. Since
these utilities work with directory entries (lumps), you can use them with
any valid WAD file, be it a Doom2 WAD or a Heretic WAD.
Although these programs can be used to simply extract a map from a WAD
file or group sevaral WAD files, you pretty much need to know a little about
the structure of WAD files to appreciate all of the features. For that
purpose, I recommend downloading and reading the first few pages of
The Unofficial DOOM Specs by Matt Fell, available as
ftp://ftp.cdrom.com/pub/idgames/docs/editing/dmspecs16.zip.
Also included in this distribution is LIST.EXE, which lets you view
the directory of a WAD file. There are many programs out there that do that,
and I am including mine only for your convenience, just in case you don't
already have one. Also, LIST.EXE will let you check if a WAD file contains
a certain entry in batch mode.
Two sample batch file are included to demonstrate the features of
EXTRACT.EXE and WADCOMP.EXE. REBUILD.BAT rebuilds your v1.666-1.9 DOOM.WAD
and eliminates the redundant sound entries (miraculously enough, it even
works with The Ultimate DOOM). SPRITES.BAT shows how you can emulate other
programs (e.g., nwt -as) using WADCOMP.EXE and EXTRACT.EXE. To test
SPRITES.WAD, I also created a small sprite replacement WAD called HUMANS.WAD.
It swaps the sprites for sergeants and former humans. To try it out, type
something like:
sprites \doom\doom.wad humans.wad \doom\tmp.wad
cd \doom
doom -file tmp.wad.
LIST OF FILES INCLUDED
======================
CUSTMWAD.TXT (this file)
EXTRACT.EXE
WADCOMP.EXE
LIST.EXE
REBUILD.BAT -- a demo batch file
SPRITES.BAT -- another demo batch file
HUMANS.WAD -- use it to try SPRITES.BAT
SOURCE.ZIP
PROGRAM DESCRIPTIONS
====================
If you invoke either WADCOMP.EXE or EXTRACT.EXE with no parameters,
it will give you the basic sytax and a brief explanation of every option.
This section explains the options in more detail. Note that you probably
don't have to read all of it.
EXTRACT.EXE
-----------
First of all, "extract" here really means "copy", so the input WAD is never
modified in any way. Also, although the examples in this section all use
doom.wad as the source file, there are absolutely no restrictions on the
input file, other than it must be a valid WAD file.
Usage: extract in.wad pattern [-{A|a}ENTRY] [-{B|b}ENTRY] [-wout.wad|path]
OR extract in.wad ENTRY [-{A|a}ENTRY] [-{B|b}ENTRY] [-wout.wad|fname.ext]
BASICS. The simplest syntax for EXTRACT.EXE is
EXTRACT.EXE filename.wad DIRENTRY
This command will try to open filename.wad and extract every entry whose name
matches DIRENTRY to a separate file. All entries are extracted as raw and no
conversion is performed.
*****************************************************
*** Note that DIRENTRY is CASE SENSITIVE, it will ***
*** not work if you specify e1m1 instead of E1M1. ***
*****************************************************
The DIRENTRY field can contain wildcards (? and *), so you can extract multiple
entries at a time. For example,
EXTRACT.EXE doom.wad DS*
will extract every sound effect contained in doom.wad.
The base file name of the file to which an entry is extracted is by
default the entry name. The extension is determined as follows:
if the entry is between S_START and S_END, the extension is ".SPR";
if the entry is between P_START and P_END, the extension is ".PTC";
if the entry if between F_START and F_END, the extension is ".FLT".
If none of the above is true, the entry name is examined:
if the entry name matches "D_*", the extension is ".MUS";
if the entry name matches "DS*", the extension is ".SND";
if the entry name matches "DP*", the extension is ".PCS".
See The Unofficial DOOM Specs for an explanation of why I chose these
extensions.
All other entries are extracted to .RAW files, except for entries that
match "E?M?" or "MAP??". These entries are special because they indicate that
the next few entries represent map data. Accordingly, they receive special
treatment. First, if such an entry is extracted, it is extracted to a WAD
file (E1M6 would be extracted to E1M6.WAD). Second, all subsequent entries are
also extracted to that file, until the program hits an entry whose name does
not match any of the following: "THINGS", "VERTEXES", "LINEDEFS", "SIDEDEFS",
"SECTORS", "SSECTORS", "SEGS", "NODES", "REJECT", "BLOCKMAP". These entries
are stored in the output WAD in the order they appear in the input WAD. For
example,
EXTRACT.EXE doom.wad E1M1
causes E1M1 and all the entries following it, up to but not including "E1M2",
to be extracted to E1M1.WAD.
EXTRACTING ENTRIES TO A WAD FILE. Although by default all entries except maps
are extracted to raw files, it is possible to direct EXTRACT.EXE to extract
everything to a .WAD file. For example,
EXTRACT.EXE doom.wad DS* -wsounds.wad
will extract all DS* entries to sounds.wad. The '-w' option affects the level
data as well.
EXTRACT.EXE doom.wad E?M? -wlevels.wad
will extract all the level data from doom.wad to levels.wad. In fact,
EXTRACT.EXE doom.wad * -wnewmain.wad
would have the same effect as
COPY doom.wad newmain.wad,
unless doom.wad contained holes, which would be removed.
SPECIFYING THE OUTPUT FILE NAME. If you wish to extract entries to a directory
other than the current directory, or if you wish to extract an entry to a file
other than the default filename for that entry, use the following syntax:
EXTRACT filename.WAD ENTRY outpath.
Whether outpath is a filename or a direcotry name is determined by whether
ENTRY contains wildcards. If it does, EXTRACT.EXE interprets outpath as a
directory name (e. g., c:\tmp) and attempts to extract files to that directory.
Otherwise, it thinks that outpath is a file name and attempts to create a file
with that name. Examples of proper use are:
EXTRACT doom.wad DS* c:\tmp
EXTRACT doom.wad TITLEPIC doomlogo.pic
NOTE: do not use this syntax in conjunction with the '-w' option. They are
mutually exclusive. Also, the following two commands will have the same
effect:
EXTRACT doom.wad E1M1 -wlevel1.wad
EXTRACT doom.wad E1M1 level1.wad
(that's because E1M1 is extracted to a WAD file by default).
EXTRACTING A RANGE OF ENTRIES. Sometimes it's useful to extract all entries
that come before or after a specified entry. An example of this would be
extracting sprites: the sprites are always between S_START and S_END. The
way to do so it is to use one (or two) of the following options:
-aENTRY -- process all entries after ENTRY;
-AENTRY -- process ENTRY and everthing that follows;
-bENTRY -- process all entries upto (but not including) ENTRY;
-BENTRY -- process all entries up to and including ENTRY.
In these options, ENTRY cannot contain wildcards.
By 'process' I mean 'look at it and extract it if it matches the pattern'.
That means you still have to specify a pattern (or an entry name). Here are
some examples.
EXTRACT doom.wad * -AS_START -BS_END -wsprites.wad
extracts all sprites to sprites.wad;
EXTRACT doom.wad * -AS_START -wgraphics.wad
extracts all entries from S_START till the end of file to graphics.wad;
EXTRACT doom.wad DS* -bS_START
extracts all DS* entries prior to S_START. This is probably better than
EXTRACT doom.wad DS*
because some sprites could match the pattern and be extracted as well, even
though they are not sound entries.
NOTE: As the first example shows, you can use '-A' and '-B' in one command.
You can also combine '-a' and '-B', or '-A' and '-b', etc. The only
requirement is that '-a' (or '-A') must come first. Also, you cannot use
both '-a' and '-A' (or '-b' and '-B'). It is your responsibility to make sure
that the entry specified in '-a' preceeds the one specified in '-b'. If that
is not the case, the '-b' option will have no effect.
Another use for this syntax is extracting map resources. The command
EXTRACT doom.wad THINGS
will extract ALL 27 THINGS resources, overwriting the file THINGS.RAW each time.
After it's done, you will always end up with THINGS from E3M9. To get around
this, you can instruct EXTRACT.EXE to ignore all THINGS resources not contained
in a specified range. Thus, to extract THINGS from E1M6, you would type
EXTRACT doom.wad THINGS -aE1M6 -bE1M7
WADCOMP.EXE
-----------
Usage: wadcomp [-I]outfname.wad { file[@[ENTRY]] | @ENTRY } ...
OR wadcomp [-I]outfname.wad -rrespfile
BASICS. WADCOMP.EXE builds a new WAD file, inserting everything you tell
it to. It will overwrite any existing file with the given name without
asking your permission. By default, it builds a PWAD, but you can use the
'-I' option to make it an IWAD.
The entries inserted into the destination WAD are specified on the
command line (or in the response file). Each parameter specifes a PWAD,
an entry, or a set of entries. You can specify as many parameters as you
can fit in one command line, and if that's not enough, you can put them in
a response file. The parameters are processed in the order they appear on
the command line (or in the response file).
Each parameter must be in one of the following formats:
(1) filename -- the simplest format. If filename is not a WAD file, it is
inserted as an entry whose name is the base file name.
Otherwise, every entry from filename is copied to the
destination WAD.
Examples:
WADCOMP mywad.wad c:\tmp\genmidi.raw
will create mywad.wad with one entry int it: GENMIDI.
WADCOMP mywad.wad *.raw
will create a WAD with as many entries as there are files
that match *.raw.
WADCOMP mywad.wad tmp\*.wad
will group all the WADs it finds in tmp.
(2) filename@ENTRY -- specifies the name of the entry that will contain the
data from filename. In this syntax, filename cannot contain
wildcards, since that could cause multiple entries with the
same name. The file is treated as raw regardless of whether
or not it's a WAD.
Examples:
WADCOMP mywad.wad e1m1.wad mywad.txt@INFO
will copy all the entries from e1m1.wad to mywad.wad and add
an entry called INFO with the contents of mywad.txt.
WADCOMP mywad.wad e1m1.wad@E1M1
will produce a WAD file with one entry, E1M1, which is
actually a copy of the WAD file e1m1.wad. I don't think
anybody would wanna do it, but the option is there. It
would be useful if you wanted to insert a raw file that
was unfortunate enough to start with "xWAD", where x is
any character.
(3) filename@ (filename can contain wildcards) simply forces EXTRACT to
treat all files that match filename as raw, even if some
of them appear to be WAD files.
Examples:
WADCOMP mywad.wad file01.raw@
is the same as
WADCOMP mywad.wad file01.raw@FILE01
(4) @ENTRY inserts an entry of length 0.
Example:
WADCOMP mywad.wad @S_START *.spr @S_END
would build a WAD file whose first entry is S_START, whose
last entry is S_END, and everything in between comes from
the files matching *.spr.
Since the program does not check for the length of
the entry name, it is possible to use '@' as a parameter by
itself. The effect of this parameter would be to insert
a 0-length entry with no name (technically the name would be
"\0\0\0\0\0\0\0\0"). That would be pointless, so consider
this option undocumented.
In the above explanations and examples, ENTRY should not be longer than 8
characters. If it is, it will be truncated and you'll get a warning. Also,
to give you more freedom, the entry name is never converted to all-caps.
I have yet to see a WAD that contains entries with lower case letters, and
I don't know how DOOM would react to them, so you should probably make all
you entries upper case anyway.
I know this can be annoying, but I wanted to make as few assumptions
as possible. At one point I assumed that all entry names would make valid
DOS filenames, only to find out that DOOM2.WAD has entries like VILE\5. So
what if some day somebody writes a DOOM-type game that uses both AA1 and aa1 ?
USING A RESPONSE FILE. Since WADCOMP.EXE is supposed to be a semi-universal
WAD compiler, it's a drag that DOS allows only 127 characters per command.
Hence, you can put all your parameters (except the output file name) in a
text file and tell WADCOMP to take its input parameters from that file. I
think this feauture is pretty much self explanatory. I jsut wan to point
out that I implemented it at the last minute, and my 'parser' is very
primitive. Therefore, avoid blank lines and trailing/leading spaces in the
response file.
HOW WADCOMP DETERMINES IF AN INPUT FILE IS A WAD FILE. Should this be of
interest to anybody, here's how it works. It does not look at the extension.
Instead, it checks to see if the file is 12 bytes or longer, and if it is,
reads in the first 12 bytes. Then it looks at bytes 2-4 of the file, and
checks if they are 'W', 'A', and 'D', respectively. If so, the program
decides it's a WAD file. Otherwise (file shorter than 12 bytes, or does not
start with "?WAD"), the file is assumed to be raw.
NOTES ON USING WILDCARDS WITH WADCOMP.EXE. If a parameter contains wildcards,
wadcomp attempts to insert every file that matches the path into the
destination WAD. The order in which the files are inserted is the order in
which DOS finds them. I think this is the order files are diaplayed in if
you type DIR with no ordering options. Sometimes the order is irrelevant,
but I remember at least one occasion where it seemed to make a difference.
I compiled a WAD that replaced all of the D_E?M? entries and D_INTER.
Somehow the order got messed up and DOOM crashed. Therefore, you should use
wildcards with caution.
If you find that the files you're trying to insert into a WAD are not
in the right order, I recommend copying them one by one to another directory,
in the order you want them stored. I don't know if this always works, but it
worked for me. Also, I've noticed that overwriting a file does not change its
place in the directory list. For more information on how DOS orders files
and how the FindFirst/FindNext system calls work, consult your local DOS guru.
GENERAL USAGE NOTES
===================
The stuff in this section is applicable to all three programs. First
of all, if a program bombs to DOS with a message that starts with the words
"system error:", it's not your system that's reporting the problem, it's
actually the program complaining about not being able to allocate memory,
write/read/close files, etc. If you see a message like that, it means one
of the following:
* The program ran out of memory. This really shouldn't happen unless
you try to compile a WAD with 4096 entries or more, but if it does,
let me know.
* The program could not read from a file. It probably means the file
is either corrupt, or not what the program thinks it is. It is
possible to confuse any of my programs by giving it a "WAD" file that
has the right header, but contains a pointer to a place past the end
of file.
* The program could not write to a file. A write protected floppy
or a full hard disk could cause it.
* Last but certainly not least, there is always a possibility that
you've found a BUG ! If you believe that's the case, E-mail me
and I'll attempt to figure out what the problem is.
Another thing that could happen is that one of the programs exists to
DOS with a "*** PROGRAM ERROR ***". That definitely indicates a bug, and
I'll fix it as soon as I can.
Since these utilities are meant to be suitable for use in batch files,
any abnormal termination or warning is accompanied by a non-zero exit code:
1 is returned if there were any warnings (symptomatic of incorrect
usage or missing input files); LIST.EXE also returns this value
if the specified input file does not contain the epecified entry.
2 is returned if a "system error" (explained above) occurs;
3 is returned on a "*** PROGRAM ERROR ***".
Any other non-zero value indicates a bug.
KNOWN PROBLEMS
==============
The following is a list of bugs I knowingly left in the programs at
the time of the first release. I did not bother to fix them because they
all seemed to be pretty harmless. Let me know if I was wrong.
* Both WADCOMP.EXE nor EXTRACT.EXE will crash if the output WAD has
4096 or more entries (the exact threshold number might be slightly
lower). The only easy way to fix this is to recompile the programs
using a DOS extender (e.g., DJGPP).
* When compiling a new WAD, if the destination file name matches one
of the source parameters, WADCOMP.EXE will insert the destination
file into itself. Under DOS, it usually becomes a 0-length entry
and doesn't hurt anything.
* The extensions EXTRACT.EXE gives to entries like S_START and S_END
are different. A _START entry gets the extension appropriate for
the entries that follow it, while the corresponding _END entry will
have ".raw" as its extension.
* SPRITES.BAT will not work if the source WAD file does not contain
an S_START lump. If you come across such a file, do the following:
wadcomp sprites.wad @S_START whatever.wad
sprites <main> sprites.wad <dest>
BUG REPORTS / COMENTS
=====================
If you believe you have found a bug in one of the programs, please
e-mail me at
sxs111@po.cwru.edu.
I cannot guarantee that I will fix everything pointed out to me, but I will
try to respond quickly. I may also supply additional information about the
source code if you request it. Feel free to send me any comments you have.
I'll be happy to know that somebody has actually looked at my programs. If
you must use regular mail, my address is
2365 Murray Hill Rd 620D Cleveland OH 44106.
CREDITS
=======
This project was made possible by the following people's efforts:
id sofware -- created DOOM
Matt Fell -- wrote The Unofficial DOOM Specs
Thanks to Michael Zoran for beta testing the software for me.
COPYRIGHTS/PERMISSIONS
======================
These programs are intellectual property of the author.
You are free to do whatever you like with the executables, as long
as you don't charge anybody for it. If you use a significant portion
of the source code in another program, please be kind and mention me
somewhere in the documentation. E-mail me at sxs111@po.cwru.edu with
any questions (I may give you my premission to include the executables
in a package that is not free, but only if you ask for it).
DOOM, MS-DOS, and Borland C are registered trademarks of their well
known creators.
PLEASE DO NOT USE THIS SOFTWARE TO MAKE WADS THAT WORK WITH SHAREWARE DOOM
