DOOM User WAD Authors Working Group T. Neff In-Progress Specification: WIF-001 tneff@panix.com *** PRELIMINARY *** WIF: A Standard for Text-Based Interchange of DOOM WAD Files STATUS OF THIS MEMO This document defines a proposed format (WIF) for the interchange of playing level (WAD) files as used with the IBM PC game DOOM.[1] It extends and revises an ad hoc format (DWD) used by the developers of DOOM, adding features of use and interest to the community of user WAD authors worldwide. This memo is intended as a "working version" of the specification, to be amended and added to by the user community after discussion. It does not define an Internet standard. Distribution of this document is unlimited. 1. INTRODUCTION Since DOOM's release in 1993, it has become a popular game among users of the Internet and BBS's worldwide. DOOM's developers, id Software, provided a "hot patch" capability (via the -file switch) that lets players load supplementary object, map, graph- ic, and/or sound information. These binary patch files are called PWADs (or just "WADs"), and their format has been unoffi- cially documented in a separate publication.[2] Based on these specifications, more than half a dozen DOOM patch builder pro- grams ("WAD editors") have been written by users and distributed electronically, along with dozens (soon hundreds) of user-written WAD files created with them. More users are learning to write WADs (and even WAD editors) every week, and the new challenges thus created are attracting a lot of excitement. As useful as WAD files are, though, they have certain drawbacks for both the developer and the user. For one thing, they are binary files, with a complex inner structure. When distributed over the Net, they suffer from the perennial problem of binary corruption in FTP and BBS archives, and they must be "uuencoded" if they are to appear in Netnews postings. Many new users have trouble handling these files. Moreover, PWADs (as defined by id) have standardized provision for internal documentation or "binary comments," making identification harder when they are exchanged without accompanying text files. Finally, the present binary format does not lend itself to the creation or exchange of "pre- fab" structural components (stairs, towers, teleport chambers, WIF-001 (PRELIMINARY) page 1 etc) that would make life easier and more fun for casual or cooperative WAD builders. As a result, every WAD programmer who wishes to address these things must do so from scratch, in proprietary, non-extensible ways. Several mutually incompatible "comments" object formats already exist, for example. Meanwhile, the FTP upload archives are replete with plaintive graffitti: ... Apr 1 15:00 CHALLENG.WAD_is_corrupt_please_fix! ... Mar 29 06:43 What_is_DEADIMP.WAD? It turns out that Id Software already has a text WAD interchange format, created as a bridge between their NeXTStep development environment and the Intel 386 binary target. The "DWD" format simply specifies Lines and Things, and lets the final PC-based WAD builder determine Sectors and Nodes. (All WAD terminology in this document is taken from the "Unofficial Specs." Appendix B shows excerpts from a sample DWD file.) DWD files can safely be transmitted over ASCII-based networks, posted in Netnews articles and BBS messages, and interpreted to a limited extent by human browsers. But DWD lacks some features that a creative user exchange commu- nity needs. There is no provision for comments, which users need for recording authorship or identifying features of interest. No known DWD record format exists for encoding bitmap or sound data, although these are includeable in binary PWADs and have been distributed successfully. Worst of all, there is no "sectors" section as such: instead, the full description (Floor/Ceiling heights and textures, Type, etc) of each Sector is redundantly recorded, again and again, with every adjoining Sidedef! This does have the effect of making DWD entries order-independent and mergeable without renumbering (or at least it would if Tag numbers did not exist), but for DOS developers who are easily capable of renumbering when required, this is not worth the tradeoff. WIF, then, builds on the existing DWD format by adding section types for the features developers need, while modifying the Line and Sector description method to eliminate the redundancy, yielding more compact and unambiguous patch files. NOTE: Because some DWD source exists in public hands (such as the sample E1M1 file included with "DOOMBSP.ZIP"[3]), it is half- heartedly suggested that WIF-compliant programmers accept "clas- sic DWD" file format as a readable extension to the standard. 1.1. Notation In this document, line syntaxes often read like this: WIF-001 (PRELIMINARY) page 2 sectors : The way to interpret this is that everything NOT in angle brack- ets (<>) should be written exactly as is, and everything WITHIN angle brackets (and the brackets themselves) should be replaced by the appropriate parameter. So sectors : 201 would conform to the above syntax, with equal to 201. Sometimes, a substitution parameter will appear in braces: level : [name] This means that while and are REQUIRED parame- ters, is OPTIONAL and can be omitted if desired. 1.2. Required and Optional Features Some statements in this document are simple declaratives or use the word "must," for example: is a number in the range 1-9. The "#WIF" tag must be the first line in the file. These statements should be considered a REQUIRED part of the WIF spec, i.e., any WAD editor that does not behave that way is considered non-conforming. Other statements use the word "should" or "it is recommended": WAD editors should emit blanks instead of tabs. This means that it would REALLY HELP if conforming applications obeyed the suggestion, although it's understood that one or two might be unable to do so; they are then considered "minimally conforming" but could use improvement. And others just say "may" or (slightly stronger) "it is suggest- ed": WAD editors may use #comments to document level features. This means that an application can obey or ignore that statement without affecting WIF conformance, although it seems like some- thing that at least some applications would want to do. If any statement does not conform to this structure and its importance is not clear, please submit a comment. 2. THE WIF FORMAT WIF-001 (PRELIMINARY) page 3 2.1. Alphabet WIF files may be encoded in any locally supported character set (ASCII, EBCDIC, etc) but must at minimum support the ISO 646 graphic character set: ! " % ' ( ) * + , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? A B C D E F G H I J K L M N O P Q R S T U V W X Y Z _ a b c d e f g h i j k l m n o p q r s t u v w x y z including the blank " ". This is the character set used in the syntactically significant portion of WIF. Any additional symbols are permissible in comments, whitespace etc, but are not guaran- teed to survive translation to another WIF platform. It is suggested that WAD authors try to stick to general character sets like ISO-8859-1 and avoid nonportable symbols like the IBM PC "line draw" characters. "Tab" characters and blanks are treated the same and may be freely interchanged as whitespace. Because not all editors and platforms support tabs, WAD editors should use only blanks in WIF files they write. 2.2. Lines WIF files consist of one or more lines of text, separated by any valid local delimiting method (NL, CRLF, fixed length records, etc). Each line must be at most 80 characters in length, not counting the line delimiter. Because of the conflict in ASCII delimiting styles between UNIX and DOS, it is recommended that WAD editors accept either style on input, while outputting the delimiter appropriate to the local environment. 2.2.1. Comments All lines beginning with the pound symbol ("#") are comments. They may be ignored, preserved, or treated as special additional data by specific WAD editors. Example: #This is a Deathmatch level built by Paul Plasma. One special comment line begins each WIF file: #WIF Version 1 must be the *first line* of the WIF file. The symbols "#WIF" must be the first four bytes of the file, for filesystems sup- porting byte structure. The remainder of the line should appear as written above, although WAD editors may be liberal in their interpretation of whitespace and case matching. The version number ("1") specifies this version of the WIF specification. In WIF-001 (PRELIMINARY) page 4 future modifications of the spec, the number should be expected to change (increase). Comments may also follow the # symbol in-line after keyword and parameters: (3584,-3904) to (3536,-3904) : 1 : 0 : 0 # back of the room WAD editors may use either form (or both) of WIF comment conven- tion to document sectors, lines and sides during editing. In general, these comments should NOT be expressed in the resulting binary WAD file; see the "Info" keyword below for in-binary documentation. 2.2.2. Blank lines All blank lines are ignored syntactically, and may be preserved or ignored by WAD editors. Editors may choose to add blank lines before WIF sections (see below) or elsewhere as appropriate. No blank lines are permitted before the initial #WIF comment line (see above). 2.2.3. Line continuation Although most WIF line formats should not require it, lines may be "continued" by ending them with the backslash ("\") symbol. Everything from the backslash through the first *nonblank* character of the following line is assumed to be replaced by a blank. Example: Info : This is the test level we are working on for our \ Modem Deathmatch club. If you have any suggestions \ for new traps, contact the secretary, Paul Plasma. 2.2. Keywords Many WIF control lines begin with a Keyword, usually followed by a colon (":") and one or more parameters. Keywords always consist of alphabetic characters (A thru Z), with case ignored. (It is suggested that WAD editors emit lower case keywords, in keeping with DWD conventions.) Each keyword should begin in the first column on its line, and be followed (after optional inter- vening whitespace) by the colon. The colon is followed by any parameters. Examples: lines:475 info : A deathmatch E2M1 wad by Paul Plasma, pplasma@imp.com 2.3. Parameters WIF-001 (PRELIMINARY) page 5 Many WIF lines contain parameters (values) that define lines, sectors etc. These parameters come in two varieties: numeric and string. 2.3.1. Numbers All WIF numeric parameters are INTEGERS in the range -32768 to +32767. They are expressed as one to five digits, optionally preceded by the "-" sign. There are no floating point or frac- tional numbers in WIF. 2.3.2. Strings String values in WIF consist of one or more characters from the ISO 646 graphic set (see above). Most WIF strings should not need embedded blanks, but a few (like the option [name] on the Level keyword - see below) might do so. Quote marks should NEVER be needed in a WIF file for reasons of syntax. If a string is allowed to contain blanks, it must be the last parameter on the line. Texture names (see below) do not contain blanks. 2.4. Levels After the #WIF comment line, a WIF file consists of one or more Levels, each composed of several Sections (see below). Each Level begins with a directive as follows: level : [name] where is a number in the range 1-3 (as of DOOM 1.2, although the commercial version due in Fall 1994 may add more episodes) and is a number in the range 1-9. [Name] is an optional string that gives a new "level name," although at present there is no known way to override the names given by DOOM at level completion. Example: level : 3 5 Nightmare Alley 2.4.1. Anonymous levels / patch components If the level directive is OMITTED, then a WIF file is assumed to apply to *no level in particular* or to *any level* as the WAD editor sees fit. At most one complete level per WIF file can be encoded this way. The more common use of "anonymous" WIF levels would be for *patch components*, i.e., self-contained architectural elements or map sections which are stored in a level-independent form and loaded "on top of" actively edited levels by a WAD editor supporting this feature. For example, a "sniper nest" or "grand ballroom staircase" or "cacodemon flying wedge" could be built using a WAD editor and then explicitly saved as a patch component, for WIF-001 (PRELIMINARY) page 6 library storage, posting to the Internet, etc. Useful or interesting rooms or constructions could be exchanged in this way without having to provide the entire Level. Any number of such Patches can be concatenated into a WIF file, unlike complete "anonymous" levels. It does not appear necessary to provide explicit keyword support for patches at this time, but comments are welcome. 2.5. Sections After the Level directive (if any), each Level is composed of the following Sections, in order: [Info] Sectors Lines Things *In a complete level, all sections except Info are mandatory*. In a patch component, any section may be omitted, except that Sectors must be present if Lines are. Each Section begins with a keyword directive from the above list. Each directive consists of the keyword and (except for Info) a count of how many of that type of thing the Level contains. (See below.) It is strongly suggested that WAD editors write "dummy sections" (with just the keyword directive, and a count of 0) rather than omit sections on output. 2.5.1. The Info Section The Info section optionally allows the WAD author to supply some documentation to be stored in the binary WAD file itself, using one of the non-Id-standard "INFO" directory entry formats already in existence, or some new one to be agreed on by WAD editor authors. The section consists just of the Info directive, followed by one or more lines (with continuations) of explanatory text: info : [text] It is suggested that no more than 1-2K of Info text should be stored per level, to keep WAD sizes down. NOTE: WAD editors which do not support the binary INFO entry must skip this section without an error when writing a WAD file. They WIF-001 (PRELIMINARY) page 7 should retain the section in the WIF file itself, even if they do not write it to the binary. 2.5.2. The Sectors section This section lists all the sectors in the level, breaking out the per-side sector information from DWD into a separate list. It begins with a directive: sectors : where is the number of sector definition entries (not counting continuations) following. Following this directive are one or more sector definition entries of the form : : where and (numeric) and and (string) are the floor and ceiling heights and texture names, respectively; is the numeric light level; (numeric) is the sector type; and (numeric) is the Linedef (Trigger) tag, or 0 if none. For definitions of these terms, see the Unofficial DOOM Specs. Example: 100 : FLOOR4_8 172 : CEIL3_5 240 9 16 (NOTE: WAD editors must treat texture names in a case insensitive manner on input, since there is some case variation even in Id's own registered levels; they should use uppercase only for texture names on output.) The list of sector definitions establishes an ORDERING which will allow subsequent Side definitions to refer back to these sectors *by number* (0 thru N), so it is important that WAD editors do not rearrange, insert or delete sectors in this list without changing the associated Sidedefs. The "sector number" itself does not appear in the definition line, but WAD editors may wish to show it in a preceding or inline comment, to make human scanning of the WIF file easier, e.g., # Sector 34 - elevator to tower 100 : FLOOR4_8 172 : CEIL3_5 240 9 16 2.5.3. The Lines section This section defines all the Lines (including Sides) in a level. It begins with a directive: WIF-001 (PRELIMINARY) page 8 lines : where is the number of line definitions (not counting Side definitions) that follow. This directive is followed by number of definitions, each consisting of a Linedef followed by one or two Sidedefs. A Linedef consists of a line as follows: (,) to (,) : : : where , , , are the numeric X and Y coordinates, respectively, of the line's start and end points; is the numeric flags value; is the numeric line type; and is the Sector/Trigger Tag or 0 if none. (See the Unofficial Specs for an explanation of these fields.) Each Sidedef consists of a line as follows: ( : / / ) where and are the numeric X and Y offsets, respec- tively, of the textures applied to this side; , , and are the (string) names of the textures to apply to top, bottom, and middle (or "normal") surfaces of this side; and is a numeric index (0-based) into the preceding Sector section (see 2.5.2 above) for the Sector adjoining this side. (NOTE: This is an extension of the DWD format.) At least one Sidedef must be associated with each Linedef. If only one Sidedef is present, it is always assumed to be the "right" side. For convenience of reading and compatibility with existing DWD files, it is suggested that WAD editors include the optional whitespace before Sidedef lines, thus indenting them from their associated Linedefs. Example: (1344,-3104) to (1344,-3200) : 29 : 0 : 0 8 (0 : STARTAN3 / STARTAN3 / - ) 16 0 (0 : - / - / - ) 21 2.5.4. The Things section This section lists all of the objects (players, monsters, bonus- es, teleport exits etc) on the level. It consists of a directive things: WIF-001 (PRELIMINARY) page 9 where is the number of Thingdefs following. Then comes many Thingdefs, each of which has the format (, , ) :, where and are the numeric coordinates of the thing's location, is the direction it faces (0 to 359), is the number (1-????) of the type of Thing at that location, and is a numeric bitmask of which degrees of difficulty the object appears in, plus other bits for "deaf" etc. Example: (1056,-3616, 90) :1, 7 # player 1 start 3. FUTURE DIRECTIONS There are several enhancements to this specification that could be considered, depending on the needs and views of WAD editor developers. Some of them are outlined in the following section. 3.1. Tag descriptions One popular Windows-based editor has already introduced the concept of "Platform," whereby text descriptions are attached to individual Sector/Linedef "Tag" numbers (see 2.5.2 and 2.5.3 above). Unfortunately it rapidly becomes obvious that users confuse these Tags or "triggers" with the Sectors that use them, perhaps especially because "Platform" sounds like a raised section of floor. Since WIF allows extensive commenting of all lines, sides and sectors, it may be unnecessary to specifically attach comments to *triggers* as such, but if WAD programmers think it is worth it, a "Tags section" could be added. The only problem is that there would really be nothing worth saying in it except a list of comments! Another solution would be to settle on a comment format associated with the Linedef. More discussion is needed on this. 3.2. Mnemonics for Things/Flags/Types The DWD format used raw numbers for such things as Linedef flags; most WAD editors then decode these and express them as human readable abbreviations or mnemonics. Would it make WIF files more readable if character mnemonics were used in place of some or all of the numbers? Or would it make parsing an unacceptable burden and interfere with multinational WAD editing? 3.3. Entries for Graphics/Sound It is possible, of course, to supply other entries in a PWAD file besides map data: texture bitmap graphics and audio samples can WIF-001 (PRELIMINARY) page 10 appear too. Is it worth coming up with an ASCII representation of these things for inclusion in a WIF? Perhaps at minimum, a UUENCODEd copy of such binary data could appear, because other- wise, WADs that do contain both map data and sound/texture data would be impossible to render in WIF without losing data. The syntax for such entries would not be too difficult to lay out, but we will skip it in this version. APPENDIX A. EXAMPLE WIF FILE #WIF Version 1 info : A sample WAD to demonstrate the WIF format. # Feel free to add to this! - Paul. sectors:41 0 : FLOOR4_8 72 : CEIL3_5 255 1 0 # sector 0 - entry room 0 : FLOOR4_5 100 : CEIL3_5 240 1 0 # sector 1 . . . 0 : FLOOR4_8 72 : CEIL3_5 255 1 0 # sector 275 - long hall 0 : FLOOR4_8 72 : CEIL3_5 255 1 0 # sector 276 104 : FLOOR4_8 184 : FLOOR6_2 128 9 2 # sector 277 - exit lines:475 (1088,-3680) to (1024,-3680) : 1 : 0 : 0 0 (0 : - / - / DOOR3 ) 0 (1024,-3680) to (1024,-3648) : 1 : 0 : 0 0 (0 : - / - / LITE3 ) 0 (1088,-3648) to (1088,-3680) : 1 : 0 : 0 0 (0 : - / - / LITE3 ) 0 . . . (3536,-3840) to (3584,-3840) : 1 : 0 : 0 0 (0 : - / - / BROWNGRN ) 186 (3584,-3904) to (3536,-3904) : 1 : 0 : 0 0 (0 : - / - / BROWNGRN ) 186 (3536,-3904) to (3520,-3904) : 1 : 0 : 0 0 (4 : - / - / SUPPORT2 ) 187 things:138 (1056,-3616, 90) :1, 7 (1008,-3600, 90) :2, 7 (1104,-3600, 90) :3, 7 (960,-3600, 90) :4, 7 (288,-3104, 90) :48, 7 (288,-3360, 90) :48, 7 (528,-3312, 90) :2028, 7 # floor lamp . . . (3376,-3024, 0) :2015, 7 # some armor bonuses (3568,-2992, 0) :2015, 7 (3616,-3088, 0) :2015, 7 WIF-001 (PRELIMINARY) page 11 (3664,-3168, 0) :2015, 7 (3648,-3840, 0) :2015, 7 APPENDIX B. EXAMPLE DWD FILE WorldServer version 4 lines:475 (1088,-3680) to (1024,-3680) : 1 : 0 : 0 0 (0 : - / - / DOOR3 ) 0 : FLOOR4_8 72 : CEIL3_5 255 1 0 (1024,-3680) to (1024,-3648) : 1 : 0 : 0 0 (0 : - / - / LITE3 ) 0 : FLOOR4_8 72 : CEIL3_5 255 1 0 (1088,-3648) to (1088,-3680) : 1 : 0 : 0 0 (0 : - / - / LITE3 ) 0 : FLOOR4_8 72 : CEIL3_5 255 1 0 . . . (3536,-3840) to (3584,-3840) : 1 : 0 : 0 0 (0 : - / - / BROWNGRN ) 104 : FLOOR4_8 184 : FLOOR6_2 128 9 2 (3584,-3904) to (3536,-3904) : 1 : 0 : 0 0 (0 : - / - / BROWNGRN ) 104 : FLOOR4_8 184 : FLOOR6_2 128 9 2 (3536,-3904) to (3520,-3904) : 1 : 0 : 0 0 (4 : - / - / SUPPORT2 ) 104 : FLOOR4_8 184 : FLOOR6_2 128 9 2 things:138 (1056,-3616, 90) :1, 7 (1008,-3600, 90) :2, 7 (1104,-3600, 90) :3, 7 (960,-3600, 90) :4, 7 (288,-3104, 90) :48, 7 (528,-3312, 90) :2028, 7 . . . (3568,-2992, 0) :2015, 7 (3664,-3168, 0) :2015, 7 (3648,-3840, 0) :2015, 7 NOTES. [1] DOOM is a registered trademark of Id Software. [2] "The Unofficial DOOM Specifications" Release 1.3, by Matt Fell (matt.burnett@acebbs.com). Available (as DMSPEC13.ZIP) by FTP from ocf.unt.edu and wustl.wuarchive.edu. [3] DOOMBSP.ZIP, dated 6 April 94, available by FTP from ocf.unt.edu and wustl.wuarchive.edu. WIF-001 (PRELIMINARY) page 12