WADS of WADS/WadsOfWads.1994.zip/TEXT/WIFSPEC.TXT

Text File | 1994-04-14 | 30KB | 734 lines

          DOOM User WAD Authors Working Group                       T. Neff
          In-Progress Specification: WIF-001                [e-mail]


                                  *** 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 : <number>

          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 <number> equal to 201.
          Sometimes, a substitution parameter will appear in braces:

             level : <episode> <level> [name]

          This means that while <episode> and <level> are REQUIRED parame-
          ters, <name> 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:

             <Level> 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, [e-mail]

          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 : <episode> <level> [name]

          where <episode> 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 <level> 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 : <number>

          where <number> is the number of sector definition entries (not
          counting continuations) following.

          Following this directive are one or more sector definition
          entries of the form

             <floorH> : <floorT> <ceilH> : <ceilT> <litelev> <type> <tag>

          where <floorH> and <ceilH> (numeric) and <floorT> and <ceilT>
          (string) are the floor and ceiling heights and texture names,
          respectively; <litelev> is the numeric light level; <type>
          (numeric) is the sector type; and <tag> (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 : <count>

          where <count> is the number of line definitions (not counting
          Side definitions) that follow.

          This directive is followed by <count> number of definitions, each
          consisting of a Linedef followed by one or two Sidedefs.

          A Linedef consists of a line as follows:

             (<x0>,<y0>) to (<x1>,<y1>) : <flags> : <type> : <tag>

          where <x0>, <y0>, <x1>, <y1> are the numeric X and Y coordinates,
          respectively, of the line's start and end points; <flags> is the
          numeric flags value; <type> is the numeric line type; and <tag>
          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:

             <xoff> ( <yoff> : <topT> / <botT> / <midT> ) <sector>

          where <xoff> and <yoff> are the numeric X and Y offsets, respec-
          tively, of the textures applied to this side; <topT>, <botT>, and
          <midT> are the (string) names of the textures to apply to top,
          bottom, and middle (or "normal") surfaces of this side; and
          <sector> 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:<count>


                                               WIF-001 (PRELIMINARY) page 9







          where <count> is the number of Thingdefs following.  Then comes
          <count> many Thingdefs, each of which has the format

             (<x>, <y>, <angle>) :<type>, <when>

          where <x> and <y> are the numeric coordinates of the thing's
          location, <angle> is the direction it faces (0 to 359), <type> is
          the number (1-????) of the type of Thing at that location, and
          <when> 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 ([e-mail]).  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