\chapter{File formats}
\label{app:formats}

All file formats are binary, and all data fields are stored in
little-endian byte order, unless otherwise specified.  All indices are
zero-based, and all sizes and offsets are in bytes unless otherwise
specified.  To describe a file format, we use the conventions shown in
the following example of a table:

\begin{protocol}
\pline{Bytes in field}{Description of field}
\\
\pline{4 bytes}{number of \nonterminal{entry}s (= $n$)}
\pline{4$n$ bytes}{\nonterminal{entry}s}
\\
\newnonterminal{entry}
\pline{4 bytes}{per-entry information}
\\
\pline{\nonterminal{entry}$*$}{zero or more instances of \nonterminal{entry}}
\end{protocol}

The file is described in sequential order.  A token within angle
brackets ({\tt <>}) is a nonterminal symbol that is defined elsewhere
in the specification.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Sound and music files}

The client supports music in standard MIDI files.  Sounds can be in
any of the usual WAV file formats:  sampling rates of 11kHz, 22 kHz,
44 kHz, mono or stereo, and 8 bit or 16 bit samples.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Object code {\tt .bof}}

A \bof file contains the object code generated by compiling a \kod
file with the Blakston compiler.  All offsets in the file are relative
to the beginning of the file, which is offset 0.

\begin{protocol}
\pline{4 bytes}{magic number = 42 4F 46 FF (hexadecimal)}
\pline{4 bytes}{version of bof file = 5}
\\
\pline{4 bytes}{offset of source filename}
\pline{4 bytes}{offset of beginning of \nonterminal{string table}}
\pline{4 bytes}{offset of beginning of \nonterminal{debugging info} (0 if none)}
\\
\pline{4 bytes}{number of classes (= $n$)}
8$n$ bytes \\
\plineindent{4 bytes}{class id}
\plineindent{4 bytes}{offset of class in file}
\\
\nonterminal{class}$*$ \\
\nonterminal{string table} \\
\nonterminal{debugging info} \\
\pline{\nonterminal{string}}{source filename}
\\
\newnonterminal{class}
\pline{4 bytes}{class id of superclass}
\pline{4 bytes}{offset of \nonterminal{property section}}
\pline{4 bytes}{offset of \nonterminal{message section}}
\pline{4 bytes}{number of class variables for this class and all superclasses}
\pline{4 bytes}{number of default class variable values (= $n$)}
\pline{8$n$ bytes}{class variable default values}
\plineindent{4 bytes}{index number of class variable}
\plineindent{4 bytes}{class variable default \nonterminal{value}}
\\
\newnonterminal{property section}
\pline{4 bytes}{number of properties for this class and all superclasses}
\pline{4 bytes}{number of default property values (= $n$)}
\pline{8$n$ bytes}{property default values}
\plineindent{4 bytes}{index number of property}
\plineindent{4 bytes}{property default \nonterminal{value}}
\\
\newnonterminal{message section}
\pline{4 bytes}{number of \nonterminal{message handler}s (= $n$)}
\pline{12$n$ bytes}{message handler headers}
\plineindent{4 bytes}{message id}
\plineindent{4 bytes}{offset of message handler}
\plineindent{4 bytes}{index of handler's comment string in \nonterminal{string table} (-1 if none)}
\nonterminal{message handler}$*$ \\
\\
\newnonterminal{message handler}
\pline{1 byte}{number of local variables}
\pline{1 byte}{number of parameters (= $n$)}
\pline{8$n$ bytes}{parameters}
\plineindent{4 bytes}{id of parameter}
\plineindent{4 bytes}{default value of parameter}
These parameters must appear in increasing id number order. \\
\pline{\nonterminal{bkod statement}$*$}{Message handler code}
\\
\newnonterminal{string table}
\pline{4 bytes}{number of strings (= $n$)}
\pline{4$n$ bytes}{offset of beginning of each \nonterminal{string}}
\\
\newnonterminal{string}
\pline{$n$ bytes}{ASCII string characters, null terminated}
\\
\newnonterminal{debugging info}
\pline{4 bytes}{number of \nonterminal{line entry}s}
\nonterminal{line entry}$*$ \\
\\
\newnonterminal{line entry}
\pline{4 bytes}{offset in file}
\pline{4 bytes}{corresponding source file line number}
\\
\newnonterminal{value}
4 bytes \\
\pushtabs
First 4 bits \= Type \hspace{1in} \= 28 data bits \\
0000         \> NIL          \> all 0 \\
0001         \> integer      \> integer value \\
0010         \> object       \> object id \\
0011         \> list         \> list id \\
0100         \> string       \> string id \\
1100         \> debugging string \> string index into \nonterminal{debugging info} \\
\poptabs
\\
\newnonterminal{bkod statement}
\pline{1 byte}{\nonterminal{opcode}}
\pline{$n$ bytes}{data}
\\
\newnonterminal{opcode}
\pline{{\it xxxwyyzz}}{8 bit opcode value}
\\
{\it xxx} or {\it xxxw} specifies the command \\
\pline{000}{\nonterminal{unary assignment}}
\pline{001}{\nonterminal{binary assignment}}
\pline{010}{\nonterminal{goto}}
\pline{011}{\nonterminal{call}}
\pline{1001}{\nonterminal{propagate}}
\pline{1000}{\nonterminal{return}}
\\
\newnonterminal{destination}
\pline{0}{local variable}
\pline{1}{property}
\\
\newnonterminal{source}
\pline{00}{local variable}
\pline{01}{property}
\pline{10}{constant}
\pline{11}{class variable}
\\
\newnonterminal{unary assignment}
\pline{1 byte}{opcode}
\plineindent{{\it w}}{\nonterminal{destination}}
\plineindent{{\it yy}}{\nonterminal{source}}
\plineindent{{\it zz}}{always 00}
\pline{1 byte}{operation}
\plineindent{0}{logical NOT}
\plineindent{1}{unary minus}
\plineindent{2}{no operation}
\plineindent{3}{bitwise NOT}
\pline{4 bytes}{destination index (property or local variable)}
\pline{4 bytes}{source index (property, local variable, constant, or class variable)}
\\
\newnonterminal{binary assignment}
\pline{1 byte}{opcode}
\plineindent{{\it w}}{\nonterminal{destination}}
\plineindent{{\it yy}}{\nonterminal{source \#1}}
\plineindent{{\it zz}}{\nonterminal{source \#2}}
\pline{1 byte}{C-like operation}
\plineindent{0}{$+$}
\plineindent{1}{$-$}
\plineindent{2}{$*$}
\plineindent{3}{$/$}
\plineindent{4}{$\%$}
\plineindent{5}{$\&\&$}
\plineindent{6}{$\mid\mid$}
\plineindent{7}{$=$}
\plineindent{8}{$!=$}
\plineindent{9}{$<$}
\plineindent{10}{$>$}
\plineindent{11}{$<=$}
\plineindent{12}{$>=$}
\plineindent{13}{$\&$}
\plineindent{14}{$\mid$}
\pline{4 bytes}{destination index (property or local variable)}
\pline{4 bytes}{source \#1 index (property, local variable, constant, or class variable)}
\pline{4 bytes}{source \#2 index (property, local variable, constant, or class variable)}
\\
\newnonterminal{goto}
\pline{1 byte}{opcode}
\plineindent{{\it w}}{\nonterminal{condition}}
\plineindent{{\it yy}}{\nonterminal{source}}
\plineindent{{\it zz}}{conditional/unconditional jump \nonterminal{indicator}}
\pline{4 bytes}{destination address, relative to the beginning of this
instruction}
\pline{4 bytes}{source index (not present for unconditional goto)}
\\
\newnonterminal{condition}
\pline{0}{jump if source != 0}
\pline{1}{jump if source = 0}
\\
\newnonterminal{indicator}
\pline{0}{conditional jump}
\pline{1}{unconditional jump (\nonterminal{condition} must be 00)}
\\
\newnonterminal{call}
\pline{1 byte}{opcode}
\pline{{\it wyy}}{location to store return value}
\plineindent{000}{local variable}
\plineindent{001}{property}
\plineindent{010}{nowhere}
\pline{1 byte}{built-in function to call}
\pline{4 bytes}{destination index for return value}
\pline{}{(not present if return value not stored)}
\pline{1 byte}{number of \nonterminal{parameter}s to the function (=
$n$)}
\pline{9$n$ bytes}{\nonterminal{parameter}*}
\\
\newnonterminal{parameter}
\pline{4 bytes}{resource identifier of parameter name}
\pline{1 byte}{parameter type}
\plineindent{0}{local variable}
\plineindent{1}{property}
\plineindent{2}{constant}
\plineindent{3}{class variable}
\pline{4 bytes}{\nonterminal{value} of parameter}
\\
\newnonterminal{propagate}
\pline{1 byte}{opcode}
\pline{yy}{\nonterminal{destination} for return value}
\pline{4 bytes}{destination index for return value}
\\
\newnonterminal{return}
\pline{1 byte}{opcode}

\end{protocol}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{String resource {\tt .rsc}}

Compiling a \kod file also generates a \rsc file, which contains a
mapping of resource identifier numbers to strings.  These files are
sent to clients, where they are used to decode resource numbers sent
in protocol messages.  The files are encrypted with the Crusher
library to keep users from reading their contents.

\begin{protocol}
\pline{4 bytes}{magic number = 52 53 43 01 (hexadecimal)}
\pline{4 bytes}{version = 2}
\pline{4 bytes}{number of resources}
\pline{4 bytes}{length of \nonterminal{encrypted section}}
\pline{4 bytes}{response to challenge of version number (used in decryption)}
\nonterminal{encrypted section} \\
\\
\newnonterminal{encrypted section}
This section is encrypted with the hexadecimal key
xF1x71xC6xBBx19x6Ex2Ex71x6F. \\
\nonterminal{resource}$*$ \\
\\
\newnonterminal{resource}
\pline{4 bytes}{resource identifier}
\pline{$n$ bytes}{null-terminated string}
\end{protocol}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Room file {\tt .roo}}

A room file contains the BSP tree for a single room.  The file can be
encrypted to prevent tampering; the client can load both encrypted and
unencrypted versions.

Building the BSP tree splits walls into smaller pieces.  However,
these splits should not appear when the room is later loaded back into
the editor.  Thus, we store the original walls (before the creation of
the BSP tree) in the file separately.  The editor loads the original
walls and ignores the BSP tree, while the client loads the BSP tree
but ignores the original walls.

The editor builds the ``server section'' of the file so that the
server can have some basic knowledge of the room's geometry.  Neither
the client nor the editor loads this section.

\begin{protocol}
\pline{4 bytes}{magic number = 52 4F 4F B1 (hexadecimal)}
\pline{4 bytes}{version = 11}
\pline{4 bytes}{\nonterminal{security}}
\pline{4 bytes}{offset of \nonterminal{main info}}
\pline{4 bytes}{offset of \nonterminal{server info}}
\nonterminal{main info} \\
\nonterminal{server info} \\
\\
\newnonterminal{main info}
\nonterminal{size} \\ 
\nonterminal{data} \\
\\
\newnonterminal{size}
\pline{4 bytes}{width of room (in client units)}
\pline{4 bytes}{height of room (in client units)}

If the width of the room is -1, then the \nonterminal{data} section is
encrypted.  \\
In this case, these bytes appear here: \\
\pline{4 bytes}{length of \nonterminal{data}}
\pline{4 bytes}{response to challenge of room security check (used in
decryption)}

and the \nonterminal{data} section is encrypted by the hexadecimal
password x15x20x53x01xFCxAAx64. \\
\\
\newnonterminal{data}
\pline{4 bytes}{offset of \nonterminal{node subsection}}
\pline{4 bytes}{offset of \nonterminal{client wall subsection}}
\pline{4 bytes}{offset of \nonterminal{roomedit wall subsection}}
\pline{4 bytes}{offset of \nonterminal{sidedef subsection}}
\pline{4 bytes}{offset of \nonterminal{sector subsection}}
\pline{4 bytes}{offset of \nonterminal{thing subsection}}
\\
\newnonterminal{node subsection}
\pline{2 bytes}{number of \nonterminal{BSPnode}s}
\pline{\nonterminal{BSP node}$*$}{nodes of BSP tree; root must appear
first}
\\
\newnonterminal{client wall subsection} 
\pline{2 bytes}{number of \nonterminal{client wall}s}
\nonterminal{client wall}$*$ \\
\\
\newnonterminal{roomedit wall subsection}
\pline{2 bytes}{number of \nonterminal{roomedit wall}s}
\nonterminal{roomedit wall}$*$ \\
\\
\newnonterminal{sidedef subsection}
\pline{2 bytes}{number of \nonterminal{sidedef}s}
\nonterminal{sidedef}$*$ \\
\\
\newnonterminal{sector subsection} 
\pline{2 bytes}{number of \nonterminal{sector}s}
\nonterminal{sector}$*$ \\
\\
\newnonterminal{thing subsection}
\pline{2 bytes}{number of \nonterminal{thing}s}
\nonterminal{thing}$*$ \\
\\
\newnonterminal{BSP node}
\pline{1 byte}{node type}
\plineindent{1}{internal node}
\plineindent{2}{leaf node}
\pline{\nonterminal{box}}{bounding box of node}
\pline{\nonterminal{internal node} or \nonterminal{leaf node}}
\\
\newnonterminal{internal node}
\pline{\nonterminal{line}}{equation of a line that splits the BSP tree}
\pline{\nonterminal{node id}}{BSP node number of + subtree (0 if none, 1 = first wall in file)}
\pline{\nonterminal{node id}}{BSP node number of - right subtree (0 if none, 1 = first wall in file)}
\pline{2 bytes}{wall number of first wall in this plane (starts at 1 =
first wall in file; 0 if none)}
\\
\newnonterminal{leaf node}
\pline{2 bytes}{sector number corresponding to this node (1 = first sector in file)}
\pline{2 bytes}{number of points in polygon defining leaf node}
\pline{\nonterminal{point}$*$}{points of polygon defining leaf node (clockwise order as seen from above)}
\\
\newnonterminal{client wall}
\pline{2 bytes}{next wall in list of walls in plane (0 if none)}
\pline{2 bytes}{sidedef on + side of wall (0 = none, 1 = first sidedef in file)}
\pline{2 bytes}{sidedef on - side of wall (0 = none, 1 = first sidedef in file)}
\pline{\nonterminal{point}}{coordinates of start of wall}
\pline{\nonterminal{point}}{coordinates of end of wall  (positive side
is on right going start to end)}
\pline{2 bytes}{length of wall (units: 1 server coordinate unit = length 64)}
\pline{2 bytes}{texture x offset on positive side (in pixels)}
\pline{2 bytes}{texture x offset on negative side (in pixels)}
\pline{2 bytes}{texture y offset on positive side (in pixels)}
\pline{2 bytes}{texture y offset on negative side (in pixels)}
\pline{2 bytes}{sector number on + side of wall (0 = none, 1 = first sector in file)}
\pline{2 bytes}{sector number on - side of wall (0 = none, 1 = first sector in file)}
\\
\newnonterminal{line}
\pline{4 bytes}{$A$ in line equation $Ax + By + C = 0$}
\pline{4 bytes}{$B$ in line equation $Ax + By + C = 0$}
\pline{4 bytes}{$C$ in line equation $Ax + By + C = 0$}
\\
\newnonterminal{box}
\pline{point}{coordinates of NW corner of bounding box}
\pline{point}{coordinates of SE corner of bounding box}
\\
\newnonterminal{point}
\pline{4 bytes}{x coordinate}
\pline{4 bytes}{y coordinate}
\\
\newnonterminal{node id}
\pline{2 bytes}{}
\\
\newnonterminal{sidedef}
\pline{2 bytes}{user-defined id (used for referencing from server)}
\pline{2 bytes}{bitmap number of normal bitmap}
\pline{2 bytes}{bitmap number of above bitmap}
\pline{2 bytes}{bitmap number of below bitmap}
\pline{\nonterminal{wall flags}}{various characteristics of the wall}
\pline{1 byte}{animation speed of bitmap on wall, in tenths of a frame per second}
\\
\newnonterminal{sector}
\pline{2 bytes}{user-defined id (used for referencing from sector)}
\pline{2 bytes}{bitmap number of floor bitmap}
\pline{2 bytes}{bitmap number of ceiling bitmap}
\pline{2 bytes}{x coordinate of origin of floor and ceiling textures
(in pixels)}
\pline{2 bytes}{y coordinate of origin of floor and ceiling textures
(in pixels)}
\pline{2 bytes}{floor height (units: size of one server coordinate = 64)}
\pline{2 bytes}{ceiling height (units: size of one server coordinate = 64)}
\pline{\nonterminal{light level}}{light level in sector}
\pline{\nonterminal{sector flags}}{various characteristics of the sector}
\pline{1 byte}{animation speed of bitmaps in sector, in tenths of a frame per second}
if \nonterminal{sector flags} indicates a sloped floor, then \\
\pline{\nonterminal{slope info}}{info on sloped floor}
if \nonterminal{sector flags} indicates a sloped ceiling, then \\
\pline{\nonterminal{slope info}}{info on sloped ceiling}
\\
\newnonterminal{light level}
\pline{1 byte}{}
\plineindent{0-127}{sector not affected by ambient light; 0 = darkest, 127 = brightest}
\plineindent{128-255}{sector affected by ambient light; 128 = darkest,
255 = brightest, 192 = neutral}
\\
\newnonterminal{roomedit wall}
\pline{2 bytes}{sidedef on + side of wall (0 = none, 1 = first sidedef in file)}
\pline{2 bytes}{sidedef on - side of wall (0 = none, 1 = first sidedef in file)}
\pline{2 bytes}{texture x offset on positive side (in pixels)}
\pline{2 bytes}{texture x offset on negative side (in pixels)}
\pline{2 bytes}{texture y offset on positive side (in pixels)}
\pline{2 bytes}{texture y offset on negative side (in pixels)}
\pline{2 bytes}{sector number on + side of wall}
\pline{2 bytes}{sector number on - side of wall}
\pline{\nonterminal{point}}{coordinates of start of wall}
\pline{\nonterminal{point}}{coordinates of end of wall (positive side is on right
going start to end)}
\\
\newnonterminal{thing}
\pline{\nonterminal{point}}{location of thing}
\\
\newnonterminal{wall flags}
\pline{4 bytes}{}
\plineindent{bit 0}{1 if bitmaps on wall should be drawn backwards (left-right reversed)}
\plineindent{bit 1}{1 if normal wall has some transparency}
\plineindent{bit 2}{1 if objects can pass through wall}
\plineindent{bit 3}{1 if wall should never be shown on map}
\plineindent{bit 4}{1 if wall should always be shown on map}
\plineindent{bit 5}{1 if wall is transparent, but there's nothing behind it}
\plineindent{bit 6}{1 if upper wall should be drawn bottom up (default is top down)}
\plineindent{bit 7}{1 if lower wall should be drawn top down (default is bottom up)}
\plineindent{bit 8}{1 if normal wall should be drawn top down (default is bottom up)}
\plineindent{bit 9}{1 if wall shouldn't tile vertically (must also be transparent)}
\plineindent{bits 10-11}{texture scrolling speed, 0 = none, ... 3 = fast}
\plineindent{bits 12-14}{texture scrolling direction (used only if
scroll speed nonzero)}
\pline{}{0 = N, 1 = NE, ... 7 = NW}
\\
\newnonterminal{sector flags}
\pline{4 bytes}{}
\plineindent{bits 0 and 1}{``depth'' of sector (for wading effects)}
\pline{}{0 = no depth, 1 = shallow, 2 = deep, 3 = very deep}
\plineindent{bits 2-3}{texture scrolling speed, 0 = none, ... 3 = fast}
\plineindent{bits 4-6}{texture scrolling direction (used only if
scroll speed nonzero)}
\pline{}{0 = N, 1 = NE, ... 7 = NW}
\plineindent{bit 7}{1 if floor texture should be scrolled}
\plineindent{bit 8}{1 if ceiling texture should be scrolled}
\plineindent{bit 9}{1 if light in sector should flicker}
\plineindent{bit 10}{1 if sector has a sloped floor}
\plineindent{bit 11}{1 if sector has a sloped ceiling}
\\
\newnonterminal{slope info}
\pline{4 bytes}{$a$ coefficient in plane equation $ax+by+cz+d = 0$}
\pline{4 bytes}{$b$ coefficient in plane equation $ax+by+cz+d = 0$}
\pline{4 bytes}{$c$ coefficient in plane equation $ax+by+cz+d = 0$}
\pline{4 bytes}{$d$ coefficient in plane equation $ax+by+cz+d = 0$}
\pline{\nonterminal{point}}{texture origin}
\pline{\nonterminal{angle}}{direction of positive u axis (for texture orientation)}
\pline{2 bytes}{vertex number of user-specified sector vertex \#1 (used in editor)}
\pline{2 bytes}{z coordinate of vertex \#1 (in room editor units)}
\pline{2 bytes}{vertex number of user-specified sector vertex \#2 (used in editor)}
\pline{2 bytes}{z coordinate of vertex \#2 (in room editor units)}
\pline{2 bytes}{vertex number of user-specified sector vertex \#3 (used in editor)}
\pline{2 bytes}{z coordinate of vertex \#3 (in room editor units)}
\\
\newnonterminal{server info}
\pline{4 bytes}{number of grid rows (= $r$)}
\pline{4 bytes}{number of grid cols (= $c$)}
\pline{\nonterminal{move grid}}{inter-square movement grid}
\pline{\nonterminal{flag grid}}{server square flags}
\\
\newnonterminal{move grid}
\pline{$r * c$ bytes}{one byte for each square in the room, row major order:}
\plineindent{bit 0}{1 if possible to move to adjacent square to N}
\plineindent{bit 1}{1 if possible to move to adjacent square to NE}
\plineindent{bit 2}{1 if possible to move to adjacent square to E}
\plineindent{bit 3}{1 if possible to move to adjacent square to SE}
\plineindent{bit 4}{1 if possible to move to adjacent square to S}
\plineindent{bit 5}{1 if possible to move to adjacent square to SW}
\plineindent{bit 6}{1 if possible to move to adjacent square to W}
\plineindent{bit 7}{1 if possible to move to adjacent square to NW}
\\
\newnonterminal{flag grid}
\pline{$r * c$ bytes}{one byte for each square in the room, row major order:}
\plineindent{bit 0}{1 if square is entirely within playable region (i.e. a real floor covers square)}

\end{protocol}


\begin{tabbing}
The \nonterminal{security} value is calculated as follows: \\
\\
1) Calculate the 32 bit signed sum of the following things in the
file: \\
\\
file version number \\
for \= each internal node in main section: \\
\>$a, b, c$ coefficients of line \\
\>wall number of first wall in plane \\
for each leaf node in main section: \\
\>x and y coordinates of each point \\
for each client wall in client section: \\
\>+ and - sidedef numbers \\
\>x and y coordinates of start and end of wall \\
\>+ and - sector numbers \\
for each sidedef in main section: \\
\>user-defined id  \\
\>bitmap numbers of normal, above, and below walls \\
\>wall flags value \\
for each sector in client section: \\
\>user-defined id \\
\>bitmap numbers of floor and ceiling \\
\>floor and ceiling heights \\
\>light level \\
\>sector flags value \\
\\
2) exclusive or with 0x89ab786c \\
\end{tabbing}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Graphics {\tt .bgf}}

A \bgf file contains one or more Windows bitmaps that describe an
object, along with information that makes displaying and animating the
object easier.

The rows in a bitmap appear in order top to bottom.  Each row contains
1 byte per column, left to right.  This byte's value is an index into
the game's palette.

\begin{protocol}
\pline{4 bytes}{magic number = 42 47 46 11 (hexadecimal)}
\pline{4 bytes}{version = 9}
\pline{32 bytes}{bitmap name, null terminated}
\pline{4 bytes}{number of \nonterminal{bitmap}s}
\pline{4 bytes}{number of \nonterminal{bitmap group}s}
\pline{4 bytes}{largest number of bitmaps in any single bitmap group}
\pline{4 bytes}{shrink factor of all bitmaps; divide by this to get size to draw bitmap on screen}
\nonterminal{bitmap}$*$ \\
\nonterminal{bitmap group}$*$ \\
\\
\newnonterminal{bitmap group}
\pline{4 bytes}{number of \nonterminal{bitmap index}s}
\nonterminal{bitmap index}$*$ \\
\\
\newnonterminal{bitmap index}
\pline{4 bytes}{index into bitmaps in file (starts counting from 0)}
\\
\newnonterminal{bitmap}
\pline{4 bytes}{width in pixels (= $w$)}
\pline{4 bytes}{height in pixels (= $h$)}
\pline{4 bytes}{x offset in pixels}
\pline{4 bytes}{y offset in pixels}
\pline{1 byte}{number of hotspots}
\pline{\nonterminal{hotspot}$*$}{hotspot locations}
\pline{1 byte}{format of image, 0 = raw, 1 = compressed}
\\
if format = 0 \\
\pline{4 bytes}{unused (must be 0)}
\pline{$w * h$ bytes}{raw bytes of image}
\\
if format = 1 \\
\pline{4 bytes}{size of compressed image}
\pline{$w * h$ bytes}{raw bytes of image, compressed by Crusher}
\\
\newnonterminal{hotspot}
\pline{1 byte}{hotspot number (unique to this object and all its overlays)}
\pline{4 bytes}{x coordinate}
\pline{4 bytes}{y coordinate}
\end{protocol}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Map file {\tt .map}}

A map file indicates which walls of each room the player has viewed,
for use in drawing the map.  It also stores map annotations, which are
text strings that are associated with locations on a map.  These files
are kept on client machines.

\begin{protocol}
\pline{4 bytes}{magic number = 4D 41 50 0F (hexadecimal)}
\pline{4 bytes}{version = 1}
\nonterminal{header table} \\
\nonterminal{offset table}$*$ \\
\nonterminal{map info}$*$ \\
\\
\newnonterminal{header table}
\pline{\nonterminal{offset}}{offset of first \nonterminal{offset
table} for \nonterminal{digits} 00; 0 if none}
... \\
\pline{\nonterminal{offset}}{offset of first \nonterminal{offset table} for \nonterminal{digits} 99; 0 if none}
\\
More \nonterminal{offset table}s and \nonterminal{map info}s occur
interspersed in the file. \\

\newnonterminal{offset table}
\pline{\nonterminal{offset}}{offset of next \nonterminal{offset table} in file with same last 2 digits; 0 if none}
\pline{\nonterminal{offset table entry}$*$}{100 table entries}
\\
\newnonterminal{offset table entry}
\pline{\nonterminal{security}}{room security value of a room, 0 if entry is invalid}
\pline{\nonterminal{offset}}{offset of \nonterminal{map info} for this room}
\\
\newnonterminal{map info}
\pline{4 bytes}{number of bits in \nonterminal{bit table} = number of walls in room}
\pline{\nonterminal{bit table}}{which walls in room are saved as visible}
\pline{\nonterminal{offset}}{offset in file of \nonterminal{annotations}, 0 if none}
\\
\newnonterminal{bit table}
An array of bits, 1 bit per wall in the room file, with the first bit \\
corresponding to the first wall.  If the bit is 1, the corresponding \\
wall should be shown on the map.  The bit table is rounded up in size \\
to the nearest byte. \\
\\
\newnonterminal{annotations}
\pline{4 bytes}{number of \nonterminal{map annotation}s}
\nonterminal{map annotation}$*$ \\
\\
\newnonterminal{map annotation}
\pline{4 bytes}{x position of annotation (client units)}
\pline{4 bytes}{y position of annotation (client units)}
\pline{100 bytes}{text of annotation, null-terminated}
\\
\newnonterminal{offset}
\pline{4 bytes}{offset in bytes from the beginning of the file}
\\
\newnonterminal{security}
\pline{4 bytes}{room security value}
\\
\newnonterminal{digits}
\pline{4 bytes}{A \nonterminal{security} value modulo 100}

\end{protocol}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Server account file}

The account file stores username, password, and administrative
information for each account.  This is a text file format, one account
per line, with fields deilimited by colons.

ACCOUNT \nonterminal{number}:\nonterminal{name}:\nonterminal{password}:\nonterminal{type}:\nonterminal{login
time}:\nonterminal{credits}

\begin{protocol}
\newnonterminal{number}
Account number; first account is 1. \\
\\
\newnonterminal{name}
String name of account. \\
\\
\newnonterminal{password}
Account password, represented as a sequence of hexadecimal digits, \\
run through the MD5 one-way hash algorithm. \\
\\
\newnonterminal{type}
Type of account. \\
\plineindent{0}{User account}
\plineindent{1}{Administrator account}
\plineindent{2}{DM account}
\plineindent{3}{Guest account}
\\
\newnonterminal{login time}
Last time the player logged in, in units of seconds since January 1,
1970. \\
\\
\newnonterminal{credits}
Floating point number equal to the number of seconds the player has
spent in game mode, \\
divided by 100. \\
\end{protocol}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Saved game format}

The server saves its object database in a binary format.  When the
server next starts, it reads in its last saved game file and
initializes its database with these values.

\begin{protocol}

\pline{\nonterminal{class}$*$}{description of all classes}
\pline{\nonterminal{resource}$*$}{description of all resources}
\pline{\nonterminal{system}}{identifies unique system object}
\pline{\nonterminal{object}$*$}{description of all objects}
\pline{\nonterminal{list nodes}}{description of all list nodes}
\pline{\nonterminal{timer}$*$}{description of all timers}
\pline{\nonterminal{user}$*$}{description of all users}
\\
\newnonterminal{class}
\pline{1 byte}{01 hexadecimal}
\pline{4 bytes}{class identifier}
\pline{\nonterminal{string}}{class name}
\pline{4 bytes}{number of properties in class (= $n$)}
\pline{\nonterminal{string}*}{property names}
\\
\newnonterminal{resource}
\pline{1 byte}{02 hexadecimal}
\pline{4 bytes}{resource identifier}
\pline{\nonterminal{string}}{resource name}
\\
\newnonterminal{system}
\pline{1 byte}{03 hexadecimal}
\pline{4 bytes}{object identifier}
\pline{4 bytes}{class identifier for this object}
\pline{4 bytes}{number of properties}
\pline{\nonterminal{value}$*$}{value of each property}
\\
\newnonterminal{object}
\pline{1 byte}{04 hexadecimal}
\pline{4 bytes}{resource identifier}
\pline{\nonterminal{string}}{resource name}
\\
\newnonterminal{list nodes}
\pline{1 byte}{05 hexadecimal}
\pline{4 bytes}{number of list nodes}
\pline{\nonterminal{list node}$*$}{values of list nodes}
\\
\newnonterminal{list node}
\pline{\nonterminal{value}}{value of first part of list node}
\pline{\nonterminal{value}}{value of second part of list node}
\\
\newnonterminal{timer}
\pline{1 byte}{06 hexadecimal}
\pline{4 bytes}{timer identifier}
\pline{4 bytes}{object that timer will call when it goes off}
\pline{\nonterminal{string}}{name of timer}
\pline{4 bytes}{number of milliseconds until timer goes off}
\\
\newnonterminal{user}
\pline{1 byte}{07 hexadecimal}
\pline{4 bytes}{user account number}
\pline{4 bytes}{user object identifier}
\\
\newnonterminal{string}
\pline{$n$ bytes}{null-terminated ASCII string}
\\
\newnonterminal{value}
\pline{4 bytes}{tagged Blakod value (4 bits type, 28 bits value)}

\end{protocol}
