%* 
%* ------------------------------------------------------------------
%* Role PlayingDB V2.0 by Deepwoods Software
%* ------------------------------------------------------------------
%* DataFormats.tex - Data Formats
%* Created by Robert Heller on Wed Dec 30 17:24:07 1998
%* ------------------------------------------------------------------
%* Modification History: 
%* $Log: DataFormats.tex,v $
%* Revision 1.3  1999/07/14 22:17:34  heller
%* Eddy's Edits.
%*
%* Revision 1.2  1999/01/02 17:15:52  heller
%* Spell Checked.
%*
%* Revision 1.1  1999/01/02 17:12:20  heller
%* Initial revision
%*
%* ------------------------------------------------------------------
%* Contents:
%* ------------------------------------------------------------------
%*  
%*     Role Playing DB -- A database package that creates and maintains
%* 		       a database of RPG characters, monsters, treasures,
%* 		       spells, and playing environments.
%* 
%*     Copyright (C) 1995,1998,1999  Robert Heller D/B/A Deepwoods Software
%* 			51 Locke Hill Road
%* 			Wendell, MA 01379-9728
%* 
%*     This program is free software; you can redistribute it and/or modify
%*     it under the terms of the GNU General Public License as published by
%*     the Free Software Foundation; either version 2 of the License, or
%*     (at your option) any later version.
%* 
%*     This program is distributed in the hope that it will be useful,
%*     but WITHOUT ANY WARRANTY; without even the implied warranty of
%*     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%*     GNU General Public License for more details.
%* 
%*     You should have received a copy of the GNU General Public License
%*     along with this program; if not, write to the Free Software
%*     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
%* 
%*  
%* 

\chapter{Data File Formats}
\label{DataFormats}
\typeout{$Id: DataFormats.tex,v 1.3 1999/07/14 22:17:34 heller Rel1 $}

\section{Class Data Object Record Files}

Except for the Map Data files, all of the other data files are
serializations of C++ class structures.  These files are read and
written using Tcl's file I/O functions from internal Record class
structure members in each of the class structures.  Each of these
records consists of a header key string starting with an asterisk (*)
followed by the name of the class as a NUL terminated string.  The rest
of the record is a sequence of NUL terminated strings that start with a
key character, a percentage character (\%), and a data value string.  The
record is terminated with a line-feed character and a NUL byte.


\subsection{Character Data Object Files}

The Character Data Object File contains the key characters listed in
Table~\ref{tab:Character}.  The file starts with the key string {\tt
*Character}. 

\begin{table}
\begin{tabular}{|l|l|p{2in}|}
\hline
Char & Value & Type of data \\
\hline
s & Strength & Decimal integer string \\
i & Intelligence & Decimal integer string \\
w & Wisdom & Decimal integer string \\
d & Dexterity & Decimal integer string \\
c & Constitution & Decimal integer string \\
h & Charisma & Decimal integer string \\
e & Exceptional Strength & Decimal integer string \\
l & Level & Decimal integer string \\
D & Number Hit Dice & Decimal integer string \\
N & Hit Die Sides & Decimal integer string \\
G & Gold Pieces & Decimal integer string \\
n & Character Name & Text string \\
p & Player Name & Text string \\
r & Character Race & Text string \\
C & Character Class & Text string \\
a & Character Alignment & Text string \\
S & Character Gender & Text string \\
A & Character Age & Decimal integer string \\
T & Commentary & Text string \\
I & Image & Text string, a GIF file name \\
\hline
\end{tabular}
\caption{Key Characters used in Character Data Object Files}
\label{tab:Character}
\end{table}

\subsection{Monster Data Object Files}

The Monster Data Object File contains the key characters listed in
Table~\ref{tab:Monster}.  The file starts with the key string {\tt
*Monster}. 

