armDeu 1.18b
============




Well... obviously it's not a full port. It's just the utter minimum required
to merge PWADs with the main WAD to get playable, standalone WADs. On PCs
this is usually done with DeuSF, a bare-bones Deu (as far as I understood it).
On RISC OS you can do that using armDeu now.


Credits:
--------
DEU was written by Raphal Quinet (quinet@montefiore.ulg.ac.be) and Brendon
J. Wyber (b.wyber@canterbury.ac.nz). The full source code is publicly available.

armDeu only uses a very small part of DEU, namely the files WADS.C and DEU.H.
My goal was not to port DEU (which would be a large-scale project), but to be
able to (finally!) build patched WADs on RISC OS. Therefore armDeu is command
line only and doesn't offer you any functionality beyond reading in WADs and
writing out patched WADs. On the bright side, the first release only took me a
couple of hours to build which amazed even myself. The current version 1.17
is another story, though.



News:
-----

The original version couldn't handle Doom2 WADs (the levels weren't updated).
I changed that and also most of the Deu code I used for armDeu. Things that
were added since the first release are configurable IO-buffers when building
WADs, elimination of duplicate lumps and handling/creating compressed WADs.
Also version 1.10 can create patch WADs (i.e. you can use armDeu without
specifying a main WAD).

Version 1.11 now just stores the lumps when building PWADs, without trying to
replace previous definitions. This proved vital for PWADs like AliensTC or
Mansion. Also you can filter lumps using patterns.

Version 1.12 can output raw binary data and fixes a small bug in the lump
pattern matching code (-r). The new switch -a # cuts the first # bytes of
each lump from the output which is handy for extracting sound samples where
the first 8 bytes are control information. So to extract all the sound samples
from the Doom2 WAD and write them into one big file called sample you could use
``armdeu doom2/wad -a 8 -or samples -r DS*''.

Version 1.13 now does proper sprite/flat/patch merging. I left that out for
a long time because DIY doesn't need this anymore, but this was a problem
if you created IWADs with PWADs containing sprite/flat/patch lumps that
weren't in the original IWAD (in some cases DIY couldn't merge the regions
properly anymore). This is now fixed.

Version 1.14 can also build PWADs from lumps (i.e. raw data). The lumpnames
will be the same as the leaf-names of the files, without the extension. All
arguments following a -l switch that don't begin with a '-' are interpreted
as lump names, same as -p does for patchwads.
Alternatively you can use a lump descriptor file where each line contains
first the filename and then (separated by space or tab) the lumpname. If
no explicit lumpname is given the leaf-name of the file without the extension
will be used. This is the prefered way to handle large numbers of lumpfiles
due to RISC OS' restrictions of command line length.
What's it good for? I used this mechanism to pack all the Hell Revealed demo
lmps into one huge compressed PWAD; handles much better than 50 separate
demo lmps...

Version 1.15 fixes a small bug in pattern matching code and includes a new
switch -m for listing all the map (level) names contained in the WADs
passed as arguments.

Version 1.16 recognizes directory entries pointing to the same lump and
maintains these multiple references in the output WAD. This was necessary
to avoid losing part of WadPtr's compression. If you use the switch -x
(for eXpand multiple lump references) the lumps are duplicated, i.e. old
behaviour.

Version 1.17 has hardly any new features. Its main purpose is a source
cleanup to prepare it for a GPL release. The cleanup consisted of the
removal of the remaining DOS-isms (``huge'' pointers, typedefs for
pointers etc) and some detail work (static declarations, const pointers).
I did change the way the WAD listings work on stdout, i.e. by default all
lumps are output in one go without waiting for keys; you can force stopping
the output every x lines using the new switch -n x, though (for the old
behaviour use -n 21).

Version 1.18 now uses the compression/decompression code I separated into
my fastlz library (this is just a restructuring, there are no new features).
This library comes as part of my Doom port DIY and can also be downloaded
separately from my homepage. Adapt the Makefile such that FASTLZDIR points
to the directory containing the fastlz lib on your system.

Version 1.18b: Bugfix caused by the separation of the compression code.
Version 1.18 couldn't build a compressed WAD from an already compressed
source anymore. Note you'll need the latest version of the fastlz library
to build armDeu yourself.




Usage:
------

armDeu [<mainWAD>] [OPTIONS]

where OPTIONS can be any combination of the following:
-d <dirfile>	directory of main WAD
-f <dirfile>	directory of first patch WAD
-m		lists all map (level) names in the WADs
-b #		set size of IO buffer to # kB
-e		eliminate duplicate lumps, keeping the last one
-o <newWAD>	write output to newWAD.
-or <file>	write output to raw binary file.
-c #		output will be compressed, # is the compression level
-p <patchWAD1> ... <patchWADn>
-l <lump1> ... <lumpn>
-lf <lumpfile>
-v		verbose output (print lumps during patching)
-r <pattern>	only write out lumps matching the pattern (see below)
-a #		suppresses the first # bytes of each lump in raw binary mode.
-x		expand multiple lump references.
-n #		set maximum number of lines to output before waiting for key.
-h		help

