\documentclass[a4paper,11pt]{article}

\begin{document}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Introduction}

\subsection{Customer Requirements}

This project aims to create a computer version of the board game conquest. 
This computer game should allow multiple players possibly playing over the
internet and there should be the option for a computer player.

\subsection{Personal Requirements}

The above customer specification is very open and can be implemented in a 
number of different ways. This project aims to achieve the following goals:-

\begin{itemize}

	\item	Create a design structure that will allow other developers to create
   		their own board games very simply using the existing source code from
   		the conquest game.

 	\item	Since the games are to be played over the internet the code should be
   		made as portable as possible so that the game is available to the 
   		maximum number of players.

	\item	The clients should as far as possible be independent of the game that
   		they are used for. These generic clients would allow developers more
   		time to concentrate on the actual game and users would not need to
   		keep lots of different client programs.

\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Design}

There are two sections to the design for this project. First there is the
overall system architecture design i.e. what the various components of the
system are and how they fit together. Secondly there is the actual design
for each of the components this will be loosely based on the Object
Modelling Technique (OMT) as described by Rumbaugh.

\subsection{Development Environment}

The language chosen for the project is C++, this will allow the creation
of a collection a classes with a well defined API for other future
developers. This will also give me some solid experience programming
in what has become one of the most important development languages in
business.

The compiler used will be the GNU g++ compiler version 2.7.2 which is
freely available on a number of different machines and comes with the
libg++ class library. This library contains many useful classes such
as lists, vectors and also the GNU implementation of STL (standard
template library) from the upcoming ANSI C++ specification.

The project will be primarily developed on an Amiga A4000 with the
Suns (SunOS 4.1.3) being used to check on portability and for demonstrations.

\subsection{Architecture}

There are a number of possible approaches that can be taken to implement
the game all of which involve the following elements :-

\begin{description}

	\item[Server] 	Passes the information about the players moves and
		 	game status to all the players.

	\item[Client]	Display a representation of the game board and enable
		 	the player to play the game communicating if necessary
		 	with other players.

	\item[Game] 	The game itself, the positions of pieces on the board,
		 	who is playing and results.

	\item[Rules] 	Some set of rules that must be obeyed during the gameplay.

\end{description}

Different configurations of these four elements can give rise to very
different implementations which may or may not achieve the targets given
in the introduction.

\bigskip
\noindent {\large {\bf Type 1}}
\bigskip

The game, rules, client and server are combined into a single program that
each player runs. Each program is both the client and the server for all 
the other players in the game.

This approach leads to a large amount of duplication and does not achieve the
aim of game independent clients. The other problem here is that any computer
player must be built into the game program making it even larger..


\bigskip
\noindent {\large {\bf Type 2}}
\bigskip

This is similar to the type 2 approach above only in this case the server
is now independent from the client, possibly on a remote machine, all 
communication passes through this central server which takes on the job
of controlling the gameplay.

This again suffers from the duplication of the rules systems and the fact
that the client is still dependent on the game type.

\bigskip
\noindent {\large {\bf Type 3}}
\bigskip

The game becomes an abstract object simply holding information about the
current situation. It acts as a central arbtitor for other processes
to communicate between each other. e.g when the network process receives
a move from a player the game process reads it and passes it onto the 
rules process for evaluation, the rules process then informs the game
what is required and the game passes the information back to the player
via the network process.

The client in this case is just a dumb interface with a very simple protocol
telling it how to draw the board. This is a similar situation to the
X client/server. 

The approach here allows both the client and server to be generic even at run
time since the only things that are game dependent are the rules.
Unfortuantely this approach cannot easily be made portable due to its
multitasking nature.

The computer player would itself act as a client to the server either
using its own local version of the game rules or in the ideal situation
evaluating the game remotely based on the information it requests from
the server i.e. a game independent computer player. 

\bigskip
\noindent {\large {\bf Type 4}}
\bigskip

This is similar type 3, there is a server for each game type. This server
contains the rules, positions, status of the game and any networking. Dumb
clients connect to it as in the type 3 approach. The type 3 multitasking
architecture is kept within single server program as C++ message passing
between objects.

This architecture is probably the closest match to the target conditions
and could probably be improved even further on systems which allow the
use of runtime libraries, on these systems the server would be able to
offer a range of games.

\subsection{Considerations}

Having chosen an overall system architecture it is now necessary to consider
some of the performance and system impact issues.

\begin{description}

	\item[network bandwidth]	The X like approach for the client/server could
			    		potentially place strains on a network. However
			    		given that this is a board game the amount of
			    		traffic would not be expected to be high.

	\item[Speed]			Again this is a board game which is played at a
			    		relatively slow rate. There should be no noticable
			    		effect on any machine running either the server
			    		or the client.

	\item[Memory]		  	Both client and server programs should not require
			    		much memory unless games are played on huge boards
			    		(e.g. > 100x100).

	\item[Size]			On the client side only one relatively simple
			    		program will be required for a number of different
			    		board games so there should be no problem here.
			    		For the server if the server is capable of
			    		multiple game types then this could push the size
			    		up but not excessively.

			   		The use of C++ will make the executables larger
			    		than that of a more traditional language such as C.

\end{description}

\subsection{Specificcation}

%%%%%%%%%%%%%%%%%%%%
% TODO
%%%%%%%%%%%%%%%%%%%%

\subsection{Modelling the Game}

\subsubsection{Object Model}

The first step is to split the game up into a number of classes. This
generally proceeds by indentifying real life objects with classes and
then eliminating the excess and unecessary classes.

For the game there are two separately identifyable groups of classes,
the actual classes involved with the gameplay and those involved with
the players.

%
% figure - object model
%

The classes are as follows:-

\begin{description}

	\item[Game]	Top level class for controlling gameplay etc.
	\item[Board]	The board for the game - contains a number of squares.
	\item[Square]	A area of the board that may or may not contain a piece.
	\item[Piece]	These are the items that are actually used in the gameplay
			each piece has a set of rules associated with it.
	\item[Rules]	A set of rules that each piece must obey during moves etc.
	\item[Team]	A group of players involved in the game.
	\item[Player]	The active participants of the game who make the moves.

\end{description}

This model is still completely general and could describe any board game,
these classes will form the base classes from which the classes specific
to a particular game will be derived.

\subsubsection{The Dynamic Model}

Stage 2 invloves determining the actions of the classes in response to changes
in state or events - a dynamic model. The overall dynamic model for the system
is actually very simple.

%
% figure - dynamic model
%

Once the game has started the game wait for the active team to move, if the
move fails then the active team tries again until a move succeeds. At this
point if the game has not ended the next team becomes active and the process
starts again.

\subsubsection{The Functional Model}

Having obtained static and dynamic models for the game the final stage is
to create a functional model this describes how the data flows through the
system and the various actions of the system. In this case the entire system
is highly interconnected so a diagram of the function model would probably
only serve to confuse. Instead lists of actions involved during a few of the
most important processes are given below.

