WADFS(4)                                                 WADFS(4)

     NAME
          wadfs - WAD file system

     SYNOPSIS
          wadfs [ -Dr ] [ -m mtpt ] [ -S srvname ] [ WAD ]

     DESCRIPTION
          Wadfs serves a file tree mounted at mtpt (default /mnt/wad)
          that provides access to a WAD file's contents.

          The command line options are:

          -D          Enable 9P debugging messages.
          -r          Set read-only file tree.
          -S srvname  Post channel on /srv/srvname.
          -m mtpt     Set mountpoint.

          A WAD is a concatenation of uncompressed files, referred to
          as lumps.  A lump may contain either data, or be used as a
          marker to indicate the beginning or end of a section, segre-
          gating lumps of the same format.

          Wadfs represents section start markers as directories, and
          regular lumps and end markers as files.  For convenience,
          lump file names are in lower case, and are translated to the
          upper case internally.

          At startup, if the path to a WAD file is provided as argu-
          ment, wadfs will attempt to parse it and construct a file
          tree.  Otherwise, wadfs starts with a blank tree instead.

          Two additional files are provided in the file system's root
          directory: `SIG' and `WAD'.  Reading from and writing to
          `SIG' allows accessing and changing the WAD's type.  The
          only possible values are `PWAD' (the default) and `IWAD'.

          `WAD' returns the new WAD file resulting from the recompila-
          tion of the lump tree.

        WAD file structure
          There are few restrictions on the structure of WAD files.
          Excepting maps, sections can nest and may have no end
          marker, or one named differently than the section itself.
          Regular sections typically have one-letter names, and nested
          sections use the same name appended by a digit.  By conven-
          tion, lump names may only contain visible printing ASCII
          characters, excepting lower-case letters.  Map sections do
          not end at a marker but at the next non map lump, and use
          hardcoded names, depending on game version.

     WADFS(4)                                                 WADFS(4)

          Wadfs imposes a number of additional restrictions on struc-
          ture and naming:

          •  Lump names may not contain upper-case letters and the `/'
             character.

          •  A map section may only contain map lumps, which use hard-
             coded names.  Ordering is significant, but is handled
             automatically.  Map sections may not nest.

          •  Regular sections may not nest beyond one level, and may
             not contain more than one end marker.  End markers may
             not exist outside of a section.  Directory names omit the
             start marker's `_START' suffix.

          •  Excepting map lumps, no two lumps, including markers, may
             have the same name.

          •  Once created, a lump may not be renamed so as to change
             its type.

        Error recovery
          Upon parsing the initial WAD file, if one of the restric-
          tions for WAD file structure outlined in the sections above
          is not respected, a warning is issued, and the offending
          lump is potentially skipped.  Some recovery is attempted,
          but one must systematically recheck the tree.  When dupli-
          cate non marker lumps are encountered, each will overwrite
          the previous entry.

     EXAMPLES
          Open doom2.wad and play a MUS file:

               % wadfs /sys/games/lib/doom/doom2.wad
               createfile SW18_7: file already exists
               % games/mus /mnt/wad/d_romero | games/midi

          Now create a blank WAD, then one section `FF'; copy a flat
          from doom2.wad to the directory, then rename the end marker
          to `F_END' to have the doom engine find the flat; finally,
          compile and save the new WAD file.

               % wadfs -m /mnt/wad2
               % cd /mnt/wad2
               % mkdir ff
               adding end marker FF_END
               % cp ../wad/f/f1/f_sky1 ff/
               % mv ff/ff_end ff/f_end
               % cp WAD /sys/games/lib/doom/sky.wad

     SOURCE
          /sys/src/games/wadfs.c

     WADFS(4)                                                 WADFS(4)

     SEE ALSO
          games(1), mus(1)

     HISTORY
          Wadfs first appeared in 9front (August, 2017).

     BUGS
          Many WAD files in the wild do not conform to all the rules
          exposed above, in particular ones using DeHackEd engine mod-
          ifications.  WAD's using end markers outside of a section,
          typically `F_END', will lose them.

          Repairing broken WAD files can be a pain.