\documentstyle[epsf]{report}
% $Source: /mit/6.170/groups/se01/.cvsroot/design/design.tex,v $
\textwidth 6.5 in
\oddsidemargin 0 in
\catcode`\| 13
\def\ttuntil#1|{\nonfrenchspacing
\tt
#1\endgroup}

\def|{\protect \begingroup\catcode`\_11\relax
\ttuntil}

\title{Antichess:Oral Report}
\author{
Jered Floyd\\
David Golombek\\
Sam Hartman\\
Ronnie Misra
}
\begin{document}
\maketitle
\tableofcontents

\chapter{Design Overview}

\section{Design Goals}

	The overall design goal of this project was to design a flexible model for implementing board  games with a web server interface.  In drafting the design, the following were considered desirable characteristics:
\begin{enumerate}

	\item  Avoid dependence on any particular game whenever possible.  For example, there is no reason for a machine player to even be aware of the game it is playing unless special optimizations are required.

	\item Maximize flexibility by minimizing the ammount of code that needs to be changed in order to implement changes in game rules.

	\item  Use portable code  so that the server compiles on as many platforms as is feisible.

	\item Conform to Internet standards and to good protocol design, providing alternatives to specified protocols when these specifications do not fully meet these goals.

\end{enumerate}




\section{Top-level Task Overview}
	
Tasks completed by the project:
\begin{itemize}

	\item  Work as a web server

	\item  Present anti-chess games to user and accept moves

	\item  Validate moves and change state of board

	\item  Determine and make best response for machine player

	\item  Present changes in board state

	\item  Handle timing 

	\item  Interpret tournament protocol as well as presenting something useful to humans

	\item  Present help and documentation

	\item  Handle meta-game information: player names, concurrent games, game initiation and termination

	\item  Deal with games between two humans, managing to the extent possible under {\sc HTTP} notifications of moves, detaching and attaching, etc
\end{itemize}

\label{s:tasks}

\section{Abstraction Layers}
\begin{figure}[p]
\leavevmode
\begin{center}
\leavevmode
\epsfbox{mdd.ps}

\caption{Modular dependencies}

\end{center}
\end{figure}
	The following abstractions are proposed to complete the tasks presented in Section~\ref{s:tasks}.

\begin{description}

	\item[|top\_node|] Abstraction, mostly provided from supplied code to represent the information associated with a server

	\item[|game|] Abstraction to represent a game that is being played: Includes meta information, move history, etc.  The game also manages interactions between other components, sequencing application of moves and notification of state change.  In addition, web requests are redirected by game to sub-components.

	\item[|board|]  Abstraction to represent the particular state of a game, including board position and timing information.  The game abstraction will have at least one |board| representing the current move.

	\item[|chess\_display\_board|] Abstraction of board to those games that use a $8\times 8$ board as their playing field.  The starting state will always be read in from a given stream.  

	\item[|player|]  A generic player abstraction used to insulate the |game| and |board| abstractions from the difference between human and machine players.  

	\item[|machine\_player|] Abstraction to represent machine players.

\end{description}


\section{Division of labor}
	Preliminary design details were worked out by the group.  Sam
wrote the first draft of the specifications, and these were revised by the group through a process of evaluating how the design worked under expected game conditions.

	David implemented |chess_display_board| and |antichess_board|,
writing the static evaluator and move generator.  In addition, he
worked on |player| and |human_player|.

	Jered wrote all the methods for doing web output from |board|,
|game| and~|player| objects and subtypes.  In addition, he wrote the
machine player and |tic_board|, a implementation of tic tac toe used to test the basic design while |antichess_board| was incomplete.

	Sam wrote the methods to deal with the incoming web requests as well as designing the enhanced protocol used in addition to the protocol specified in the problem set.

	Ronnie wrote the {\sc HTML} used for the help and welcome pages.  In addition, he implemented several methods in |top_node| and several web enhancements.


\section{Schedule}
	
	Our schedule was based upon the given due dates, then expanded
to cover all of the abstractions we created.