At the highest level there the actual gameplay, controlling which team is
responsible for making the next move and checking to see if the game has
ended for any reason.

\begin{enumerate}

	\item Select Team that has to make move
	\item Tell Team to make a move and waits for completion
	\item Team selects player to make the move and waits for completion
	\item Player sends message to player informing that input is required
	\item Player attempts moves until success
	\item Check if game has finished, if it has then send messages
	      to each Team with appropriate messages.
	\item Repeat process until game has finished

\end{enumerate}

The second main point for events is when the Player class is in contact
with the player since this is the point at which the protocol is 
interpreted.

\begin{enumerate}

	\item Wait for data from player
	\item Read command 
	\item Process command with any data provided
	\item Repeat until successful move has been made

\end{enumerate}

At the next level is the communication to the players, this can be to
an individual player, a team or all players. This is the method by 
which all communication between the client and server is made.

\begin{enumerate}

	\item Message sender composes the message
	\item Sender gives message to Game class
	\item Game passes message to any Teams that require it
	\item Team passes message to any Players that require it
	\item Player sends message to actual player

\end{enumerate}

The move is perhaps the most complex of the interactions since every
class is required to become involved at some stage. If for any reason 
the move fails then the class where the failure occurs must check
send a message to the player making the move saying that there has
been an error and the cause of that error.

\begin{enumerate}

	\item Player class receives move from player
	\item Player class decoded move and places it in correct data
	      format for piece.
	\item Player class passes move to Team class as the teams move
	\item Team class passes move to Game class to carry out
	\item Game class gives move to board to carry out
	\item Board examines move to locate square that piece being moved
	      occupies.
	\item Board passes move to appropriate square
	\item Square passes move to piece if it is occupied
	\item Piece now attempts to move itself
	\item Piece queries Rules to check if move is valid
	\item Rules checks move against the rules
	\item Piece queries Rules if any pieces are captured in the move
	\item Rules creates list of captured pieces
	\item Piece queries Rules to see if game result has been set
	\item Piece goes ahead and moves itself
	\item Piece tells Square it is on to clear itself
	\item Square marks itself as empty 
	\item Piece tells destinatation square that it is occupying it
	\item Square marks itself as being occupied by the piece
	\item Piece tells Rules to remove all captured pieces from the game
	\item Rules tells each piece to remove itself
	\item Piece tells square it is no longer occupied
	
\end{enumerate}

\subsection{The Classes in Detail}

Now that the model has been established it is necessary to divide up the
various responsiblities into the classes. All the gameplay group of
class share an attribute, they all have a name or type which can be accessed
via the function Type.

\subsubsection{Game Class}

This is the top level of the game when the a game is started a Game class
is created. This in turn has to go on to create the board and the correct number
of teams to play the game. At this stage the game is ready to be played
(assuming that players have actually joined the teams) so the Game class must
go into its gameplay mode of operation and control the way the game is played.
This means switching between teams ready for their turn then after the move
has been made checking to see if that move has decided the result of the game.
The final job of the Game class occurs after the game has been decided. At
this point the Game class must give the players appropriate result messages
and then shut everything down i.e. remove the board and the teams.

%
%  figure - CRC Game
%

\subsubsection{The Board Class}

The board is where all the gameplay takes place, it consists of a rectangular
array of squares and may have a variable size. When the board is created the
array of Square class objects is created. During gameplay these squares are
access via the Board class to ensure that only squares at valid coordinates
are used. The load/save pair of functions of the Board class are used to set
up a particular type of board with pieces in preparation for the game.
The final responsibility of the Board class is to actually draw the board when
requested or after every move, this could be an full or incremental redraw.
After the game has finsihed and the before the Board class is destroyed it
first removes all the squares.

%
%  figure - CRC Board
%

\subsubsection{The Square Class}

This is one of the simplest classes it has just a couple of purposes. The
first is to keep track of any piece that is occupying it and the second is
to have a particular type e.g. white and black squares as in chess.
The only other thing it has to do is to draw itself if requested, this will
also involve sending a message to the occupying piece to draw itself
afterwards.
When the square is destroyed it must also remove any piece that may be
occupying it otherwise the piece will become 'lost'.

%
% figure - CRC Square
%

\subsubsection{The Piece Class}

This class together with the Rules class are the key elements of any game.
Apart from the general housekeeping task such as keeping track of the team
that owns the piece and informing the Squares it moves between its main task
is the move. Together with the Rules class for every move it must check that

\begin{itemize}

	\item The move is valid
	\item If the move results in any pieces being captured or created
	\item If the move ends the game for any reason

\end{itemize}

After these checks have been made it is then free to go ahead with the move
i.e. place piece at new location, capture any pieces etc.

%
% figure - piece CRC
%

\subsubsection{The Rules Class}

The Rules class has 2 main purposes, the first is to know what rules the piece
must obey for a move and the second is to know the way in which a piece moves
so that it can move the piece after the move has been accepted.

%
% figure - Rules CRC
%

\subsubsection{The Team Class}

This is basically just a container for a number of players it directs messages
to specific players and keeps track of a single active player who is
responsible for making the teams move for the current turn.

When the game ends and the team is destroyed it does not destroy the Player
classes it contains, since the players may wish to play another game, it
simply informs the Player classes they are no longer part of a game.

%
% figure - Team CRC
%

\subsubsection{The Player Class}

This is the key point of interaction between the server and a particular
player, each Player class has a single real player and network connection
associated with it.

The Player class is responsible for all contact with the server and a
particular player. When a message is recieved from a player the Player class
interprets it according to the protocol and then carries out the request or
passes the request to another class for execution.

%
% figure - Player CRC
%

\subsection{The Server}

Given the above classes the server is relatively simple to implement, all that
has to be done is to create a communication channel of some type. When a
connection request arrives then the channel is assigned to a Player. After all
requests have been satisfied a Game class object can be created and the
Players classes can join up in Teams as desired. The only thing remaining then
is to start playing.

The process of forming teams and joining the game can be expanded upon as
required, the above example is only a simple case.

The Player class creation is the job of the main server program since these
may exist independently of the Game class to allow for flexibility, it also 
enables the Player to exist over many games rather than having to start the
connection again each time a game ends.

\subsection{The Client}

At the simplest level the client is very simple since all it has to do is
keep a local copy of the appearance of the board and update it as the game
progresses. The other job for the client is to pass on the players moves and
requests to the server and to interpret and display the servers responses.

The client can be made game independent by ensuring that all that has to be
displayed is the bitmap of a square or piece at a particular location or in
the abscence of a bitmap the name of the bitmap that should have been
displayed will enable the user to still see the board since the protocol will
be designed to be text based.