\begin{table}
\begin{tabular}{|l|l|p{2in}|}
\hline
Char & Value & Type of data \\
\hline
n & Monster Name & Text string \\
a & Monster Alignment & Text string \\
t & Treasure Type & Text string \\
x & Special Attacks & Text string \\
d & Special Defenses & Text string \\
p & Psionics & Text string \\
T & Commentary & Text string \\
I & Image & Text string, a GIF file name \\
H & Hit Points & Decimal integer string \\
D & Number Hit Dice & Decimal integer string \\
N & Hit Die Sides & Decimal integer string \\
A & Hit Point Adjustment & Decimal integer string \\
X & Armor Class & Decimal integer string \\
m & Land Speed & Decimal integer string \\
f & Flying Speed & Decimal integer string \\
s & Swimming Speed & Decimal integer string \\
b & Burrowing Speed & Decimal integer string \\
w & Web Speed & Decimal integer string \\
l & Percent in Lair & Decimal integer string \\
u & Number of Attacks & Decimal integer string \\
M & Magical Resistance & Decimal integer string \\
$+$ & Minimum Damage per Attack & Decimal integer string \\
$-$ & Maximum Damage per Attack & Decimal integer string \\
! & Minimum number appearing & Decimal integer string \\
@ & Maximum number appearing & Decimal integer string \\
i & Intelligence Rating & Text string (rating string) \\
q & Frequency & Text string (frequency class) \\
h & Hit Type & Text string (``Points'' or ``Dice'') \\
S & Size & Decimal floating point string \\
\hline
\end{tabular}
\caption{Key Characters used in Monster Data Object Files}
\label{tab:Monster}
\end{table}

\subsection{Spell Data Object Files}

The Spell Data Object File contains the key characters listed in
Table~\ref{tab:Spell}.  The file starts with the key string {\tt
*Spell}. 

\begin{table}
\begin{tabular}{|l|l|p{2in}|}
\hline
Char & Value & Type of data \\
\hline
l & Level & Decimal integer string \\
R & Range & Decimal integer string \\
F & Flag bits & Two hexadecimal characters \\
n & Spell Name & Text string \\  
C & Spell Class & Text string \\
t & Spell Type & Text string \\
d & Spell Description & Text string \\
a & Spell Area of Effect & Text string \\
T & Spell Casting Time & Text string \\
D & Spell Duration & Text string \\
s & Saving Throw & Text string \\
\hline
\end{tabular}
\caption{Key Characters used in Spell Data Object Files}
\label{tab:Spell}
\end{table}

\subsection{Treasure Data Object Files}

The Treasure Data Object File contains the key characters listed in
Table~\ref{tab:Treasure}.  The file starts with the key string {\tt
*Treasure}. 

\begin{table}
\begin{tabular}{|l|l|p{2in}|}
\hline
Char & Value & Type of data \\
\hline
W & Weight & Decimal integer string \\
A & Armor Class Adjustment & Decimal integer string \\
T & To Hit Adjustment & Decimal integer string \\
D & Damage Adjustment & Decimal integer string \\
M & Magical Resistance Adjustment & Decimal integer string \\
P & Damage Protection Adjustment & Decimal integer string \\
s & Strength Adjustment & Decimal integer string \\
i & Intelligence Adjustment & Decimal integer string \\
w & Wisdom Adjustment & Decimal integer string \\
d & Dexterity Adjustment & Decimal integer string \\
c & Constitution Adjustment & Decimal integer string \\
h & Charisma Adjustment & Decimal integer string \\
g & Land Speed Adjustment & Decimal integer string \\
f & Flying Speed Adjustment & Decimal integer string \\
S & Swimming Adjustment & Decimal integer string \\
v & Value & Decimal integer string \\
n & Treasure Name & Text string \\
C & Description & Text string \\
I & Image & Text string, a GIF file name \\
\hline
\end{tabular}
\caption{Key Characters used in Treasure Data Object Files}
\label{tab:Treasure}
\end{table}

\subsection{TrickTrap Data Object Files}

The TrickTrap Data Object File contains the key characters listed in
Table~\ref{tab:TrickTrap}.  The file starts with the key string {\tt
*TrickTrap}. 

\begin{table}
\begin{tabular}{|l|l|p{2in}|}
\hline
Char & Value & Type of data \\
\hline
n & Trick or Trap Name & Text string \\
T & Trick or Trap Type & Text string \\
C & Description & Text string \\
I & Image & Text string, a GIF file name \\
\hline
\end{tabular}
\caption{Key Characters used in TrickTrap Data Object Files}
\label{tab:TrickTrap}
\end{table}

\subsection{Dressing Data Object Files}

The Dressing Data Object File contains the key characters listed in
Table~\ref{tab:Dressing}.  The file starts with the key string {\tt
*Dressing}. 

