Quadrature by Scott Dial <dialsa@rose-hulman.edu>
CSSE 473 - Fall 2005
========================

This text will not cover game rules, please read the Official Rules.txt which
contains the official rules for Quadrature as published by Mark Steere on
rec.games.abstract in 1996. The rules for tournament play and the information
needed to implement an external player will be detailed below.

Please check the class websites for software updates, clarifications, and
other information that will be posted as they become available.

TOURNAMENT RULES
========================

The tournament will be played in swiss-tournament fashion. Each player will play
each other player as white and as black. After the first round and in any
required successive rounds, the players will be split up into groups of the
same number of wins until all ties are resolved. As it is very possible that the
players may be very deterministic in their play, successive rounds will be
played until no further changes in standrings are made.

The tournament will be run on my desktop computer. The important details are:
Windows XP, Athlon XP 2100+, 1Gb RAM, RAID5 array. Essentially, if your
AI requires more CPU power, memory, or disk I/O than I have available then you
should reconsider what you are doing. An important detail here is that I will be
running java with "-Xmx512M" to set a known upperbound on memory.
Finally, the time-per-turn will be set at 15 seconds.

In addition to the official rules, a new rule of "no repeated states" is being
included. This rule is similar to the draw rule used in chess. A state is state
is defined to be the positional infomration of the board as well as the status
of the markers. In most gameplay, this rule should have no effect because there
is no way to repeat states. It has come to my attention that there is an
oversight in the rules concerning mutual squaring in which one can repetitiously
take the opponents pieces and then the opponent can retake the piece. This can
continue on forever because it is considered an aggressive move. Hence, no
repeated states will be allowed in the tournament.

QUADRATURE.INI
========================

Within quadrature.ini you will find a group of configuration options:

[quadrature]
Timeout = 30 <- How long will each player get each call (in seconds)?
Logging = True <- Should we write debugging log files?
LoggingLevel = debug <- What logging level should the players run at?
LoggingPattern = %d [%t] (%F:%L) - %m%n  <- What pattern should we log with?
RecordGames = True <- Should we write replay files for games?
ReplayDelay = 100 <- How many milliseconds should be wait inbetween steps?
GamesPerMatch = 3 <- Best of how many games for a match?
EnforceNoThreads = True <- Don't allow players to leave threads alive

NumberOfPlayers = 4 <- How many Player[n] entries are there?
Player0 = RandomPlayer
Player1 = APlayer
Player2 = BPlayer
Player3 = Scott

To add a player, please increase NumberOfPlayers to 5, then add a "Player4"
set equal to the name of the class for your player.

IMPLEMENTATION DETAILS
========================

As you are aware, Quadrature has been written in Java. In particular, I have
targeted the code for version 1.4. You should feel free to use a later version
of java if you'd like.

To compile your player, you will be required to include both Quadrature.jar and
log4j-1.2.11.jar in your classpath:

javac -classpath Quadrature.jar;log4j-1.2.11.jar <source file>

Quadrature and log4j will provide for you several essential and useful things
(Player, Move, and Logger). Your player class will be required to implement the
Player inteface:

import org.apache.log4j.Logger;
public interface Player {
	public void startGame(Integer player, Integer time, Logger logger);
	public Move doTurn(int[][] board, int[] marker);
	public void skipTurn(int[][] board, int[] marker);
	public void endGame(int[][] board, int[] marker);
}

Other important classes provided:

public class Move implements Cloneable, Serializable {
	public Point from, to;

	public Move(Point from, Point to);
	public Move(int x1, int y1, int x2, int y2);
}

public class Point implements Cloneable, Serializable {
	public int x, y;

	public Point(int x, int y);
}

At the start of a game, the startGame will be called providing you with whether
you are WHITE (1) or BLACK (2), how much time you will have to make your
decisions, and an instance of a log4j Logger. Then, on each turn you will either
be asked for a Move via doTurn or told that your turn has been skipped via
skipTurn. The board will provided in a board[x][y] format with board[0][0]
representing the top-left corner of the board. Each element of board will be
of either EMPTY (0), WHITE (1), BLACK (2). As well, you will be provided with
the current status of the marker pieces with marker[0] being WHITE's count and
marker[1] being BLACK's count. At the completion of the game, endGame will be
be the final call made to your player and at that time any cleanup should be
performed.

IMPORTANT: Your player will be expected to return from any function call within
the the time specified by the startGame (including the startGame itself). Any
failure to return within this time period will be an automatic forfeit for the
current game. A simple way to do this would be to spawn a thread and join it.
It follows then that you must end any threads before returning, otherwise you
will be disqualified.

ALSO IMPORTANT: If your player returns an invalid move, then you will be
automatically forfeited.

REALLY IMPORTANT: If _any_ exception is thrown by your player, then it will
be caught by the game and will be an automatic disqualification. It would be
a good idea to catch and manage any exceptions.

REALLY SUPER IMPORTANT: Please clean-up release any unnessecary memory whenever
possible. Garbage collection and finalization with be forced by the game
_off of the clock_. In other worse, it is to your benefit to avoid having a
garbage collection occur during your turn. Also, large amounts of persistant
memory usage will be frowned upon.

USING Logger
========================

Your player will be passed a log4j.Logger instance which will be directed to a
file (the filename will be sequentially chosen, no overwriting). This will more
than likely be your primary means of debugging. Log4j provides a number of
useful features, but most importantly, you will want to make use of the message
logging functions: debug, info, warn, error, fatal. With that order of priority,
if you set LoggingLevel all levels "above" that in the order will be included.

For the competition, I will be setting the logging level to "warn". So, debug
and info messages will not be recorded. So, feel free to write lots of debug
messages for your purposes as there will be virtually no time penalty during the
competition for the execution of these functions.

For example:

public void startGame(Integer player, Integer time, Logger logger) {
	if(player.intValue() == 0)
		logger.fatal("Uh oh! We didn't get a valid input!");
	logger.info("We are " + (player.intValue() == 1 ? "white!" : "black!"));
}

NOTE: If you are familiar with log4j, feel free to modify the PatternLayout for
your purposes.

MISCELLANEOUS
========================

* Please make sure all of the files associated with your player start with your
  player's name (or at least the same unique abbreviation). This is to be done
  to avoid namepsace conflicts (using inner classes where possible is preferable
  for your own benefit, in this case).

* Your final turnin will have to be in a form that I can compile from source.
  I will not make use of any class files without being able to inspect the code
  that has generated it. There is one exception: if you have data files, then
  you may provide them as-is. If you can provide a Makefile, then great,
  otherwise please provide me with any special instructions, if any.

* An effort has been made to disallow certain blatant unsportsman-like playing
  however no security is ever perfect. Any cheating will be severely frowned
  upon. Besides, the winner will naturally recieve a lot of scrutiny, so it
  would not be wise. There have been no hard-fast rules set to avoid stiffling
  creativity. If you are concerned that you may be cheating, then please
  ask for a clarification. I will post all clarifications on the class website.

* If you find any bugs, then please notify me so that I can fix it as soon as
  possible. Please check that you are using the latest version of the game (you
  can find the version number in the log file or by
	java -jar Quadrature.jar -version
  and the reporducibility of the error before reporting any problems. I will
  need to be able to reproduce the error or you will have to provide detailed
  information so that I can take care of it.

* Anything else, please ask.