Since the protocol is text based a separate client is not absolutely necessary
as the game could be played via terminal session (e.g telnet host game\_port).
This will also help in the testing.
   
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{The Board Game Protocol - rfcXXXX}

\subsection{General Details}

The protocol is designed to be fully ascii text readable via a telnet session
each protocol message consists of a single line terminated by <CR><NL> or
<NL> the message may be either in upper or lower case.

Each messsage consists of two parts, a command word such as DRAW or MOVE
followed by the options for that command.

The protocol is still under development so that only the commands required for
a simple client are defined. As development continues the GAME commands will
be extended to allow for more control of the game and additional commands will
be added for pre-game setup.

\subsection{Bi-Directional Commands}

These Commands may be sent by either the client or the server.

\subsubsection{GAME}

This is a general purpose command indicating that game information follows
or that a game control message is being sent. This will be extended as the
protocol develops. Currently only the following messages are understood.

\begin{verbatim}

	GAME QUIT

\end{verbatim}

Client tells server that it is leaving the game, if the client is the last
member of a team then this implies that the team has resigned.

\begin{verbatim}

	GAME TYPE Conquest

\end{verbatim}

Server tells client that a game of conquest is starting.

\begin{verbatim}

	GAME BOARD ConqustBoard 9 8

\end{verbatim}

Server tells client that the game is being played on a ConquestBoard of
size 9 by 8 (x,y).

\subsection{Client to Server Commands}

\subsubsection{MOVE}

This command informs the server of a move that the player is making, it should
be followed by a series of numbers. The first number is the number of squares
that are involved in the move, this is followed by the coordinates of each
square in turn starting with the square that the piece being moved currently
occupies.
The coordinates of squares start in the lower left corner of the board at
(1,1) with $x$ coordinate being given first.

\begin{verbatim}

	MOVE 2 1 1 1 6

\end{verbatim}

Moves the piece at square (1,1) to square (1,6)

\begin{verbatim}

	MOVE 3 1 1 1 5 2 5

\end{verbatim}

Moves the piece at square (1,1) to (1,5) and ending up at (2,5)

If the move is successful there will be a reply from the server containing
messages describing how the board needs to be updated, otherwise if there was
a problem with the move the server will respond with an error message. e.g.

\begin{verbatim}

	ERROR You do not own that piece

\end{verbatim}

\subsection{Server to Client Commands}

\subsubsection{ERROR}

This is a simple status response informing the client that an error has
occured in response to the request made by the client. The message will be
composed with the keyword ERROR and then a text description of the cause of
the error.

\begin{verbatim}

	ERROR The destination square does not exist

\end{verbatim}

\subsubsection{RESULT}

Again this is a status command informing the client that the game is now
finished and the outcome of the game, win, lose or draw. The final part of the
message is a text description of the exact way the game has been won.

\begin{verbatim}

	RESULT WIN Your team has won
	RESULT LOSE Your team has resigned

\end{verbatim}

\subsubsection{DRAW}

This command is issued by the server to tell the client to draw a particular
piece or square. 

If drawing a square the command will be followed by the word SQUARE followed
by the type of square to be drawn and then the coordinates of that square on 
the board.
When a piece is being drawn the command will be followed by the word PIECE 
and then a single word which describes the type of piece and any specific 
orientation details for that piece (e.g. the faces of a die), this word should 
be interpreted as the name of the file containing the image to be drawn. The 
final part of the draw piece message is the team number of the side owning the 
piece so appropriate colour adjustments can be made. The piece should be drawn 
at the location of the last square that was drawn.


\begin{verbatim}

	DRAW SQUARE white 1 1
	DRAW SQUARE black 1 6
	DRAW PIECE die123 1

\end{verbatim}

This informs the client to draw a white square at location (1,1) a black
square at location (1,6) and then the draw a die piece with faces 123 and a
team number of 1 at location (1,6)

\subsubsection{READY}

This command is simple to inform the client that the server is now expecting
input from it. There are no options following the keyword.

\subsection{A Simple Client Session}

\begin{verbatim}

Connection to server and wait for other players to join in

	GAME TYPE Conquest
	GAME BOARD ConquestBoard 9 8
	DRAW SQUARE white 1 1
	DRAW PIECE die536 1
	READY
	MOVE 2 1 1 1 5
	ERROR The range dies not match the value shown
	READY
	MOVE 2 1 1 1 6
	DRAW SQUARE white 1 1
	DRAW SQUARE black 1 6
	DRAW PIECE die326 1
	DRAW SQUARE key 5 8
	DRAW SQUARE white 5 7
	DRAW PIECE key111 2
	READY
	GAME QUIT
	RESULT LOSE Your team has resigned

\end{verbatim}

The client connects to the server and is told that a game of conquest will be
played on a conquest board of size 9 by 8. The server the draws all the
squares and pieces on the board in their initial positions (left out except
for 1 example of each) and then informs the client that is waiting for input.
The client responds by making a move which the server decides is not allowed
and therefore replies with an error message explaining the failure. The server
prompts the client for input again and the client responds with another move
which accepted this time so the server sends the board update details. Another
team now makes their move and the server updates the board before requesting
some more input from the client. This time the client decides that it wants to
leave the game and in this case it means that the clients team resigns. The
servers final message is tho inform the client that its team has lost.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Game Implementation}

Only the Player class is designed to be dirctly instantiated, they are
abstract class which exist only to provide a general public interface to be
used by the derived specialised classes.

In all classes of the actual game contain a character array which contains a
string describing the type of the class, this is accessed via the common Type
method.

The classes often contain pointers to other classes, for example the Game
class contains a pointer to the board class. This pointer is a pointer of the
base class type, however when an object is assigned to it the object will be a
derived class. This is a feature of C++ which allows a pointer of a base class
to be used for any class derived from it, in doing this the base classes can
be made very general. This can leads to problems when actually refering to the
objects via this pointer since the compiler must assume that the object is a
class of the same type as the base class.
As a result of this problem the wrong function can be invoked especially where
virtual functions are being used. There are two ways around this problem:-

\begin{itemize}

	\item 	The pointer can be cast to the correct type before use, however
		this means that the required type must be known and therefore
		the generality of some functions is lost.

	\item	Use two stage function calls, a main public function which
		calls the protected virtual function. This gets around the 
		problem since the call to the virtual function now occurs
		within the class and the class has self knowledge of what type
		it is.

		\begin{verbatim}

		class dummy {

                  public:

                    int func( void ) { Dfunc(); }

                  protected:

                    virtual int Dfunc( void ) { some code }

		}

		\end{verbatim}

\end{itemize}


All classes except for the player class which can exist independently contain
pointers to all the classes that they are contained within. For example the
Board class has a pointer to the Game class that it part of and the Square
class has pointers to the Board class and the Game class that hold it. This
enables quick and simple message passing between the low level and high level
classes, high to low level messages still need to go through every
intermediate class since there are often access restrictions to obey for
messages in that direction.
 
