Witchaven & Witchaven II modding

If you would like to edit the Witchaven games, here is some help in doing so. The info here touches on all aspects of modding, although some are not well understood.

Witchaven II map editing

Compared to the first game, Witchaven II is convenient to edit. The editor is included with the game and good to go with all its features. The manual provides a fairly decent introduction to working with maps.

NAMES.H was not included with the Witchaven II release, but is a handy addition. (It will make BUILD show the internal names of tiles that have them, e.g. monster sprites that can be placed for functional monsters.)

The Witchaven II manual is in error about the map loading parameter, but such a parameter does exist. The correct parameter is "MAP #", e.g.

WH2 MAP 15

You can only load numbered maps in the form of LEVEL#.MAP, not arbitrary file names like Doom (and other games with good custom map support) allow. BME made a frontend that works around this, but it does so by swapping file names on the fly. You can also name your maps with level numbers higher than those included with the game. The game can load levels up to LEVEL999; at this point you're probably limited by DOS file name lengths. If you make sure to give every map set a unique block of level numbers (and have a note or batch file to correctly select the starting map number) it would probably be possible for quite a few maps and sets to coexist even in the vanilla game although I'm not certain that music will play correctly.

Corvin has been arranging an expanded and improved version of the manual's editing instructions on R.T.C.M.

Witchaven I map editing with BUILD 7 tools

I'm keeping this section for posterity, but you'd do much better to use the version of the BUILD editor that works directly with Witchaven, found in the patches and utilities section. Because the original Witchaven is based on version 6 of the BUILD format, there are some difficulties in editing maps with tools designed for version 7 (used by Duke Nukem 3D and later BUILD games), but these can be overcome.

Things that are needed:

  • A BUILD editor. The one from Witchaven II will work fine. Mapster probably works too but I haven't tried this. You need the TABLES.DAT that goes with it as well.
  • The utilities CONVMAP7 and BACKMAP6.
  • PALETTE.DAT and LOOKUP.DAT of Witchaven's palette in BUILD version 7 format. The utility TRANSPAL should be able to convert these. Using the ones from Witchaven II is possible but not recommended as a few of the palette swaps are different.
  • The Witchaven .ART files, and if editing or examining them is desired, the .MAP files run through CONVMAP7.
  • Optionally, the Witchaven NAMES.H which will let BUILD display special names for those tiles that have them (usually sprites which have special functions when placed.)

Once the above items have been gathered in a folder (NOT your main Witchaven folder, as this may impair running the game), editing may proceed according to the usual usage of BUILD. To edit a map, it must be in version 7 format, and to run it in Witchaven, it must be version 6. Swapping between the two is achieved through CONVMAP7 and BACKMAP6. One important note: the BUILD editor may allow you to put in slopes, but they are unlikely to work right after the conversion.

Graphic editing

Neither game includes a graphic editing tool on disc. For reasons currently unknown to me, the EDITART program from Duke Nukem 3D has trouble being run on the Witchaven resources; they load but the program text will appear garbled up.

Les Bird's source release for Witchaven II included a version of EDITART that appears to work with both games.

I have also had a reasonable time using the third party utility BastART instead, although it seems to be a rather sluggish program. Some other third party programs make too many Duke Nukem 3D based assumptions to be of use.

Music and sound

These are stored using a simple custom archive format. Basic tools to work with the archives are now available on the patches and utilities page.

Sounds are contained in JOESND for both games, while music is in SONGS for Witchaven I and both F_SONGS and W_SONGS for Witchaven II. Which of the two files in Witchaven II gets used appears to depend on what music card setting the game is put on; F_SONGS is used if (sMIDIHardware.wPort == 0x388), that is to say a Sound Blaster card as far as I can tell, otherwise W_SONGS is chosen. In Witchaven I the tracks for different sound cards are all lumped in the single file and selected for the sound hardware by track number.

The music is in HMP format, version 2 (HMIMIDIP013195). In Witchaven II, each of the 15 levels get four tracks; the first two are the regular music and the second pair are battle music. Some tracks are duplicated, for example the two regular music tracks for level 1 are duplicates of the same song. The "level 16" tracks are the menu music (duplicated four times).

Sound effects from JOESND are stored as a raw PCM and may be loaded using Audacity and loading the file with Import > Raw Data. The settings to use are unsigned 8 bit PCM, mono, and 11025 for the sample rate.

The last 4096 bytes of each archive contain the archive index. Each index entry is made up of 3 double words (32 bit values). This allows up to 341 entries plus a final four null bytes. Any unused entries are filled with null bytes.

For both types of archive, the first value in an index entry indicates an offset to the sound or song entry, but you need to multiply the value in the index by 4096 to get the real offset.

The second value is the entry's real length in bytes. Each file packed in the Joe archive is padded at the end with null bytes to reach the next 4096-byte division in the container file. Only the amount of bytes specified should be read.

For JOESND, the third value is the sound's priority (for deciding how important a sound is when playing multiple sound FX at once). For SONGS, the third value might be unused (appears always to be 9). Other archives might likewise ignore the third value.

In both Witchaven and Witchaven II's source code, the file SNDMOD.H attaches names to the sound index numbers. They are unnamed in the archives themselves.

GRP files

Support for placing the MAP and ART files in a GRP archive under the filename STUFF.DAT has recently been discovered by Corvin of R.T.C.M. GRP utilities for Duke Nukem 3D can work with these. To be investigated more fully; apparently there are some issues with reading the palette files out of STUFF.DAT. It's possible that this was an incomplete feature in the versions of BUILD used in these games.

Game behavior

Unlike Duke Nukem 3D, there are no .CON files to modify the game behavior. Therefore, it is only possible to alter it via DeHackEd style methods (for which no editor currently exists) or using a modified engine. EGwhaven now supports a RULES.CFG file that can be used to adjust a few game variables.