Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:WAD (Doom engine)

From ReverseEngineering.wiki
Format
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: numlumps entries 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 only infotableofs is 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 numsectors bits, row-major, LSB first: bit s1 * numsectors + s2 set 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 one int16 offset 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), then width 32-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 (int32 count, then 8-byte patch names) and TEXTURE1 (plus TEXTURE2 in registered Doom; the Freedoom Doom II-compatible IWAD has only TEXTURE1) 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 NNNNFR or NNNNFRFR: 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 TEXTURE1 record stores a 4-byte masked flag 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 BEHAVIOR lump after the ten map lumps, use larger THINGS and LINEDEFS records; the record sizes above are for Doom-format maps only.
  • Quake's gfx.wad and texture WADs are a different format, Format:WAD2 (Quake): the header has the same shape but the magic is WAD2 and 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.