\subsection{Game Classes}

\subsubsection{Data Members}

The members of the play reflect the participants of a real game there is a
board and there are a number of teams of players. The board can be held by a
pointer to a Board class object, this can then be initialised with the actual
type of board needed by the derived class. The teams can be held in an array
of Team class objects since the number of teams in a game is known in advance
by the derived game class. 

The only other data items needed are some kind of variables to keep the games
result in. This is required since the result cannot be handled by a lower
level class such as the Piece class, if that happened then the functions calls
sequence would become complicated and unclear. There would also duplication
since moving pieces is not the only way of causing a game to end. The result
can be stored as a single integer value with a second integer containing the
team id for the team that created the result.

\subsubsection{Methods}

In terms of required functions the Game class is very simple since it actually
has very few tasks to do. The model defines a few of the functions with the
others being obvious results of the way in which the classes communicate and
the data members.

\begin{description}

	\item[{\bf Constructor}]	

The constructor has to initialise the data and create the teams - the
derived class creates the board. 

	\item[{\bf Destructor}]

This must remove the teams and board, these in turn clear up any lower level
objects.

	\item[{\bf SelectTeam()}]

This is one of the access functions, it exists to protect the array of teams.
If a pointer to a team playing in the game is needed then this function is
called with the teams id number (range 1 - num\_teams) and a pointer to the
team is returned if the team id is valid. This can also be used to see if a
particular team exists, this is done in the DLoad() function.

	\item[{\bf SetGameResult()}]

As mentioned earlier the Game class must handle the end of a game at the end
of each move. This requires there to be a way of informing the game about the
result, this is what this function does - it records the result set and the
current team that has caused the result then after the move the Game class can
use the information to end the game properly if it needs to.

	\item[{\bf Move()}]

This is basically just to pass the move onto the board from the team since
the Team class does not know how to talk to the Board class.

	\item[{\bf MsgToPlayer() and MsgToAll()}]

These functions are used by the gameplay classes to pass a formatted protocol
message back to a number of real players. The MsgToPlayer() function goes to the
currently active player of the currently active team and is used for error
messages in response to moves. MsgToAll() goes to all players in all the
teams and is used for sending information such as board updates after moves.

\end{description}

\subsubsection{Private and Protected Methods}

\begin{description}

	\item[{\bf SendDetails()}]

At the start of the game the clients need to know various pieces of
information about the game they are involved with. This method is responsible
for providing that information, it sends details about the game type, board
type, board size and then draws the complete board for the client in its
starting position.

	\item[{\bf HandleResult()}]

This is the function that is called at the end of each move to evaluate any
results that have been set with SetGameResult(). It figures out if the game is
over and sends out appropriate messages to the players about the result e.g.
if one team has resigned it will send a message to all the players of that
team that they have lost and to the other team the message will be that their
opponents have resigned and that they have won.

This function is made virtual so that it can be replaced if the game type does
not conform with the way that it works e.g. different result types, more that
2 sides in a game.

\end{description}

\subsection{Board Class}

\subsubsection{Data Members}

There are relatively few data items that the Board class needs since it serves
primarily as a way of accessing the squares and pieces. Apart from a pair of
integers to contain its size the only important data is the array of Square
classes that is the internal representation of the board. This array is a 2D
array with the same size as the board, each element represents a single
square. The elements are actually pointers to squares so that the base Board
class can initialise array of the correct size and leave the final creation of
the squares to the derived classes which know what type of squares to create.

\subsubsection{Public Methods}

The methods in this class are mainly access function to get hold a particular
square on the board or a piece on that square. They serve to protect the
members from bad read attempts.

\begin{description}

	\item[{\bf Constructor}]

The constructor has only to initialise the size members and create an
appropriately sized array of pointers to squares for the derived class to use.

	\item[{\bf Destructor}]

The destructor also has very little to do, it just frees memory allocated for
the array of squares.

	\item[{\bf Size()}]

Another simple function it just fills in the arguments with the size of the
board.

	\item[{\bf SelectSquare()}]

This is probably the most used function it returns a pointer to the square at
the specified coordinates. It is the only way of accessing the squares from a
higher level class and as such protects the squares array from bad accesses.
It also serves to identify if a square at a particular coordinate is on the
board.

	\item[{\bf IsOccupied()}]

This is an extension of the above function to access the piece that may or may
not be occupying a square at the specified coordinates.

	\item[{\bf RemovePiece()}]

Similar to the IsOccupied() function except that it removes any piece that is
occupying the square at the coordinates given.

	\item[{\bf ClearBoard()}]

Removes every piece on the board this is mainly used internally for things
like clearing all the pieces before a new set are loaded in.

	\item[{\bf Move()}]

This is where the first part of checking the validity of a move occurs, the
function checks if there is actually a piece to move at the coordinates given.
If there is it passes the move on to that piece otherwise an error message is
sent back to the player.
If the move is successfuly then the board goes on to update the display to
reflect the new positions of the pieces.

	\item[{\bf Load()/Save()}]

This is a situation as described at the start of the section where dummy
functions are needed. In this case the Load() and Save() functions simply call
the DLoad() and DSave() functions respectively. The purpose if this pair of
function is simply to be able to save the position of the pieces to a file and
then restart from that position after loading it in.

	\item[{\bf Draw()}]

This function simply tells all the squares to draw themselves, the squares in
turn draw an pieces that are on them.
 
\end{description}
  
\subsection{Square Class}

\subsubsection{Data Members}

The Square class also has very few necessary members, it needs to know its
position on the board since it is very difficult for the Board class to work
it out given just a pointer to the square. It also needs to contain a pointer
to a Piece class object, this will contain a piece if the square is occupied
or NULL if there is no piece there.

The only other data item if a flag which indicate if the square needs a
redraw. By doing this only the squares that need to be updated are redrawn
instead of all the squares thus saving bandwidth and processing.

\subsubsection{Public Methods}

\begin{description}

	\item[{\bf Constructor}]

This has basically got to initialise the members, i.e. make the piece variable
NULL indicating no piece is on the square and set the redraw flag so the first
draw causes the square to be drawn.

	\item[{\bf Destructor}]

The only thing the destructor has to do is remove any piece that happens to be
occupying the square.

	\item[{\bf Location()}]

This provides a way of finding out the location of the square by filling the
arguments with its location.

	\item[{\bf IsOccupied()}]

Informs the caller is the square is occupied by a piece and if so returns a
pointer to that piece.

	\item[{\bf Occupy()}]

Informs the square that it is being occupied by the piece given as an
argument, if the square is already occupied then the function must fail.
Causes a redraw on the square being occupied.

	\item[{\bf RemovePiece()}]

Removes any piece currently occupying the square and clears it for another
occupations. If the square is not currently occupied then this should do
nothing.

	\item[{\bf Clear()}]