\begin{itemize}

	\item November 14 Preliminary Design.  Create preliminary
draft of this document.
	
	\item November 21 Revised Design.  Finish this design
document, flesh out all abstractions and implement code for lowest
levels of abstraction.

	\item November 30 Oral Presentation.  By this time, design
should be stable, and a large portion of the code should have been
roughed out, but not completely tested.

	\item December 05 Functionality Freeze.  This should be date
for last check-in of added functionality code changes, to give us a
chance to begin final testing. 

	\item December 11 Final Report.  All but exreme bug changes
should be completed and finalized.  

	\item December 12 Demonstration.  All code better be done by
this point.

	\item Dececmber 14 Tournament.  And even more finished by this point.

\end{itemize}

\section{User Interface}

		After a user initially connects to the server, the server will accept at least the following options:
\begin{itemize}
	\item  Begin a game

	\item Help on Antichess

\item Load new games

\item  Show incomplete games

\end{itemize}


	Users who begin a game will be asked to fill out appropriate
meta-information such as user name, and machine player
characteristics, then the game will enter the movement phase.  A page
will be presented containing an Antichess board.  Above the board, a
list will contain the last few moves and any additional status
messages.  Below this will be an $8\times 8$ Antichess board; this
will either be presented using tables, or a series of images on a
line, depending on the apparent capabilities of the browser and what
ends up looking good.  

	Below the board will be a form entry where the user can enter
a textual move and click submit.  It is expected that this interface
will rarely be used outside of testing.

	Each image on the board will be a link.  If the image is
selected, the board will enter select state.  The board in selected
state looks much as the normal board, except:
\begin{itemize}

	\item  The piece that is selected  will be replaced with a image showing it as highlighted.

	\item  The source section of the movement entry form will be filled in with the square of the piece that is selected.
\end{itemize}


	If another square is selected while the board is in select state, the user is assumed to have attempted a move from the source square to the destination square.    

	If a move is entered either by entering one in the movement area, or by selecting a destination from select state, the move is processed and the board is updated.

	Additional options may be provided below the board for things
like help, viewing previous game positions, getting hints, configuring
the game, etc.
\chapter{Design and Implementation comments}
\section{Design of game}
\label{d:game}
	This abstraction implements the concept of a game, with a
state represented by a board.  This abstraction makes few assumptions
about the game that the board ``plays''.  It also keeps a move history
and maintains state about each player.

Task List:
\begin{itemize}

	\item  Keep track of the current player and board

	\item Keep track of previous moves

	\item  Apply moves to the board

	\item  Ask players to make new moves

	\item  Dispatch web requests to players and boards

	\item  Inform players when another player makes a move

	\item  Handle compatability web protocol

\end{itemize}


	Unfortunately, some fairly complicated dependencies exist
between |game|, |board| and |player| to allow for the various
strategies for entering moves.  four mechanisms exist for entering moves, and |game| must deal with all of these:
\begin{enumerate}
	\item When a game is initialized, if a machine player is
first, it will need to move.  Generalizing this solution, it is
important that players used with |game| support a method to ask them
to consider moving whenever the game state changes significantly.
Such changes include initialization, or extra-game editing of the
board.

	\item  In order to allow a machine player to think and return a move, |game| must call each player giving that player an opportunity to return a move.  For human players, this will never result in a move being generated, as the move will be returned by a web request, instead of from a call to a method of |player|.

	\item An incoming request in either the 6.170 mandentory
protocol, or in our extended protocol may indicate the current player
has moved.  This request will be dispatched to the appropriate
instanciation of |player| or |board|.  

	\item A request, directed at the board, may select a
destination square for a move.  This may cause the board to generate a
move for the current player.

\end{enumerate}
These interactions become important at the design phase  because it is necessary to understand how moves can be generated in order to best  design an interface that minimizes duplication of code and places emphasis on the underlying problem---the problem of reading and acting on a move.  In order to implement a clean interface for dealing with moves, the following approach is taken:
\begin{enumerate}

	\item Whenever the game state changes in response to game
	initialization or any event besides one of the players moving,
	a state change method is called on each player.  If an
	instance of |player| has valid moves it can make when this
	method is called, it is required to take actions that will
	avoid deadlock.  Generally, moving is sufficient, although a
	subtype of |player| could simply arrange to move at some
	future time.  Other options include presenting some web interface to force the player to move.


