\documentclass{article}
%%toolkit zrm
\usepackage{zeta}
\usepackage{epic}
\usepackage{eepic}
\usepackage{url}
\usepackage[numbers]{natbib}

% the tables are wide
\topmargin=0pt
\oddsidemargin=-0.25in
\evensidemargin=-0.25in
\textwidth=6.5in
\textheight=8.5in

% table of requests
\newenvironment{reqtab}[2]{%
\begin{table}%
\centering
\caption{#2}%
\label{table-#1}%
\begin{tabular}{rll}%
\multicolumn{1}{c}{\bf name}&%
\multicolumn{1}{c}{\bf request}&%
\multicolumn{1}{c}{\bf meaning}\\\hline
}{\end{tabular}%
\end{table}}

% table of responses
\newenvironment{resptab}[2]{
\begin{table}%
\centering
\caption{#2}%
\label{table-#1}%
\begin{tabular}{rll}%
\multicolumn{1}{c}{\bf name}&%
\multicolumn{1}{c}{\bf response}&%
\multicolumn{1}{c}{\bf meaning}\\\hline
}{\end{tabular}%
\end{table}}
% tokens
\newcommand{\stok}[1]{{$\langle${\em #1}$\rangle$}}
\newcommand{\bfid}[1]{{\bf #1}}
\newcommand{\itid}[1]{{\it #1}}

\title{A Networked Awari Referee: Specification}
\author{Bart Massey}

\begin{document}
\maketitle

The many variants of the African game Awari are among the
oldest known games of intellectual skill.  In this document,
we will describe a networked server to which human and
computer players can connect to play the game in a refereed
fashion.

\section{The Game Of Awari}

The rules of awari are complicated and have many variants.
This discussion is based on the excellent summary of
Schaeffer~et~al.~\cite{awari-rules}.

Awari is a two player game, played by players conventionally
designated as $north$ and $south$.
\begin{zed}
PLAYER ::= north | south
\end{zed}
\begin{axdef}
  opponent : PLAYER \bij PLAYER
\where
  opponent~north = south \\
  opponent~south = north
\end{axdef}

The board,
shown in figure \ref{fig-board}, consists of 12
{\em pits} into which a number of {\em stones} are placed.  In
addition, two end pits, or {\em awari}, contain stones
captured by the two sides during play.
Starting from the NE corner and
moving counterclockwise,
the pits are named by the letters
$a$ through $f$, first in lowercase and then in uppercase.
This convention is
sensible, since the fundamental sowing operation
described below moves counterclockwise.
\begin{zed}
  PIT ::= a | b | c | d | e | f |
  A | B | C | D | E | F
\end{zed}
\begin{axdef}
  pit\_order : \seq PIT \\
  next : PIT \bij PIT \\
  prev : PIT \bij PIT
\where
  pit\_order = \langle a, b, c, d, e, f, A, B, C, D, E, F \rangle
\also
  \forall p : PIT @
      next~p = pit\_order(((pit\_order\inv)~p) \mod 12 + 1)
\also
  prev = next\inv
\end{axdef}

\begin{figure}
\begin{center}
\input{awari-board.eepic}
\end{center}
\caption{Awari Board In Initial Configuration}
\label{fig-board}
\end{figure}


The board starts with 48
stones, and stones are never lost from the game: all 48 must
always be somewhere.  It is thus useful to talk about the
the total contents of a set of pits: more generically,
about the total sum over the range of some relation.
\begin{gendef}[X]
  \Sigma :  (X \rel \nat) \fun \nat
\where
  \Sigma \emptyset = 0
\also
  \forall r : X \rel \nat; x : X; n : \nat |
  (x \mapsto n) \in r  @ \\
  \t1 \Sigma r = n + \Sigma (r \setminus \{x \mapsto n\})
\end{gendef}

The state of the board at any given time is essentially just
the number of stones in each pit.  The players alternate
moves.
\begin{zed}
  BOARD == PIT \fun \nat \\
  SCORE == PLAYER \fun \nat
\end{zed}
\begin{schema}{AwariBoard}
  board : BOARD \\
  score : SCORE \\
  to\_move : PLAYER
\where
  \Sigma board + \Sigma score = 48
\end{schema}

Each pit initially contains 4 stones,
as shown in figure \ref{fig-board}.
The $south$ player moves first.
\begin{schema}{InitAwariBoard}
  AwariBoard '
\where
  board' = PIT \cross \{4\}
\also
  score' = PLAYER \cross \{0\}
\also
  to\_move' = south
\end{schema}

The players alternate in {\em sowing} the stones in a pit of
their choice on their side of the board.  ($north$ owns
pits $a$--$f$, and $south$ pits $A$--$F$.)
\begin{axdef}
  side : PLAYER \bij \power PIT
\where
  side~north = \ran ((1 \upto 6) \dres pit\_order) \\
  side~south = PIT \setminus (side~north)
\end{axdef}

A pit may be sown if it contains one or more stones: the
stones are removed from the pit, and placed one at a time
into subsequent pits, moving around the board in
counterclockwise order.
The original pit is skipped
whenever it is encountered.
\begin{axdef}
  next\_skip : PIT \fun PIT \fun PIT
\where
  \forall p : PIT @
     next\_skip~p =
     next \oplus \{ prev~p \mapsto next~p \}
\end{axdef}
Thus, the sequence of pits
to be sown is a prefix of the
infinite cyclic
sequence of pits which repeats
every 11 elements after skipping the sown pit.
We call this infinite sequence the $trace$ of
the sown pit.
\begin{axdef}
  trace : PIT \fun \seq PIT \\
\where
  \forall p : PIT @
      trace~p = (\lambda n : \nat_1 @ (iter~n~(next\_skip~p))~p)
\end{axdef}

Thus we can sow the stones by emptying
the pit to be sown and adding a stone
to each other pit for each time it is
hit by sowing.  The last
pit filled is the first pit we will
examine for possible capture below.
\begin{schema}{Sow}
  \Delta AwariBoard \\
  move : PIT \\
  to\_capture : PIT \\
\where
  \forall p : PLAYER @
      score~p < 25
\also
  move \in side~to\_move
\also
  board~move > 0
\also
  to\_capture = (trace~move)(board~move)
\also
  board' = \\
  \t1 \LET emptied == board \oplus \{move \mapsto 0\}; \\
  \t1 sown == (1 \upto (board~move)) \dres (trace~move) @ \\
  \t2 (\lambda p : PIT @ (emptied~p) + \#(sown \rres \{p\}))
\also
  score' = score
\also
  to\_move' = to\_move
\end{schema}

When sowing a pit, if the last pebble placed makes a group
of two or three, then that pit's stones are {\em captured} and
scored by placing in the capturing player's awari.
If the previous pit then contains a group of two or three
stones, these
stones are also captured, and so forth.
Thus, the set of pits which are captured is the
set of pits on the opponent's
side of the board reachable by captures from the last
pit sown:
This set is given by
by the range of the transitive closure of the
next relation restricted to the capturable elements.
\begin{gendef}[X]
  reachable : (X \rel X) \fun \power X \fun \power X
\where
  \forall r : X \rel X; xs : \power X @ \\
  \t1 reachable~r~xs = \ran (xs \dres (r\star))
\end{gendef}
\begin{schema}{Capture}
  \Delta AwariBoard \\
  to\_capture : PIT \\
  captures : \power PIT
\where
  captures = \\
  \t1 \LET vul == \dom (board \rres \{2, 3\}) \cap
      side(opponent~to\_move) @  \\
  \t2 reachable~(vul \dres prev \rres vul)~\{to\_capture\}
\also
  board' = board \oplus (captures \cross \{0\})
\also
  score'~to\_move = score~to\_move + \Sigma(captures \dres board)
\also
  score'(opponent~to\_move) =  score(opponent~to\_move)
\also
  to\_move' = to\_move
\end{schema}

The sowing of stones to capture all stones
on the opponent's side of the board is known as a {\em grand
slam}, clean sweep, or grand coup.  Normally, a
grand slam ends the game, capturing all stones remaining on
the board.
The rules
governing the grand slam vary widely, however:
Schaeffer~{\em et.~al.}~\cite{awari-rules} lists
a number of variations:
{\renewcommand{\theenumi}{\alph{enumi}}%
 \renewcommand{\labelenumi}{\theenumi)}%
\begin{enumerate}
  \item \label{case-computer-olympiad} Stones may not be sown for
        a grand slam (unless no other move is possible).
  \item The stones may be sown for a grand slam, but
        no capture results.
  \item The stones may be sown for a grand slam, but
        the last pit is not captured.
  \item The stones may be sown for a grand slam, but
        only the first pit is captured.
  \item \label{case-mind-sports} The stones may be sown for a grand slam, and
        all captures happen: the remaining stones on
        the board are awarded to the opponent.
\end{enumerate}}
This paper will consider only
variant (\ref{case-mind-sports}), which will be
used in the 
August 2000 Mind Sports Olympiad~\cite{mso}
computer competition.
The 1990--1992 Computer
Olympiads~\cite{computer-olympiad}
used variation (\ref{case-computer-olympiad}).
Many human players prefer the simpler version.

There are a number of possible outcomes of a (attempt to)
move.
\begin{zed}
  RESULT ::= win \ldata PLAYER \rdata | draw | not\_done | illegal\_move
\end{zed}
\begin{axdef}
  winner : SCORE \fun RESULT
\where
  \forall s : SCORE @ winner~s = \\
  \t1 \IF s~north > s~south \\
  \t2 \THEN win~north \\
  \t1 \ELSE \IF s~south > s~north \\
  \t2 \THEN win~south \\
  \t1 \ELSE draw
\end{axdef}

A game may be ended by a player being
unable to move, in which case the remaining stones on the
board belong to the opponent.
\begin{schema}{ClaimStones}
  score, score' : SCORE \\
  board : BOARD
\where
  \forall p : PLAYER @
      score'~p = score~p + \Sigma (side~p \dres board)
\end{schema}
However,
a player must leave the opponent with a legal move
at the start of their turn, if it is possible to do so.

A game will also be ended by repetition of position.
(This is generally only true of computer play.  In human
play, it is more common to end by agreement of both sides.)
The most common rule here is that each player captures the
stones on their side of the board.  One popular
variant, used in the 1990--1992 Computer Olympiad,
is to not count the stones left on the board at the end.
To keep track of repetitions, it is necessary to keep
track of the set of positions seen so far.
\begin{schema}{Positions}
  positions : \power AwariBoard
\end{schema}

To summarize the variant of interest here: a move
in the game consists of
altering the board and recording the resulting board
position.  Moves alternate between players.
\begin{schema}{AwariMove}
  \Delta AwariBoard \\
  \Delta Positions \\
  opp\_stones : BOARD \fun \nat \\
  result : RESULT
\where
  positions' = positions \cup \{\theta AwariBoard\}
\also 
  \forall b : BOARD @
  opp\_stones~b = \Sigma ((side(opponent~to\_move)) \dres b)
\end{schema}

If either player has 25 or more stones at the start
of their turn, the player
with the most stones wins,
and the game is over.
\begin{schema}{WinMargin}
  AwariMove
\where
  \exists p : PLAYER @ score~p \ge 25
\also
  score' = score
\also
  result = winner~score'
\end{schema}

If the sowing is impossible,
or the position is a repetition of a previous one,
each player claims the stones on their
side of the board, and the game is over.
\begin{schema}{NoMove}
  AwariMove \\
  ClaimStones
\where
  \forall p : PLAYER @
      score~p < 25
\also
  \theta AwariBoard \in positions \lor \\
  \Sigma (side~to\_move \dres board) = 0
\also
  result = winner~score'
\end{schema}
If the opponent's pits are all empty, the
player must sow a pit which leaves the opponent a move if
possible.
\begin{schema}{NormalMove}
  AwariMove \\
  Sow \semi Capture
\where
  \forall b : BOARD @
  opp\_stones~board = 0 \implies opp\_stones~board' > 0
\also
  result = not\_done
\end{schema}

A grand
slam capture forfeits all stones still on the
board at the end of the turn.
\begin{schema}{ForfeitStones}
  score, score' : SCORE \\
  board : BOARD
\where
  \forall p : PLAYER @
      score'~p = score~p + \Sigma (side(opponent~p) \dres board)
\end{schema}
A grand slam is the capture the rest of the opponent's stones.
\begin{schema}{GrandSlam}
  AwariMove \\
  Sow \semi Capture \semi ForfeitStones
\where
  opp\_stones~board > 0
\also
  opp\_stones~board' = 0
\also
  result = winner~score'
\end{schema}

A move can only be illegal if a move is available
and neither side has won.
An illegal move is from a pit on the wrong side of the
board, a pit with no stones, or fails to feed an
opponent with stones when necessary.  (Note that
this schema does not assume $NormalMove$ is deterministic
for a given move, although we know it to be.)
\begin{schema}{IllegalMove}
  AwariMove
\where
  \forall p : PLAYER @ score~p < 25
\also
  \exists p : side~to\_move @ board~p > 0
\also
  \t1 move \notin side~to\_move \lor board~move = 0 \lor \\
  \t1 opp\_stones~board = 0 \land \\
  \t2 (\forall m : NormalMove | m.move = move @ \\
  \t3 opp\_stones~m.board' = 0) \land \\
  \t2 (\exists m : NormalMove | m.move \neq move @ \\
  \t3 opp\_stones~m.board' > 0)
\also
  result = illegal\_move
\end{schema}

The referee reports whether a
move continues the game, ends the game, or is illegal.
\begin{zed}
  AwariRef \defs NormalMove \lor WinMargin \lor \\
  \t1 NoMove \lor GrandSlam \lor IllegalMove
\end{zed}

The game starts with the initial board,
and no positions yet seen.
\begin{schema}{InitAwari}
  InitAwariBoard \\
  Positions '
\where
  positions' = \emptyset
\end{schema}

\section{Server}

The Awari server listens on a port in the
range $29046\ldots29056$ for a
connection.\footnote{All numbers in this section
will be base 10 (decimal) unless otherwise stated.}
All input to the server will be in the form of
ASCII text lines, terminated with a CR character (ASCII code
13).  All server responses will be in the form of ASCII text
lines, terminated with a CR and then an LF character (ASCII
code 10).  Responses will begin with a 3-digit numerical
code, and be followed by whitespace and a (non-standard)
explanatory text message.  Requests and responses not currently
implemented by the server will have their identifier
in italics: those implemented will have boldface identifiers.

Any number of observers may connect to the server, as well
as the two players.
The server will always be in a state determined by the input
it has seen.  This state will determine which messages it
will accept, and which responses it will return.  The server
may be in different states for different connections: it
must synchronize the connections at key points.
\begin{zed}
  STATE ::= initial | seated | playing | done \\
  ENTITY ::= player \ldata PLAYER \rdata | observer \ldata \nat_1 \rdata \\
  observer \in \power(\seq ENTITY)
\end{zed}
\begin{axdef}
  cstate : ENTITY \pfun STATE
\end{axdef}


Upon connection to the server, an entity will
receive a greeting in the form indicated by Table~\ref{table-greeting}.
The version number is a pair of integers separated by a
decimal point.  This document describes version 0.9.

\begin{resptab}{greeting}{Greeting}
\bfid{greeting} & 000 \stok{version-number} &Greeting message
\end{resptab}


The initial message sent to the server must be as
shown in Table~\ref{table-initreq}.
Responses are shown in Table~\ref{table-initresp}.
The \stok{optional-name} is an optional
double-quoted string (with the convention that two
consecutive double-quotes "" inside the string escape to
a single double-quote ") of up to 31 characters used to
identify the entity.  The version number is as above,
and is used to identify the client version.  The client
version must be no greater (under the usual ordering)
than the server version.
If both players indicate ``player ?'', the server will
randomly select a north and south player.

\begin{reqtab}{initreq}{Initial Requests}
\bfid{want\_north} & \stok{version} player north \stok{optional-name}
  & Will play north \\
\bfid{want\_south} & \stok{version} player south \stok{optional-name}
  & Will play south \\
\itid{want\_side} & \stok{version} player ? \stok{optional-name}
  & Will play either \\
\bfid{want\_observe} & \stok{version} observer \stok{optional-name}
  & Will observe
\end{reqtab}

\begin{resptab}{initresp}{Initial Responses}
\bfid{seat\_granted}	& 100	& Request accepted \\
\bfid{seat\_granted\_tc}& 101 \stok{secs}
			      \stok{opp-secs} &
				  Request accepted with time
			          controls \\
			& 19x	& Request not accepted \\
\bfid{seat\_taken}	& 191	& Other player holds requested side \\
\bfid{seat\_full}	& 192	& There are already two players \\
\bfid{seat\_private}	& 193	& Cannot observe \\
\bfid{seat\_illegal}    & 198	& Illegal version number \\
\bfid{seat\_garbled}    & 199	& Request not understood
\end{resptab}

Once both a north player and a south player have
connected, the setup phase will be over.  The server may
indicate to each entity the other entities involved, by
sending messages as shown in
Table~\ref{table-configresp}. \stok{name} and \stok{optional-name} are
double-quoted strings as described below. \stok{number} is a
decimal number. (All entities should be prepared to deal
with numbers up to 3 decimal digits, and to discard an
arbitrary number).

\begin{resptab}{configresp}{Configuration Messages}
\itid{config\_north}	    & 341 \stok{name}	  & North player is \stok{name} \\
\itid{config\_south}	    & 342 \stok{name}	  & South player is \stok{name} \\
\itid{config\_observer}  & 343 \stok{number} \stok{name} & Observer \stok{number} is \stok{name} \\
\itid{config\_nobserver} & 344 \stok{number}	  & There are \stok{number} observers
\end{resptab}

The server will then signal the start of game by sending
a message to each connected entity, as shown
in Table~\ref{table-startresp}.

\begin{resptab}{startresp}{Starting Messages}
\bfid{role\_north}    & 351 & You will play north \\
\bfid{role\_south}    & 352 & You will play south \\
\bfid{role\_observer} & 353 & You will observe
\end{resptab}

After this, the server will accept moves from players
in alternation, of the form shown
in Table~\ref{table-moves},
where the \stok{move number} is a standard decimal number
indicating the ply of the move, the \stok{ellipses-if-north}
will be the string ... for a move by north and the
empty string for a move by south, and \stok{move} will be
a move in the notation described above.

\begin{reqtab}{moves}{Move Syntax}
\bfid{action\_move} & \stok{move number} \stok{ellipses-if-north} \stok{move}
  & Make a move
\end{reqtab}

Instead of a move, the following inputs may
also be 
accepted as shown in Table~\ref{table-altmovereq}.
Responses to actions are shown in Table~\ref{table-altmoveresp}.

\begin{reqtab}{altmovereq}{Alternatives To Moving}
\itid{action\_resign}    & resign & Player resigns \\
\itid{action\_draw\_req} & draw?  & Player offers a draw \\
\itid{action\_draw\_ack} & draw   & Player accepts a draw \\
\itid{action\_draw\_nak} & nodraw & Player refuses a draw
\end{reqtab}

\begin{resptab}{altmoveresp}{Responses To Actions}
                        & 20x & Action accepted \\
\bfid{result\_continue} & 200 & Continue playing \\
\bfid{result\_continue} & 207 \stok{secs} & Continue with time left \\
\bfid{result\_win}      & 201 & You win \\
\bfid{result\_lost}     & 202 & You lose \\
\bfid{result\_drawn}    & 203 & You draw \\
\itid{result\_resigned} & 204 & Resignation accepted \\
\itid{result\_drawreq}  & 205 & Received draw request \\
\itid{result\_drawnak}  & 206 & Received draw refusal \\
                        & 29x & Action not accepted \\
\bfid{result\_illegal}  & 291 & Illegal request \\
\bfid{result\_garbled}  & 299 & Request not understood
\end{resptab}

After each accepted action, a message will
be sent to each connected entity, as
shown in Table~\ref{table-statusmsgs}.
Upon termination of the game, the server will close all
connections.

\begin{resptab}{statusmsgs}{Status Messages}
& 31x			     & Game continues \\
\bfid{status\_moves\_south} & 311 \stok{move-number} \stok{move}     & South move \\
\bfid{status\_moves\_north} & 312 \stok{move-number} ... \stok{move} & North move \\
\bfid{status\_moves\_south\_tc} & 313 \stok{move-number}
                                  \stok{move}
				  \stok{secs}
				& South move and time\\
\bfid{status\_moves\_north\_tc} & 314 \stok{move-number}
			  ... \stok{move}
			  \stok{secs}
			& North move and time \\
& 32x, 36x			     & Game over \\
\bfid{status\_winsmove\_south} & 321 \stok{move-number} \stok{move}     & South wins by move \\
\bfid{status\_losesmove\_south} & 322 \stok{move-number} \stok{move}     & South loses by move \\
\bfid{status\_winsmove\_north} & 323 \stok{move-number} ... \stok{move} & North wins by move \\
\bfid{status\_losesmove\_north} & 324 \stok{move-number} ... \stok{move} & North loses by move \\
\bfid{status\_drawsmove\_south} & 325 \stok{move-number} \stok{move} & Drawn by South move \\
\bfid{status\_drawsmove\_north} & 326 \stok{move-number} ... \stok{move} & Drawn by North move \\
\itid{status\_resigns\_north} & 327			     & South wins by resignation \\
\itid{status\_resigns\_south} & 328			     & North wins by resignation \\
\itid{status\_draw\_agreed} & 329 & Draw accepted \\
\bfid{status\_flagfell\_north} & 361 & South wins by North time expiring \\
\bfid{status\_flagfell\_south} & 362 & North wins by South time expiring \\
$$ & 33x			     & Draw protocol \\
\itid{status\_reqsdraw\_south} & 331			     & Draw requested by South \\
\itid{status\_reqsdraw\_north} & 332			     & Draw requested by North \\
\itid{status\_refsdraw\_south} & 333			     & Draw refused by South \\
\itid{status\_refsdraw\_north} & 334			     & Draw refused by North \\
& 34x		             & (see above) \\
& 35x			     & (see above) \\
& 39x			     & Bad status \\
\itid{status\_disconnect\_south} & 391			     & South disconnected \\
\itid{status\_disconnect\_north} & 392			     & North disconnected \\
\bfid{status\_garble} & 399			     & Unknown problem
\end{resptab}

If the participant is an observer, every status message will
be followed by three state display messages showing the
current state of the game, as in Table~\ref{table-sdispmsgs}.
The times will be in seconds, and the \stok{to-move} value
will be either ``n'', ``s'', or ``*'' indicating North,
South, or the game is over.

\begin{resptab}{sdispmsgs}{State Display Messages}
& 38x			     & state display \\
\bfid{sdisp\_score} & 380 \stok{move}
                                \stok{score-n}
				\stok{score-s}
				\stok{to-move} & state \\
\bfid{sdisp\_score\_tc} & 381 \stok{move}
                                \stok{score-n}
				\stok{score-s}
				\stok{time-n}
				\stok{time-s}
				\stok{to-move} & state and time \\
\bfid{sdisp\_board\_north} & 382 \stok{pit-f} ... \stok{pit-a}
				& North board \\
\bfid{sdisp\_board\_south} & 383 \stok{pit-A} ... \stok{pit-F}
				& South board
\end{resptab}

The draw protocol is as one would expect: a draw may be
offered by a player whose turn it is to move.  If it
is rejected by the other player, it may not be offered
again until the next move.

% Pending Issues:
%+ Multiple games on a single server. (i.e. sub-connection
%protocol)
%+ Partial board positions.  (e.g. for saving game status
%across disconnects.)
%+ 4-player game.
%+ Chat.
%+ Late observers.

\bibliographystyle{plainnat}
\bibliography{awari-server}

\end{document}