\begin{table}
\begin{tabular}{|l|l|p{2in}|}
\hline
Char & Value & Type of data \\
\hline
n & Dressing Name & Text string \\
v & Value & Decimal integer string \\
C & Description & Text string \\
I & Image & Text string, a GIF file name \\
\hline
\end{tabular}
\caption{Key Characters used in Dressing Data Object Files}
\label{tab:Dressing}
\end{table}

\subsection{Space Data Object Files}

The Space Data Object File contains the key characters listed in
Table~\ref{tab:Space}.  The file starts with the key string {\tt
*Space}. 

\begin{table}
\begin{tabular}{|l|l|p{2in}|}
\hline
Char & Value & Type of data \\
\hline
x & Center X coordinate & Decimal floating point string \\
y & Center Y coordinate & Decimal floating point string \\
s & Shape Type & Text string (``Square'' or ``Hexagon'') \\
n & Space Name & Text string \\  
C & Space Description & Text string \\
b & Background Color & Text string (color name) \\
e & Exit Element & Text string (exit description string, see
Figure~\ref{fig:exitRec}) \\
i & Item Element & Text string (item description string, see
Figure~\ref{fig:itemRec}) \\
\hline
\end{tabular}
\caption{Key Characters used in Space Data Object Files}
\label{tab:Space}
\end{table}

\begin{figure}
\begin{centering}
\verb=%ex.xx\0y.yy\0A\0type\0descr\0image\0nextspi\0\r\0= \\
Where x.xx and y.yy is the relative offset of the exit, A is the
alignment flag and is either a T or an F, type is the type of exit
(listed in Table~\ref{tab:exitTypes}), descr is the description, image
is the name of a GIF file to display for the exit, and nextspi is the
next space index string.
\end{centering}
\caption{Exit Description String}
\label{fig:exitRec}
\end{figure}

\begin{table}
\begin{tabular}{|l|p{3in}|}
\hline
Type & Description \\
\hline
Doorway & Open doorway \\
Door & Normal door \\
LockedDoor & Locked door \\
SecretDoor & Secret (hidden) door \\
OnewayDoor & One way door \\
TrapDoorUp & Trap door in ceiling \\
TrapDoorDown & Trap door in floor \\
StairsUp & Ascending stairs \\
StairsDown & Descending stairs \\
WindowUnglazed & Unglazed window \\
WindowGlazed & Glazed window \\
Chimney & Chimney or hole in the ceiling \\
Pit & Pit or hole in the floor \\
\hline
\end{tabular}
\caption{Exit Types}
\label{tab:exitTypes}
\end{table}

\begin{figure}
\begin{centering}
\verb=%ix.xx\0y.yy\0type\0image\0filename\0\r\0= \\
Where x.xx and y.yy is the relative offset of the item, type is the type
of the item (Character, Monster, Treasure, Trick / Trap, or Dressing),
image is the name of a GIF file to display for the item, and filename is
the name of the file with the full description of the item.
\end{centering}
\caption{Item Description String}
\label{fig:itemRec}
\end{figure}

\section{Map Data Files}

Map data files are written directly from Tcl -- there is no C++ class
structure for maps.  Maps are implemented using a Tcl ``array''
variable.  Tcl ``arrays'' are really associative tables implemented with
a hash table.

A Map data file contains a set of name value pairs as shown in
Table~\ref{tab:mapFile}. 

\begin{table}
\begin{tabular}{|l|p{3in}|}
\hline
Name & Value \\
\hline
\hline
shape & The shape of the spaces, either Space::Hexagon or Space::Square. \\
\hline
name & The name of the map. \\
\hline
description & The description of the map. \\
\hline
deepestLevel & The level deepest in the ground (most positive numerical
value). \\
\hline
highestLevel & Highest level at or above the ground (0 = ground level,
negative values are above ground). \\
\hline
maxX & Maximum (rightmost or ``easternmost'') X coordinate. \\
\hline
maxY & Maximum (bottommost or ``southernmost'') Y coordinate. \\
\hline
minX & Minimum (leftmost or ``westernmost'') X coordinate. \\
\hline
minY & Minimum (topmost or ``northernmost'') Y coordinate. \\
\hline
Spaces,l,x,y & Filename of the Space Data Object at level l at x,y. \\
\hline
\end{tabular}
\caption{Name Value Pairs in a Map Data File.}
\label{tab:mapFile}
\end{table}