Informs the square that it is no longer being occupied. This is typically used
by the Piece class when moving a piece. Has no effect apart from causing the
square to be redrawn if the square is already clear. 	 

	\item[{\bf Draw()}]

This is another situation where a dummy function is needed, in this case it
simply call the DDraw() function. This must send a message to all players
telling them to draw a square of type T at position (x,y) if the redraw flag
is set for the square. It needs to then go on to inform any piece occupying
the square to draw itself.

\end{description}

\subsection{Piece Class}

\subsubsection{Data Members}

In this case there are again few items of necessary data, most of that will
appear in the derived classes to describe the properties of the piece. As far
as general data items are concerned there are two important items. The first
is the owner of the piece which is integer containing the team id for the team 
that owns the piece, the second is a pointer to the Rules class that defines
the way the piece behaves this is initialised by the derived class to an
appropriate Rules based class for that piece.

\subsubsection{Public Methods}

\begin{description}

	\item[{\bf Constructor}]

This has to initialise the owner member with the value provided it then needs
to contact the team that it is owned by and inform it that it has a new piece,
this enables the team to keep track of the number of pieces it has.

	\item[{\bf Destructor}]

This is has a cleanup role, it must remove the piece from the square it
occupies, inform the owner that it has lost a piece and finally free the Rules
class that belongs to it.

	\item[{\bf Location()}]

This queries the square that the piece occupies to find the location of the
piece on the board which it returns to the caller via the arguments.

	\item[{\bf Owner()}]

Returns the team id for the team that owns the piece.

	\item[{\bf Move()}]

This is one of the key functions of the board game classes system, this is
where the move is finally evaluated and executed. The rules are first queried
to see if the move is valid. If the move if found to be valid the rules are
again queried to find the pieces that are captured as a result of the move.
Next to be checked is if the move results the end of the game this calls the
game->SetGameResult() function to inform the Game class. The captures can now
go ahead using the rule->DoCaptures() function to do so.
The final stage of the move is to move the piece to its destination using the
SetNewLocation function.

	\item[{\bf Draw()}]

Like Square.Draw() this is again a dummy function which simply calls DDraw()
this in turn sends a message to all the players telling them how and where to
draw the piece. The DDraw function can be overidden if as in the case of
Conquest the pieces require more information to be sent such as die faces.

\end{description}

\subsubsection{Private and Protected Methods}

\begin{description}

	\item[{\bf SetNewLocation()}]


This function does not actually appear in the base Piece class but since it
must appear in any derived class its functionality is described here. This
function has to move the piece to its final destination square which is
established using the rule->GetNewLocation function. This involves clearing
the current square the piece occupied (square->Clear()) then finding and occupying 
the new square (square->Occupy()), this process will automatically cause the relavent
redraw actions to be taken.
Finally the piece must set its new position if necessary e.g. the new
pattern of faces shown after rolling the die in conquest, this will probably
be done using the Rules class in some way.
 
\end{description}

\subsection{Rules Class}

The Rules class is currently just an open base class for future development
which currently does nothing all the rules that are currently used are found
in the PieceRules class, that is what will be described below.

\subsubsection{Data Members}

There is very little data that the PieceRules class requires since it is
essentially a class of functions. Various data items may be required in
derived classes but in the top level class there is only one. 

This data item is a list of pieces captured as a result of a move, it is added
to by the Captures() function and then if the move goes ahead then the the
pieces in it are removed by the DoCaptures() function.

Future versions of this class will also require a second list containing
pieces created by a move. This would be used in games like chess for when a
piece is created.

\subsubsection{Public Methods}

The public interface for the PieceRules class is essentially dominated by 3
virtual functions, these query the rules as to the effects of a move. As has
been seen before they are essential dummy functions which just call the real
function.

There are two sets of functions in the public interface, the first queries the
rules about the move, and the second helps to implement the move once it has
been accepted. This allows for speculative querying of the rules by a computer
player.

\begin{description}

	\item[{\bf Constructor and Destructor}]

This functions have nothing to do since this is a function based class rather
than a data based class.

	\item[{\bf ValidMove()}]

Checks to see if a particular move is valid returning a boolean value. This is
actually done by the DValidMove() function in the derived class.
This basically involves checking the move against each rule that applies to
the piece in turn until either they have all been done or the rule fails the
move.

	\item[{\bf Captures()}]

This finds any pieces that have to be removed as a result of the move and
places pointers to them in the captures list. It then returns TRUE or FALSE if
any pieces have been captured. Again it is a dummy function for DCaptures()
which is actually implemented in the derived class.

	\item[{\bf Results()}]

Checks if the move has determined the result of the game and returns that
results. Also a dummy function which calls DResults() from the derived class. 

	\item[{\bf GetNewLocation()}]

A dummy function for DGetNewLocation() which finds the new location for the
piece after the move. It returns the particular index from of the final square
from the moves array which it is given.

	\item[{\bf DoCaptures()}]

This goes ahead and removes all the pieces in the captures list from the game.
It requires that the Captures() function has been used before this function is
called otherwise the cpatures list may contain pieces captured in a previous
move that was aborted.

\end{description}

\subsubsection{The Rule Functions}

These are the key elements of the whole Rules class idea, they rely heavily on
the C++ inheritence features. A rule function has the following properties

\begin{itemize}

	\item It accepts a move as the argument
	\item It returns TRUE or FALSE if the rule is obeyed
	\item It checks only one aspect ofthe rules for the game
	\item It has no extenal effect on the class

\end{itemize}

The rule function are designed to become more and more specialised through
derivation. At the top level in the PieceRules class the rule function check
for general things such as if a move is on the board, or that the player owns
the piece being moved. In the derived classes these general functions can
either be applied or used in a more specialised way to check game specific
rules.
  
\subsection{Team Class}

The Team class has an essentially administrative role, just keeping track of
players and grouping them together.

\subsubsection{Data Members}

The most important member for the team is the list of players that belong to
it, a doubly linked list is used for flexibility in rotating through the
players. Associated with the players list must be a pointer to the current
player making the moves and also an iterator to enable the next player to be
selected in this case the iterator is a standard STL iterator.

The team also needs to know its numeric id number to pass to other classes
during requests. The id is better than passing a pointer to the class itself
since the class may be destroyed before the pointer is used leaving a hanging
pointer, this way the access is safe via the game->SelectTeam() function.

Finally there is a simple integer count of the number of pieces that the team
owns. This is useful for games like draughts where the game is over when a
team has no more pieces.

\subsubsection{Public Methods}

\begin{description}

	\item[{\bf Constructor}]

This has only to initiasise the number of piece variable to zero.

	\item[{\bf Destructor}]

When the team is shut down it must tell all the players that were part of it
that it no longer exists.

	\item[{\bf ReadyToPlay()}]