\item If a web request is dispatched to an
	inferior node such as an instance of |player| or |board|, the
	corresponding response is returned unmodified.  This allows
	for non-movement-related requests such as help, etc.

	\item A request handler that wishes to enter a move will call
a method on |game| to handle all the work of entering the move.  Such
requests will eventually call another method on |game| to obtain an
updated state of the game.  This state will be the complete,
unmodified response of the request.

	\item When an instance of |player| is informed of an
opponent's move, it is legal for the player to make its own move by
calling the appropriate method on |game|.

\end{enumerate}



\input{game.h.tex}

\section{Design of board, the interface between game and game state}

	The |board| abstraction is a abstract base class inheriting
from |web_node|.  It is designed to present the interfaces required by
|game| and a reasonable machine player without including any specific
knowledge of a particular game or its rules.  For this reason, moves
are represented as abstract members of class~|move|.  

	Several pure virtual interfaces, required by |game| and
|player| are included.  Any implementation of these interfaces will
require specific knowledge of the particular game being represented by
the board.  

	A decision was made to include the interface to the static
evaluator in |board| and to include implementations in subtypes of
|board|.  It is likely that only machine players will find the static
evaluator useful.  H.wever, by including it in |board|, it is possible
to write a machine player that isn't aware of what game it is playing.
Also, this helps concentrate game-specific code in one
place---subtypes of |board|.  

Tasks required by this abstract interface:
\begin{enumerate}

	\item Accept web requests from |game|

	\item Apply moves as requested by |game|

	\item Provide a generator that returns all legal moves at the current point, along with the static evaluation of the board after applying one of these moves
	\item Provide a static evaluator

	\item Provide a routine to generate the board representation for inclusion in the response to web requests to |game|.


	\item Suggest the ammount of time to be spent on a particular move.
\end{enumerate}


\input{board.h.tex}

\section{ Design of chess\_display\_board}

	This subtype of the |board| interface implements functions
required for an $8\times8$board where a square can hold one chess
piece.  This board is not aware of the rules of the game in that the
moves generator and static evaluator are still pure virtual, but it
can display a chess board, and generate a move by selecting a source
and destination square.  The initial state of a chess\_display\_board 
shall be specified in a given stream, which will meet the specifications 
below:

\input{chess_board_format.tex}

\input{chess_display_board.h.tex}

\section{Design of antichess\_board}


This subtype of |chess_display_board| implements the rules of Antichess.    In particular, all methods specified in |board| are implemented in such a way that it is possible for this board to be used with |game|.

\input{antichess_board_format.tex}

\input{antichess_board.h.tex}


\section {Design of {\tt player}}

This is a subtype of |web_node|.  The |player| class embodies an abstract entity capable of making moves in a game.  It accomplishes the following:

\begin{enumerate}

	\item Keeps track of time elapsed and remaining and forfeits when time runs out

	\item  Has interface so |game| can notify it about moves made both by itself and by the opponent and of state changes not resulting from moves
	
	\item  Keeps track of player name and if set, position

	\item  Provides a method so that boards in games like Antichess can set the position of the player to ``white'' or ``black''.

	\item  Provides a method so that |game| can get a representation of the player state to include in a web response.  This state should include name, position (if set), and time remaining at a minimum.  

	\item  Accepts web requests including at a minimum requests to change the player name and time remaining.
\end{enumerate}




\input {player.h.tex}

		There are two subclassess of |player| essential to the operation   of the server: |machine_player| and |human_player|.

\subsection{machine\_player}

	The machine player abstraction implements a computer player.
It uses one of two algorithms to choose a move.  If possible, it uses
a min-max search with alpha-beta prooning.  Otherwise, it simply
choosesthe best move at the current level.  It is expected that the
alpha-beta algorithm will not fail, but in case it does, the simple
algorithm is included.

