Format:WAD (Doom engine)
| Developer | id Software |
|---|---|
| Versions | one container layout since 1993; Hexen changes the map lumps (not covered here) |
| Magic | 49 57 41 44 ("IWAD") or 50 57 41 44 ("PWAD") at offset 0 |
| Extensions | .wad |
| Endianness | little |
| On this wiki | Facts · Code · Notes · Topics |
Container format of the Doom engine (Software:Doom, Doom II, Heretic, Hexen, Strife): a 12-byte header ("IWAD" or "PWAD", lump count, directory offset) and a directory of 16-byte entries naming flat, untyped data blocks (lumps). Maps, graphics, palettes, sounds and demos are all lumps; meaning comes from lump names, marker lumps and lump order.
Identification
Offset 0 holds IWAD (a complete game, "internal") or PWAD (a patch WAD that overrides or adds lumps). The next two little-endian int32 values are the lump count and the file offset of the directory. Engines treat both kinds identically once loaded; some refuse to start without an IWAD.
Structure
- Header (12 bytes): magic,
numlumps,infotableofs. - Directory:
numlumpsentries of 16 bytes:filepos(int32),size(int32),name(8 bytes, NUL-padded, not necessarily NUL-terminated when 8 characters long). The directory usually sits at the end of the file (true for the Freedoom 0.13.0 IWADs), but onlyinfotableofsis authoritative. - Lumps: raw data, no header, no compression, no alignment requirement. Zero-size lumps are used as markers and map labels.
Lump lookup
The engine concatenates the directories of all loaded files (IWAD first, then each -file PWAD) into one list and looks names up by scanning from the end, so the last lump with a name wins. That is the whole override mechanism. Only the requested name is upper-cased (stored names are compared as they are, see #Pitfalls); both are compared as two 32-bit integers, which shows up in disassembly as two 32-bit compares against a name copied into an 8-byte buffer.
Namespaces are delimited by marker lumps rather than by name: sprites between S_START and S_END, flats (64x64 floor and ceiling textures, 4096 raw palette indices) between F_START and F_END. Wall patches sit between P_START and P_END, but the 1.10 engine never reads those markers: it finds each PNAMES entry with a global name lookup, so a patch can be anywhere in any loaded WAD. The Freedoom 0.13.0 IWADs also nest P1_START/P1_END to P3_START/P3_END and F1_START/F1_END to F3_START/F3_END inside them; the engine only uses S_START/S_END and F_START/F_END and treats the nested ones as ordinary (empty) entries of the range, since it takes every lump between the outer markers.
Maps
A map is a zero-size label lump (ExMy in Doom and The Ultimate Doom, MAPxx in Doom II) followed by exactly ten lumps in a fixed order, which the loader reaches as label index + 1 ... + 10: THINGS, LINEDEFS, SIDEDEFS, VERTEXES, SEGS, SSECTORS, NODES, SECTORS, REJECT, BLOCKMAP. All coordinates are signed 16-bit map units; the loader shifts them to 16.16 fixed point. Fixed-size records:
| Lump | Record | Contents |
|---|---|---|
| THINGS | 10 bytes | x, y, angle (degrees), type (editor number), option flags |
| LINEDEFS | 14 bytes | start and end vertex, flags, special, sector tag, front and back sidedef (-1 = none) |
| SIDEDEFS | 30 bytes | x and y texture offsets, upper, lower and middle texture names (8 bytes each, - = none), sector
|
| VERTEXES | 4 bytes | x, y |
| SEGS | 12 bytes | vertices, angle (binary angle >> 16), linedef, side, offset along the linedef |
| SSECTORS | 4 bytes | seg count, first seg |
| NODES | 28 bytes | partition line, two child bounding boxes, two child indices (bit 15 set = subsector) |
| SECTORS | 26 bytes | floor and ceiling height, floor and ceiling flat names, light level, special, tag |
SEGS, SSECTORS, NODES, REJECT and BLOCKMAP are generated by a node builder, not by the map editor.
- REJECT: a bit matrix of
numsectors x numsectorsbits, row-major, LSB first: bits1 * numsectors + s2set means a monster in sector s1 can never see sector s2, so the line-of-sight check is skipped. A matrix of zeros is valid. - BLOCKMAP: a grid of 128x128-unit blocks for collision. Header of four
int16(origin x, origin y, columns, rows), then oneint16offset per block (in 16-bit words from the lump start) to a list of linedef numbers ended by -1 (0xFFFF). Node builders start every list with a 0, and the engine does not skip it, so linedef 0 is tested in every block. Everything is signed 16-bit, which limits the size of large maps.
Graphics
- Pictures (patches): used for sprites, wall patches, menus and the status bar. Header of four
int16(width, height, left offset, top offset), thenwidth32-bit offsets (from the lump start) to columns. A column is a list of posts: top row (byte), pixel count (byte), one unused byte, the pixels, one unused byte; a top row of 0xFF ends the column. Transparent areas are simply not covered by posts. - Wall textures are composed at load time from patches:
PNAMES(int32count, then 8-byte patch names) andTEXTURE1(plusTEXTURE2in registered Doom; the Freedoom Doom II-compatible IWAD has onlyTEXTURE1) list textures with their size and patch placements. - PLAYPAL: 14 palettes of 256 RGB triples (768 bytes each, 10752 bytes in all). Palette 0 is normal; 1-8 are the red damage/berserk tints, 9-12 the item-pickup tints, 13 the radiation suit tint.
- COLORMAP: 34 tables of 256 palette indices (8704 bytes): 32 light levels from bright to dark, the invulnerability map (32) and an all-black table.
- ENDOOM: 4000 bytes, an 80x25 text-mode screen (character, attribute pairs) shown on exit.
- Sprites are named
NNNNFRorNNNNFRFR: four-letter sprite name, frame letter (A = frame 0) and rotation digit (0 = all angles, 1-8 = views 45 degrees apart); the optional second frame/rotation pair reuses the same picture mirrored.
Tools that read/write it
- The engine's own
w_wad.c(GPL-2.0) is the reference reader; source ports (Chocolate Doom, PrBoom+, GZDoom) and editors (SLADE, Doom Builder) all read and write it. - A small standard-library Python inspector is on this wiki (see Code), tested against the Freedoom 0.13.0 IWADs.
Pitfalls
- The engine upper-cases the requested name, not the stored one; a PWAD with a lower-case lump name will not override anything.
- The
TEXTURE1record stores a 4-bytemaskedflag and an obsolete 4-byte column-directory pointer between the name and the patch count; readers that skip them misparse every texture. - A map's ten lumps must follow the label in the exact order; the loader does not check their names.
- Unverified (not checked here): Hexen-format maps, recognisable by a
BEHAVIORlump after the ten map lumps, use larger THINGS and LINEDEFS records; the record sizes above are for Doom-format maps only. - Quake's
gfx.wadand texture WADs are a different format, Format:WAD2 (Quake): the header has the same shape but the magic isWAD2and directory entries are 32 bytes, so this page's directory layout does not apply.
Evidence & references
- id Software DOOM source release,
linuxdoom-1.10/w_wad.h,w_wad.c,doomdata.h,r_defs.h,r_data.c,p_setup.c,p_sight.c,p_maputl.c,r_things.c,st_stuff.c(commit a77dfb9). - Runtime test: all 68 maps of the Freedoom 0.13.0 IWADs (
freedoom1.wad, SHA-256 7323bcc168c5a45ff10749b339960e98314740a734c30d4b9f3337001f9e703d;freedoom2.wad, a8772e088847032510d97ba2312406a6998f21cbab44d4ff10696faa9c0ecd4b) have lump sizes that are exact multiples of the record sizes above and REJECT lumps of exactly ceil(sectors^2 / 8) bytes; PLAYPAL, COLORMAP and ENDOOM have the sizes given above.