Checks if the Team is ready to start a game, this currently involves checking
if there are any players.

	\item[{\bf NumPlayers()}]

Informs the caller how many players are currenly playing for this team.

	\item[{\bf NumPieces()}]

Enables the other classes to find out how many pieces this team owns.

	\item[{\bf Id()}]

Informs the caller the team id associated with the team.

	\item[{\bf ControlToPlayer()}]

This function must choose the next active player to make a move and then pass
control onto that player so that the move can be made.

	\item[{\bf Move()}]

This is for passing the move message onto the Game class after the Player
class has interpreted the request from the player. It adds the team id to the
arguments to allow the ownership of the move to be determined.

	\item[{\bf Addplayer()}]

Adds a player to the team, appending the Player class pointer it has been
given to its list of players. It could also check that the team does not
exceed a certain number of players.

	\item[{\bf RemovePlayer()}]

Removes the player given to it from the team, this should then go on to take
action if there are no more players in the team since the team will no longer
be able to play.

	\item[{\bf MsgToAll() and MsgToPlayer()}]

These functions are equivalent to the functions of the same name in the Game
class. MsgToAll send the message to all players, MsgToPlayer sends the
message to the player that is currently making the move.
If the functions fail then the player involved must be removed from the game
and in the case of MsgToPlayer() the next player must be selected so that the
move can continue.

\end{description}

\subsubsection{Private and Protected Methods}

\begin{description}

	\item[{\bf NextPlayer()}]

This function is responsible for setting the current player variable. In the
default version this simply selecting the next player in the list although
this can be changed by replacing the function in a derived class.
If the no valid player can be found the current player variable must be made
equal to NULL.

\end{description}

\subsection{Player Class}

All the interaction between the player and the server occurs within the Player
class, it is essentially a protocol handler.

\subsubsection{Data Members}

The most important member are the team that the Player belongs to and the
communications channel that the Player talk to real players on, both items are
actually held as pointers to the relavent classes.

The communication has been designed so that with relatively little change it
can use standard i/o, the internet or any other form of communications
channel.

Other items which are not currently used include a player name, player
password and some statistics for the results the player has been involved in.

\subsubsection{Public Methods}

\begin{description}

	\item[{\bf Constructor}]

There are 2 constructors for this class, the first is a default constructor
which allows arrays of Player classes to be created in which case no arguments
can be supplied. Before the player can be used in this case it must be
provided with an active communication channel with RestartPlayer().
The second starts off players with a given communications channel.

	\item[{\bf Destructor}]

This must do serveral things all of which are covered by the FreePlayer()
function which it calls.

	\item[{\bf RestartPlayer()}]

This allows the Player class objects to be reusued by the server. It is
basically an initialisation function setting all the members with appropriate
values. It is used by both the constructor and after the default constructor
has been used or when the server has finished with the current player but
wishes to reuse the Player class.

	\item[{\bf FreePlayer()}]

This clears up when the player decides to leave it has to do a number of
things.

\begin{itemize}

	\item Close down the communications
	\item Remove the player from the team
	\item Mark the class as ready for use

\end{itemize}

	\item[{\bf TeamDisbanded()}]

This function is used by the Team class to inform players when it is shutting
down, the players are then free to join in another game.

	\item[{\bf Send()}]

This is the final step of the process of sending a message to the player. It
forms a direct interface to the communication channel.

	\item[{\bf PlayerEvents()}]

This is where the protocol is actually interpreted, the current implementation
keeps on reading messages from the player until a successful move has been
achieved.
The function interprets the command word of the message from the player then
calls the relavent handler function to process the remainder of the message.
Since the protocol is very simple at the moment there is only a handler
function for the MOVE command.

	\item[{\bf Move()}]

This extracts the move data from the message checking that the data is valid.
It then passes on the move to the Game class via the Team class for execution,
finally it returns a value indicating if the move has been successful or not.

\end{description}

\subsection{Passive Data Structures}

A number of passive data structures exist for passing data around between
classes. 

\subsubsection{Moves Structure}

This is an array of coordinates of squares that the piece moves onto during a
move. The first element is the start square for the piece and the final
element is usually the destination.

\subsubsection{DieStat Structure}

This is a general structure used in conquest for describing the way in which
the die is orientated. It describes the number shown on the top, back and left
faces from which the remainded of the values may be determined.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Developing New Games}

This section describes how a new game can be developed using the board game
classes described. It uses the existing Conquest implementation as an example
of how easy it is. It should be possible using the classes to create a server
for a new board game in less than a day.

For each class the derivations that need to be made and the options available
for doing so are discussed. As new games are contributed and more classes
become available there will be less and less to do.

\subsection{General Information}

\subsubsection{Programming Style}

It is recommended that all code written conforms to the following style to
keep consistsancy for other developers.

\begin{enumerate}

	\item	For each C++ class there is a header file class.h and a
		file for functions class.cc. The header file should contain
		nothing but definitions and necessary includes - no function
		implementations.

	\item 	All local includes should be referenced as if from one
		directory up the tree. e.g. for the include inc.h in directory
		test use.
		
		\begin{verbatim}

		        #include "test/inc.h"

		\end{verbatim}

	\item	ALL functions should be defined in the .cc file no matter how
		simple they are (they can be inlined for optimization). Each
		function should have at least the following items.

		\begin{itemize}

			\item 	A comment block desribing its prupose
			\item	A conditional compilation debug code (see any
				file for example)

		\end{itemize}

	\item 	Definitions or constants that are likely do be used in many
		different areas it should be collected together in a single
		header file and placed in the General directory.

\end{enumerate}

\subsection{The Main Server Program}

This can actually be very simple. All that is required is to create a master
socket (MSSocket class) which is ready to accept connections, once the master
socket is ready the program should wait on connection requests assigning each
to a Player class object as they come in. When enough players have connected
the game class can be instantiated and the players assigned to teams. To start
the game the game.Play() function is called, this does not return until the
game has completed.

\subsection{Game Class (required)}

The complexity here depends very much on the game that is being implemented.
It is recommended that all game specific definitions and constants are placed
in a header file gamename.h which should be placed in the General directory
since these values may also be needed by the client.

Example files Game/ConquestGame.h Game/ConquestGame.cc

\subsubsection{Constructor (required)}

This should call the base class Game constructor with a string containing the
name of the game and the number of sides that participate in the game. It
should then create the board for this particular game type.

\subsubsection{DPlay() (required)}

This function actually controls the gameplay from start to end. First it must
load (board->Load()) in the default set of pieces onto the board and send the 
complete board (SendDetails()) to all the players.

It should then go into a loop that is broken only when the game has finished.
During each loop the following actions must be taken:-

\begin{itemize}

	\item Give control to team making the next move (team->ControlToPlayer())
	\item Check for a result (HandleResult())
	\item Select the next team to make a move

\end{itemize}