\input{machine_player.h.tex}

\subsection{human\_player}

	The human player object implements functionality necessary for
human--human games and to allow humans to change parameters about
their players.  In particular, it has the ability to forefit and
change time remaining.  Clock management is handled to work properly
for someone connected over the web.

\input{human_player.h.tex}


	\section{Design of {\tt move}}

	The |move| class implements the concept of an abstract move.
Required by |board| and |player|.  Moves can be compared for equality,
and can return a string representation of themselves.  All other operations are reserved to subclasses of |move|.

	Because |move| is expected to be small, and because many
instances of |move| are expected to exist, |move| must be able to be a
stack abstraction.  Note that several constructors and operators on
|move| are protected, so that |move| objects are not chopped by
inadvertant copying.


	For this reason, |move| requires a special |move_generator|
that returns pointers to |move| instead of actual move objects.

	However, in order for |game| to maintain a move history, it
must be able to copy a |move| without knowing what type of move it is.
Thus, |move| must also be capable of being a heap abstraction.  It is
invisioned that |board::valid_moves| will produce a large number of
moves of a particular type in a compact form, and will return pointers
to these one-at-a-time.  Only moves that are actually used will be
copied by |game|.

\input{move.h.tex}

\section{Implementation Overview}

	The implementation of the program was split into three
components: modified versions of web server code supplied with the
problem set, basic components such as players and |game|, and
antichess specific components.

	
	For the most part, the design allowed components to be
implemented without any unnecessary dependencies or unusual features.
However, the required {\sc HTTP} protocol was designed for a less
modular design.  In order to implement it, some unnecessary
dependencies had to be introduced into |game|.

	Because of design errors in the required protocol, it was felt
acceptable to introduce these dependencies and provide a better
default protocol than to redesign around the broken protocol.

	
	

\input{http_proto.tex}

\chapter{Validation Strategy}

Several methods were used to verify test the implementation and design:

\begin{enumerate}

	\item A small test framework was used to test the interactions
between |game|, |board| and~|player|.  This framework tested the
simple machine player, playing in a simplified game.  The framework
confirmed that there were no apparent design flaws, and that the
movement structure would allow moves to be made without deadlocks.

	\item Along with the test framework, a simple board was
constructed: a board to play tic tac toe was implemented in parallel
with |antichess_board|.Having multiple implementations of
|board|provided additional confirmationthat |board| was a reasonable design.

	\item In |antichess_board|, a different algorithm is used to
confirm the validity of moves than is used to generate the valid
moves.  These multiple implementations tend to illustrate bugsin each other.

	\item The web protocol was tested by constructing a subset of
valid requests that were likely to happen.  In particular, each
request in Chapter~\ref{s:http} was tested with reasonable arguments.  Error conditions were also tested.

	\item Once the load game feature was implemented, several test
case boardswere loaded and responses of the move generator was
tested.



	\item A clear method of notifying all developers of changes in
design specification.


	\item All compilations will be done with -Wall to help catch
casting and coding errors.

	\item Where possible, methods and procedures will have a
checks clause that ensures input meets requirements from this design
document. 

%	\item Automated testing will be performed when it becomes
%viable to do so, by creating a harness for the web server and throwing
%requests at it.

	\item Outside testers, untainted by source, shall test working
code to find bugs not seen by programmers.
	
\end{enumerate}

\chapter{Description of Progress}


	Currently, almost all specifications have been implemented.
Testing, including play testing from outsiders proceeds well; many
bugs have been found, and it is unlikely that any serious bugs remain.
The following lists known deficiencies that may correct themselves by
the time of the demonstration:

\begin{enumerate}

	\item The |nnnn/display|request does not always work;
sometimes it is not found.  This creates somewhat of a problem for human players; you just have to ``know'' the other player has moved.

	\item  The `Can I move yet?'' button ` doesn't work very predictably.
\end{enumerate}



\end{document}