The main WAD is usually one of doom/wad, doomu/wad or doom2/wad. The output
produced by -o will be either a new main WAD if you specified a main WAD, or
all PWADs merged into one if you only specified PWADs. A patched main WAD
should have the same name as the input main WAD (so the Doom player can
handle it correctly), but you _REALLY_ should store it in another directory
because only a complete and utter idiot would overwrite his original WADs.
The patch WADs are a list of WADs that contain update information for the
main WAD. The list is terminated by the first argument starting with a '-'
(i.e. another switch) or when the argument list terminates. Therefore you can
swap the order of the arguments in basically any way except for one thing:
the main WAD mustn't be specified immediately following the patch WAD list.
-d creates a listing of the main WAD's contents and writes it into <dirfile>.
-f does the same for the first PWAD. -b # lets you set the size of the buffer
in kilobytes to use when building a new WAD. The default is 1MB which seems
about right if you don't wanna completely screw your harddisc while building
something like Eternal III (result is 34MB). -e is new in 1.01 and means
``eliminate lumps with identical names''. This will a) safe space and b) make
sure everything gets replaced (-> problem in AliensTC).



Compression:
------------

Compression is a whole new story. Currently only the DIY M3 engine with the
minor update 3.1 can read these WADs and you must be really careful that you
don't try to use these WADs with anything else because it'll crash the player
big time. You select compressed output WADs (both IWAD and PWAD) by using the
switch -c #. # Determines the compression level and must be a number between
1 and 9. The bigger the number the more thoroughly armDeu will compress (at the
expense of speed). armDeu can also read in (and decompress) these compressed WADs,
so if you have a compressed WAD and you want to build the uncompressed one from
that you have to call armDeu like this:
``armDeu <compressedIWAD> -o <uncompressedIWAD>'' for IWADs and
``armDeu -p <compressedPWAD> -o <uncompressedPWAD>'' for PWADs.
Input WADs (IWAD / PWADs) can be both compressed and uncompressed WADs, there
are no restrictions. Compression speed is not too hot. It already uses some
smart tricks or it'd take a lot longer, but I don't feel like building a second
ZIP utility, so you'll have to put up with it. Compression rates are quite good,
typically within 10% of ZIP -9, but decompression in DIYM3.1 is a lot faster
than ZIP, which was the most important bit.
My main incentive was to make building a large number of third party WADs
cheaper on HD space. It should also be safe to compress your orignal WADs,
though. I tested the compression algorithm very thorougly and it seems
impossible that there's still a bug left in it. I compressed the WADs for
Ultimate Doom, Doom II, Eternal III and some others, decompressed them with
armDeu, compared the results with the originals and they were identical, and
we're talking around 60MB of data here. If you want to do similar comparisons
you have to take into account that the layout and lump alignment of your
source WAD doesn't have to be the same as the one output by armDeu. If you
want to check you have to build a ``clean'', uncompressed WAD from your
original WAD first and compare that with the uncompressed compressed one.
To build the clean one use ``armDeu [-p] <orgWAD> -o <cleanWAD>''.
Compressed WADs are identified by special header data in bytes 12-23 of the
WAD. In theory it's possible that an uncompressed WAD contains the identifi-
cation string there and is thus wrongly handled as a compressed WAD. In real
life this seems impossible, though, so I wouldn't bother. The identification
string is !COMPRESS00! BTW. As you can see there's room for 99 other compression
schemes, although I really don't think I'll implement another one.



Patterns:
---------

These are new in version 1.11. You can use patterns to filter lumps and make
sure only those fitting the pattern are output. That way you can easily extract
lumps for analysis.
A pattern is basically a simple regular expression. It can contain the following
elements:

*	any string
\*	any repetition of the preceding char / range
\&xx	the character code xx (hex)
\|	OR operator
\\	the character '\'
ranges	these are enclosed in \[ ... \] brackets. If the first character following
	the [ is a '!' then the range is inverted. Ranges are always case-sensitive.
	You can use the '-' character to specify a character range. If you want the
	character '-' you have to encode it using "\&2d".

All other characters are taken literally. Take care to use upper case characters,
because all lump names are upper case and patterns are matched case-sensitively.
Note also that when you're using a pattern the output will always be a PWAD, even
if the pattern is "*"!



Examples:

All Doom 1 levels:		E\[1-3\]M\[1-9\]
All DoomU episode 4 levels:	E4M\[1-9\]	or	E\[!1-3\]M\[1-9\]
All Doom2 levels:		MAP\[0-9\]\[0-9\]	or MAP\[0-9\]\*
All sound samples:		DS*
All player sprites:		PLAY\[A-Z\]\[0-9\]*
				(PLAY* would also select PLAYPAL)
Doom 2 maps 1,5, and 17:	MAP01\|MAP05\|MAP17

...you get the idea. You can't address the lumps within a level (THINGS, LINEDEFS,
SIDEDEFS...) directly! Instead extracting a level extracts all those lumps too.






Example:
--------

To build the AliensTC for Ultimate Doom you have to call armDeu with

armDeu doomu/wad -e -o Aliens.doomu/wad -p ALITCSF/WAD ALITCSND/WAD ALITCWAD/WAD



OK, I hope now you know what to do.



I successfully used armDeu to build the following alternative WADs:

- AliensTC for UltimateDoom
- Simpsons for Doom2
- Eternal III for Doom2 (This didn't work in the first armDeu release, the
  levels were completely screwed up. It definitely works now).




Contact:

	Andreas Dehmel
	<zarquon@t-online.de>
	http://home.t-online.de/~zarquon
