User Documentation
------------------

Installation

The server is developed using Tcl 7.5 and Tk 4.1.  It may be compatible with
the environment using Tcl 7.4 and Tk 4.0, but it will not work with any
earlier version.

To install it, follow the steps below.
- Use tar and gunzip to retrieve all files from the archive file.
- Tailor the Makefile for your environment (you have to change at least INCDIR
  and LIBDIR before compiling)
- Type "make"

Two executables, server and client, should be found in the current directory
if compilation succeeded.

Programming

Currently, the server supports Chinese Checkers only.  You may write a program
that plays with the demo program to see whether you can beat it.  To do this,
you have to provide function with the prototype:

void move_game_piece(char *msg)

Note:	The following is quoted from a document that describes the rules for
	the Computer Chinese Checkers Competition held by The ACM Hong Kong
	Chapter.  The rule used in the server is exactly the same as described
	in the document except that no clock is implemented.  Here I just
	quote the information regarding the message format, which is the most
	important for your code to be compatible with the modules provided.

The argument is the message to be passed to the same server through which it
arrives at your opponent's machine.  The maximum length is 56 characters.
Its format is:

+-------+------+-----------+-----------+-...-+-------+
| # of  | from | intermed. | intermed. | ... | final |
| jumps | pos. | pos. 1    | pos. 2    |     | pos.  |
+-------+------+-----------+-----------+-...-+-------+

The value of each field is represented by a byte.  The first field indicates
the number of jumps of the move.  The second field contains the location of
the marble which is moved.  Zero or more subsequent fields indicate
intermediate positions.  The last field contains the location of the final
destination of the marble.

Since no game board information is passed between the clients and the server,
you have to keep your own copy of the game board.  You can assume that the
moves passed from the server is always valid.

After finishing your coding of move_game_piece(), you can compile your module
with two other modules, com.c and com_cli.c, in the archive.  Then you can
know start the game!

Running the Server

Before running the server, you have to edit a file named serverrc.  Enter
addresses of two machines with one address per line.  Then you are ready for
the game.

One game mode

Invoke the server.  Choose "Open..." in the File pull down menu.  Then you are
asked to enter names of the players and paths of their programs.  Enter
whatever name your like but make sure that the paths are correct.  Press OK
button to confirm and then press the start button to begin.  You will see
another window poping up.  That is the game board of Chinese Checkers.  This
window will be disappeared when the game ends.  Exit the program by choosing
"Exit" in the File pull down menu.

Tournament mode

You can also make the server automatically invoke several game player programs
that are written by different people.  Edit a file to put the players' names,
players' ID, program paths in each line for each player.  The line should be
like

Felix Cheng,12345678,/homes/felix/client

Note that there should be no space on either side of the commas and no empty
line.

After editing the clients database, run the server and press the "Tournament"
button.  Choose "Open..." as before.  A window pops up which allows you to
select a file to be read.  Click on the name of the file that you have just
edited.  Now you will see a table showing all players' names and five more
columns.  Those columns mean

P	- number of games played
W	- number of games won
D	- number of games drawn
L	- number of games lost
Pt	- points obtained so far

The tournament is started by pressing the "START" button.  The game board
window pops up as in one-game mode.  The difference is that after one game
is finished, another game between another pair of players will be started
automatically.  When all the matches are played, the tournament ends.  As
described before, matches are organized to have each player plays two games
with each of the other players.  The one who gets most points is the champion.


Internal Documentation
----------------------

This section is for those who want to modify the server for improvement or for
supporting other games.  The archive you obtained should contain the following
files.

Makefile

com.h		def.h		msg.h		server.h	validate.h

client.c	com.c		com_cli.c	com_svr.c	gcu.c
server.c	string.c	validate.c

board.tcl	control.tcl	file.tcl	player.tcl

Organization of the Tournament

The organization being used now is a two-round league.  So, the number of
matches is very large for a class of 40 students.  (40 * 40 - 40 = 1560!!)
This problem can be solved by dividing participants into small groups (e.g. 4
in each group) or by using another organization like a single elimination
tournament.  

The first one can be done manually by cutting the clients database into small
ones and start a league for each smaller group.  Then pick the champion from
each group to form another league to decide who is the champion of the whole
class.

To do the second one, you have to look at the module, control.tcl, in which there are three procedures:

next_pair	It returns the names and the program paths of the next pair of
		clients.  The values are stored in the global variables,
		player1, player2, path1 and path2.
update_table	It updates the Clients Database and Match List to reflect the
		current league table.
create_table	It updates the league table on the display.

They are the interface to other modules.  Keeping them unchanged should
minimize the effort to adapt your changes.

Implementation of Other Games

If you want to the server the support other games, you have to modify two
modules, validate.c and board.tcl.  They are game specific.  validate.c, as
its name implies, checks whether moves are valid or not.  The interface of
this module to other modules is the function:

int validate_move(int player, char *msg)

The first argument is to distinguish which players message to be validate.
There are 2 macro, P1 and P2, defined in def.h.  The second argument is the
message received from a client.  Note that the header has already been chopped.

board.tcl draws the game board and update it when requested.  The interface of
this module is the following three functions:

add_name player1 player2	This procedure adds names, player1 and player2,
				on the side that represent each player.
move_marble position1 position2	It updates the games board by moving a game
				piece from position1 to position2.
init_board			It initializes the game board before a new
				game starts.

All of them are called from gcu.c.  You may also have to look at this file to
resolve game dependency.

Hope you enjoy playing with GameNet! :)

Felix