\subsubsection{HandleResult() (optional)}

This function checks for the end of the game and handles the actions that need
to be taken given a particular result. If the game is undecided it should
return the value TRUE otherwise it should at least send appropriate messages
to all the teams and then return FALSE.

This function by default assumes that the game is played by two teams and that
there are all 3 outcomes (win,lose,resign). If the game does not fit this
profile then this virtual function can be replaced in the derived class.

\subsection{Board Class (required)}

The game board should be derived from the board class this can be via an
intermediate class e.g. for chess and draughts first derive a check board
class which creates a board of black and white squares then derive the
draughts and chess board classes from that.

Example files Boards/ConquestBoard.h Boards/ConquestBoard.cc

\subsubsection{Constructor (required)}

This has two jobs, the first is to call the base class constructor with the
board type and size, the second is to actually allocate the squares. The base
class constructor sets up a 2D array of pointers to Square class objects, the
derived constructor should allocate an appropriate Square class object for
each of them (e.g. BlackSquare and WhiteSquare).

\subsubsection{Destructor (required)}

This has to free up any Squares allocated in the constructor and also any
other items that the class has allocated.

\subsubsection{DLoad() (required)}

This function reads the positions of all the pieces from a file and creates
those pieces on the current board. The file can be formatted as required
although it is suggested that the same type of format seen for the Conquest
game is used. This consists of a header line giving the board type followed 
by a series of lines each describing a single piece, the following information
is given, piece type, x position, y position, which side piece belongs to, and
finally any piece specific information.

\begin{verbatim}

      ConquestBoard
      die 1 1 1 5 3 6
      die 2 1 1 1 3 5
      die 3 1 1 2 3 1
      die 4 1 1 6 3 2
      key 5 1 1

\end{verbatim}

The only requirement for the function is that it returns TRUE if it succeeds
and that if it fails it leaves an empty board (board.ClearBoard() is provided)
and then returns FALSE.

\subsubsection{DSave() (required)}

This function must be able to save the positions of all the pieces on the
board to a file. The only requirement is that it saves in the same format as
DLoad() loads ! This function is currently not used so be be replaced with a
dummy function.


\subsection{Square Class (required)}

This is a vey simple class and it is most likely that the appropriate derived
class already exists.

Example files Squares/WhiteSquare.h Squares/WhiteSquare.cc

\subsubsection{Constructor (required)}

All that is required here is to call the base class constructor with an
appropriate type name for the square e.g. WhiteSquare.

\subsubsection{DDraw() (optional)}

This virtual function can optionally be overidden in the derived class. This
should only be done if some extra information is required to draw the
square by the client.

The replacement function must do the following things :-

\begin{itemize}

	\item 	Compose a message containing the type of square, its position on
		the board and any other important information.

	\item	Send the message to all players in the game (use game->MsgToAll())

	\item	If the square is occupied send a message to the piece
		occupying it to draw itself (piece->Draw())

\end{itemize}

\subsection{Piece Class (required)}

When deriving from the Piece class it is highly likely that there will be a
number of intermediate classes. This is because many of the pieces in the game
have a similar behaviour to each other e.g. in Conquest both the Key and
normal piece are Dice so the derivation is therefore Piece -> ConquestPiece ->
DiePiece and KeyPiece.

Example files Pieces/DiePiece.h Pieces/ConquestPiece.h Pieces/DiePiece.cc
Pieces/ConquestPiece.cc

\subsubsection{Constructor (required)}

The constructor must call the base class constructor with the name of the piece
that is being created and must also create an instance of the Rules class that
applies to this type of piece.

The constructor may also need to intialise some information about the way the
piece is positioned but this is game dependent.

\subsubsection{SetNewLocation() (required)}

This function is responsible for actually moving the piece after the move has
been accepted. It has to remove the piece from the current square
(square->Clear()) and place it on its destination(s). Finally it needs to set
the new position for that piece if required e.g. for a dice it needs to change
which faces are showing.

\subsubsection{DDraw() (optional)}

This virtual function can be overidden in the derived class if required. This
should only be necessary if the piece has some special properties that need to
be described to draw the piece.

The replacement function must do the following things :-

\begin{itemize}

	\item 	Compose a message containing the type of piece, its owner and 
		any other important information.

	\item	Send the message to all players in the game (use game->MsgToAll())

\end{itemize}

\subsection{Rules Class (required)}

This is where most of the time involved in developing a new game is spent.
The rules idea is still under development so there may be slight changes in
the way things can be done in the futures but the public interface should
remain almost unchanged.

All derivations here are made from the PieceRules class which is itself
derived from the Rules class (in the future the board and square may be able
to have rules). Each 'rule' is actually a single boolean function which given
a move then decides TRUE or FALSE if the move is valid. The Rules class is a
collections of the rule functions which are gradually made more specific in
each derived class e.g. in PieceRules there is a FreePath() function which
checks if all the square in between two points are clear. In ConquestRules
this is used in FreeDiePath() to check if the all the squares covered in the
move of a die are free.

If a rule decides a move is invalid then it should send the error message
containing the reason for failure to the player making the move.

Examples files Rules/PieceRules.h Rules/PieceRules.cc Rules/ConquestRules.h
Rules/ConquestRules.cc Rules/DieRules.h Rules/DieRules.cc
 
\subsubsection{Constructor (required)}

This just has to call the PieceRules constructor and do any necessary local
initialisations.

\subsubsection{DValidMove() (required)}

This function checks if a move is valid it is basically a series of calls to
the rule functions that cover all the rules for the game. If any of them fail
then the move is not valid and FALSE should be returned otherwise if there are
no problems then TRUE is returned.

There may also be simple checks for things such as there being the correct
number of sections in the move in this function.

\subsubsection{DCaptures() (required)}

This should create a list (captures of PieceRules is a doubly linked list
using libg++) containing pointers to all the pieces that are captured as a
result of this move. It should return TRUE if pieces are captured or FALSE if
no pieces are captured.

\subsubsection{DResults() (required)}

This function examines the move to see if that move has determined the games
outcome. It then returns one of the values found in Game/Game.h that describe
the particular result found.

\subsubsection{DGetNewLocation() (required)}

This returns an integer which indicates which of the squares of the Moves
array refers to the final location of the piece. A valid result here is in the
range 0 to nmoves-1.

\subsubsection{Other Rules Class Functions}

Other functions that are likely to be needed by the Rules class derived
include functions that alter the pieces position such as Roll in the ConquestRules
class.

\subsection{Team Class (optional)}

There is only one reason for deriving from the Team class and that is so that
a new method of moving between active players can be introduced. This is done
by replacing the virtual function NextPlayer() in the derived class.

Example files Play/Team.h Play/Team.cc

\subsubsection{NextPlayer() (optional)}

