sys/man/4/wadfs

   1 .TH WADFS 4
   2 .SH NAME
   3 wadfs \- WAD file system
   4 .SH SYNOPSIS
   5 .B wadfs
   6 [
   7 .B -Dr
   8 ] [
   9 .B -m
  10 .I mtpt
  11 ] [
  12 .B -S
  13 .I srvname
  14 ] [
  15 .I WAD
  16 ]
  17 .SH DESCRIPTION
  18 .I Wadfs
  19 serves a file tree mounted at
  20 .I mtpt
  21 (default
  22 .BR /mnt/wad )
  23 that provides access to a
  24 .I WAD
  25 file's contents.
  26 .PP
  27 The command line options are:
  28 .TF "-S srvname"
  29 .TP
  30 .B -D
  31 Enable 9P debugging messages.
  32 .TP
  33 .B -r
  34 Set read-only file tree.
  35 .TP
  36 .BI -S \ srvname
  37 Post channel on
  38 .RI /srv/ srvname .
  39 .TP
  40 .BI -m \ mtpt
  41 Set mountpoint.
  42 .PD
  43 .PP
  44 A
  45 .I WAD
  46 is a concatenation of uncompressed files, referred to as lumps.
  47 A lump may contain either data,
  48 or be used as a marker to indicate the beginning or end of a section,
  49 segregating lumps of the same format.
  50 .PP
  51 .I Wadfs
  52 represents section start markers as directories,
  53 and regular lumps and end markers as files.
  54 For convenience, lump file names are in lower case,
  55 and are translated to the upper case internally.
  56 .PP
  57 At startup, if the path to a
  58 .I WAD
  59 file is provided as argument,
  60 .I wadfs
  61 will attempt to parse it and construct a file tree.
  62 Otherwise,
  63 .I wadfs
  64 starts with a blank tree instead.
  65 .PP
  66 Two additional files are provided in the file system's root directory:
  67 .L SIG
  68 and
  69 .LR WAD .
  70 Reading from and writing to
  71 .L SIG
  72 allows accessing and changing the
  73 .IR WAD 's
  74 type.
  75 The only possible values are
  76 .L PWAD
  77 (the default) and
  78 .LR IWAD .
  79 .PP
  80 .L WAD
  81 returns the new
  82 .I WAD
  83 file resulting from the recompilation of the lump tree.
  84 .SS "WAD file structure"
  85 There are few restrictions on the structure of
  86 .I WAD
  87 files.
  88 Excepting maps, sections can nest and may have no end marker,
  89 or one named differently than the section itself.
  90 Regular sections typically have one-letter names,
  91 and nested sections use the same name appended by a digit.
  92 By convention,
  93 lump names may only contain visible printing
  94 .SM ASCII
  95 characters,
  96 excepting lower-case letters.
  97 Map sections do not end at a marker but at the next non map lump,
  98 and use hardcoded names, depending on game version.
  99 .PP
 100 .I Wadfs
 101 imposes a number of additional restrictions on structure and naming:
 102 .IP • 3
 103 Lump names may not contain upper-case letters and the
 104 .L /
 105 character.
 106 .IP •
 107 A map section may only contain map lumps, which use hardcoded names.
 108 Ordering is significant, but is handled automatically.
 109 Map sections may not nest.
 110 .IP •
 111 Regular sections may not nest beyond one level,
 112 and may not contain more than one end marker.
 113 End markers may not exist outside of a section.
 114 Directory names omit the start marker's
 115 .L "_START"
 116 suffix.
 117 .IP •
 118 Excepting map lumps, no two lumps, including markers,
 119 may have the same name.
 120 .IP •
 121 Once created, a lump may not be renamed so as to change its type.
 122 .SS "Error recovery"
 123 Upon parsing the initial
 124 .I WAD
 125 file, if one of the restrictions for
 126 .I WAD
 127 file structure outlined in the sections above is not respected,
 128 a warning is issued, and the offending lump is potentially skipped.
 129 Some recovery is attempted,
 130 but one must systematically recheck the tree.
 131 When duplicate non marker lumps are encountered,
 132 each will overwrite the previous entry.
 133 .SH EXAMPLES
 134 Open
 135 .B doom2.wad
 136 and play a MUS file:
 137 .IP
 138 .EX
 139 % games/wadfs /sys/games/lib/doom/doom2.wad
 140 createfile SW18_7: file already exists
 141 % games/mus /mnt/wad/d_romero | games/midi
 142 .EE
 143 .PP
 144 Now create a blank
 145 .IR WAD ,
 146 then one section
 147 .LR FF ;
 148 copy a flat from
 149 .B doom2.wad
 150 to the directory,
 151 then rename the end marker to
 152 .L F_END
 153 to have the
 154 .B doom
 155 engine find the flat;
 156 finally, compile and save the new
 157 .I WAD
 158 file.
 159 .IP
 160 .EX
 161 % games/wadfs -m /mnt/wad2
 162 % cd /mnt/wad2
 163 % mkdir ff
 164 adding end marker FF_END
 165 % cp ../wad/f/f1/f_sky1 ff/
 166 % mv ff/ff_end ff/f_end
 167 % cp WAD /sys/games/lib/doom/sky.wad
 168 .EE
 169 .SH SOURCE
 170 .B /sys/src/games/wadfs.c
 171 .SH "SEE ALSO"
 172 .IR games (1),
 173 .IR mus (1)
 174 .SH HISTORY
 175 .I Wadfs
 176 first appeared in 9front (August, 2017).
 177 .SH BUGS
 178 Many
 179 .I WAD
 180 files in the wild do not conform to all the rules exposed above,
 181 in particular ones using
 182 .SM DeHackEd
 183 engine modifications.
 184 .IR WAD 's
 185 using end markers outside of a section,
 186 typically
 187 .LR F_END ,
 188 will lose them.
 189 .PP
 190 Repairing broken
 191 .I WAD
 192 files can be a pain.