To chose a new way of moving through the players simply navigate around the
players doubly linked list in a different way (DLList from libg++). A pointer
to the player that is currently active should be placed in the current\_player
member or NULL if there is no active player available.

\subsection{Player Class (optional)}

Again there is only one thing to change on the Player class, this can be
achieved by deriving a new class and replacing the virtual PlayerEvents()
function. This will allow the protocol to be changed slightly to suit a
particular game. Care should be taken when doing this as it may cause the
clients to stop working.

NOTE: This is not yet available, there is still work in progress on the Player
class.

Example files Play/Player.h Play/Player.cc

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{User Documentation for Conquest Server}

\subsection{Introduction}

This is a simple implementation of a conquest server using the Board Game 
classes, it is primarily an example program to demonstrate how easy it is
to construct a game server using the classes. As such it has relatively few
features.

\subsection{Operation}

The server handles a single game with multiple remote players and teams. Once a
player connects to the server (port 8765) they are assigned to a particular team 
and then told to wait until the rest of the players have joined in.

As soon as all the players are ready the server sends a copy of the board to
each of them and informs the first player to make a move. The players on each
team take it in turns to make the move for that team.

After the game has been finished the players are all disconnected and the
server becomes ready to begin a new game. To shutdown the server the program
must be aborted with a CTRL-C, this will cause the server to exit after the
current game has finished.

\subsection{Starting the Server}

The server program has a number of command line options to control various
aspects of its operations.

\begin{description}

	\item[{\bf -p}] Sets the total number of players that participate in the 
			games. This defaults to 2.

	\item[{\bf -h}]	Prints a short help message then exits

	\item[{\bf -d}]	Turns on the debugging mode of the server which will 
			create a file called debug.log in the current directory. 
			This contains a trace of functions called and other useful 
			information.
 
\end{description}

If for some reason there is a problem an appropriate error message will be
printed and the program will exit.

\subsection{Bugs}

There are no known bugs, however the behaviour during the CTRL-C abort may
vary accross systems dues to differences in signal handling especially with
the network functions.

If a bug is found please send full details to nagd@doc.ic.ac.uk together with
the debug.log file.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{User Documentation for Curses Client}

\subsection{Introduction}

This is a simple client for the board game server to provide an interface on
a text based terminal using curses. The client is actually game independent so
that users will not have to keep lots of different programs for playing each
different game.

\subsection{Operation}

When the client is started it attempts to make a connection to the server on
port 8765. Once the connection has been established the client waits until the
other players have joined the game, at this point it reads the various details
about the game from the server and draws the board. If the terminal is too
small the client will abort otherwise the game will start.

When it is time to move the user will be asked to select a command, this is
done by typing the first letter of that command, after which the client may
prompt for further information from the user. All status messages are
displayed on the status line.

After the game has finished the client will display the result for a few
seconds before quitting and resetting the terminal.

\subsection{Starting Up}

The command line options for the curses client are relatively simple. If
started without any options the client will attempt to start up and connect to
the local machine, to connect to a different machine the hostname of the
remote server should be given as the first command line argument. This can be
in either form of addressing (i.e. 127.0.0.1 or localhost).

To turn on debugging mode the client should be started with at least 2
arguments - this must include the remote hostname as the first. This will
cause debugging information to be written to a file called debug.log in the
current directory.

\subsection{Playing the Game}

Once the client is ready to player and it is time to make a move the client
will prompt the user with the available options.

\begin{verbatim}

     Enter Command: (M)ove, (Q)uit

\end{verbatim}

To select the option the letter in the brackets should be pressed (case is not
important). 

\subsubsection{Move}

If the move option is selected the client will then go on to prompt.

\begin{verbatim}

      Enter move: 

\end{verbatim}

At which point the user should enter the coordinates of the squares that the
piece will land on as it moves. If the data entered is not valid for some
reason the status line will display that reason and the user will be prompted
for a move again. e.g.

\begin{verbatim}

      Enter move: 1 1 1 6

\end{verbatim}

\subsubsection{Quit}

This sends a message to the server informing it that the user is leaving the 
game, after which the client will exit.

\subsection{Playing Conquest}

When playing conquest the pieces appear as a pair of lines each containing 3
characters.

\begin{verbatim}

      die
      536

\end{verbatim}

The first line indicated that the piece is a normal dice (instead of the key
die), and the second line indicates how the faces of the die are positioned.
The first digit is the top face, the second is the face at the back and the
third is the face on the left of the die.

\subsection{Bugs}

There are currently no known bugs, however this program may crash
occassionaly on the amiga due to bugs in the console device. Another problem
that will be fixed in the near future is that the program requires a very
large terminal (at least 80x50).

If a bug is found please send full details to nagd@doc.ic.ac.uk together with
the debug.log file.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Testing}

\subsection{Test Strategy}

The nature of the program and the design structure make it very difficult to
test this program in the traditional way by writing each section and then
testing it in isolation. 
The various parts of the program are all very interdependant and can often not
be tested without each other. In this case the stragey must be to test the
smallest possible set that will work together.

This combined with specific debug code, runtime debuggers and external
betatesting should catch must bugs.

\subsection{Test Programs}

A very simple test program was created for each class simple to check out the
constructors and destructors for that class, any other class code used in
these two functions was commented out so the test was not fully comprehensive
as far as allocation and deallocation is concerned.

Only one class could actually be tested independently of the others, the Board
class test program basically checked that the board was correctly allocated
and that the various member functions behaved as expected even with error
conditions. This program was then expanded to include test for the Square
class as that was added in.

As the piece class was developed that the test program was again expanded so
that a simple display of the board was shown. This proved useful as the Rules
were added to the Piece class since it enabled any bad moves and positions to
be quickly spotted.

The test program at this stage had a dummy frontend on it that allowed moves
to be made for all the players via the terminal. This ability was retained
once the Team and Player classed were added in. At this point the server was
complete except for the networking code so this was the version used to check
the gameplay and for betatesting. This ensured that there was no confusion
about the location of the bugs i.e. in the protocol\/network section or the
actual game itself.

The network classes were tested independently as dummy client\/servers for
existing network protocols such as daytime and NNTP. Then finally the network
code was added to the rest and a simple server program was created for final
testing.

\subsection{Debug Code}

Every function written has a piece of conditional compilation code built into
it that writes a line to a debug logfile everytime that function is called.
This line contains the name of the function, and the arguments it was called
with. In addition a small program was written to analyse this logfile checking
for things like a destructor is called for every constructor.

This code proved to be extremely useful in tracking down where errors occured
doing a similar job to a runtime debugger - but faster. Once the approximate
location of the error had been tracked down using the logfile then the
debugger can be used to examine the code in more detail.

Other debug code included special display functions and the printing of key
variables.

\subsection{BetaTesting}

This basically involves playing the game and noting down in problems that
occur and the way in which they were brought about. Most of the errors in the
rules and the network protocol were found in this way.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\end{document}