--- /dev/null
+
+<html>
+
+<head>
+<title> UCC::Progcomp 2013 - Writing an Agent </title>
+</head>
+
+<body bgcolor=white>
+
+
+<h1> What API do I use? </h1>
+
+<p> If you are <b>not</b> using python, your agent will use the <a href="agent_text.html"/>text based API</a> </p>
+<p> If you are using python, you should use the <a href="agent_python.html"/>python API</a>. But you don't have to. </p>
+
+<hr>
+
+<h2> I've read that, but don't know where to start </h2>
+
+<ol>
+ <li> Pick a language. Python is recommended for beginners. </li>
+ <li> Look at the sample agents. Here is the <a href="../agents/sample"/>sample python agent</a> </li>
+ <li> Copy sample and rewrite amazingly awesome quantum chess algorithm of supreme domination </li>
+ <li> Profit </li>
+</ol>
+<hr>
+
+<h2> That was too long; I didn't read it </h2>
+
+<p> Read the <a href="../agents/sample"/>sample python agent</a> instead. </p>
+
+<hr>
+
+<h2> Policy on Threading and Forking </h2>
+
+<p> <b> Don't do it. It is not allowed. Use a single thread like a real man/woman/robot. </b> </p>
+
+<hr>
+<h2> This API seems terrible and I want to use threads</h2>
+
+<p> Too bad. Write your own competition. </p>
+
+<hr>
+
+<p> Page last updated 2013-02-18 by matches </p>
+
+<p> <a href="http://www.ucc.asn.au">The UCC Website</a> </p>
+<p> <a href="http://progcomp.ucc.asn.au/2013/web">UCC::Progcomp 2013</a> </p>
+
+</body>
+
+</html>
--- /dev/null
+
+<html>
+
+<head>
+<title> UCC::Progcomp 2013 - Writing an Agent - python </title>
+</head>
+
+<body bgcolor=white>
+
+<h1> Python API </h1>
+
+<p> Be sure to read and understand <a href="http://research.cs.queensu.ca/Parallel/QuantumChess/QuantumChess.html"/>the rules</a> before reading this page. </p>
+<p> </p>
+<p> The <a href="../agents/sample"/>sample python agent</a> implements this API </p>
+<p> You may still use the <a href="agent_text.html"/>text based API</a> if you insist. </p>
+
+
+<h2> Overview </h2>
+
+
+
+<hr>
+
+<p> Page last updated 2013-02-18 by matches </p>
+
+<p> <a href="http://www.ucc.asn.au">The UCC Website</a> </p>
+<p> <a href="http://progcomp.ucc.asn.au/2013/web">UCC::Progcomp 2013</a> </p>
+
+</html>
--- /dev/null
+
+<html>
+
+<head>
+<title> UCC::Progcomp 2013 - Writing an Agent - Text based </title>
+</head>
+
+<body bgcolor=white>
+
+<h1> Text based API </h1>
+
+<p> Be sure to read and understand <a href="http://research.cs.queensu.ca/Parallel/QuantumChess/QuantumChess.html"/>the rules</a> before reading this page. </p>
+<p> </p>
+<p> All agents (even python ones) are stand alone programs which qchess spawns instances of to play a game. Qchess sends state updates and requests moves from players through pipes. From the agent's point of view, all it has to do is read commands from stdin and respond to stdout. </p>
+<p> <b>Note:</b> Although pipes are pretty damn awesome, they unfortunately always get buffered by default, with a stupidly large size like 4KB. This means that it is unlikely a program will work unless it is able to unbuffer its stdin/stdout streams. In some languages this is trivial. In others it is probably impossible. If you want to use a language where it is impossible, please tell the organiser. Even if I have to rewrite half of the code dealing with external agents, <i>I will make it work</i>. </p>
+
+<hr>
+
+<h2> Overview </h2>
+
+<p> In the following, lines prefixed with "<< " indicate input to the agent, lines prefixed with ">> " indicate output. </p>
+<p> The end line character is a unix new line character '\n'. There is no carriage return. </p>
+<p> A token prefixed with '$' is taken to be variable, whilst all other tokens are to be interpreted literally. </p>
+
+<hr>
+
+<h2> Game start </h2>
+
+<p> << $colour </p>
+<p> Where: </p>
+<ol>
+ <li> $colour is either "white" or "black" and indicates the colour the agent will be playing as. </li>
+ <li> The agent should make <i>no response</i> to this message. If it does, it will be declared illegal. </li>
+</ol>
+
+<hr>
+
+<h2> Request: Selection </h2>
+
+<p> << SELECTION? </p>
+<p> >> $x $y </p>
+<p> << $x $y $index $type
+
+<p> Where: </p>
+<ol>
+ <li> $x and $y are the x and y co-ordinates of the piece that the agent wishes to select. </li>
+ <ol type="i"> <li> $x and $y must be the co-ordinates of a square that is on the board, and occupied by a piece belonging to the agent. </li>
+ <ol type="a"> <li> The top left square is (x,y) = (0,0). The bottom right is at (x,y) = (7,7). </li>
+ <li> Qchess does <b>not</b> recognise standard chess square names (eg: E5) </li>
+ <li> A piece belongs to the agent if its colour matches that of the agent. </li> </ol>
+ </ol>
+ <li> An invalid selection results in the game ending with the offending agent declared illegal </li>
+ <li> A valid selection results in a response from qchess; see <b> Update: Agent selects a piece </b> </li>
+ </ol>
+</ol>
+
+<hr>
+
+<h2> Request: Movement </h2>
+
+<p> << MOVE? </p>
+<p> >> $x $y </p>
+
+<p> If an agent selects a piece that cannot move, it will not receive this request before its next selection. </p>
+
+<p> Where: </p>
+
+<ol>
+ <li> If an agent selected a piece that couldn't move, it will not receive this request before another selection request </li>
+ <li> $x and $y are the co-ordinates of the destination square </li>
+ <ol type="i">
+ <li> The selected piece must be able to move into the square, and the square must be unoccupied or occupied by a piece of the opposing colour </li>
+ <li> If the square was occupied by a piece of the opposing colour, that piece is "taken" and removed from the game </li>
+ <li> If the "taken" piece was the opposing king, the agent will win the game. </li>
+ <li> The agent must always make a move </li>
+ </ol>
+ <li> An invalid move results in the game ending with the offending agent declared illegal. </li>
+ <li> A valid selection results in a response from qchess; see <b> Update: Agent moves a piece </b> </li>
+</ol>
+
+
+<hr>
+
+<h2> Update: Agent selects a piece </h2>
+
+<p> << $x $y $index $type </p>
+
+<p> Where: </p>
+<ol>
+ <li> $x and $y are the x and y co-ordinates of the selected piece </li>
+ <li> $index is either "0" or "1" and indicates which of its two states the selected piece is in. </li>
+ <li> $type is a string indicating what the state of the piece actually is. </li>
+ <ol type="a"> <li> This string is one of: "king", "queen", "rook", "knight", "bishop" or "pawn". </li>
+ <li> The piece's next move will obey traditional chess movement rules for a piece of this type. </li> </ol>
+ <li> The agent should <b> not </b> respond to this message, or it will be declared illegal
+</ol>
+
+<hr>
+
+<h2> Update: Agent moves a piece </h2>
+
+<p> << $x1 $y1 -> $x2 $y2 </p>
+
+<p> Where: </p>
+<ol>
+ <li> The piece will have been been selected immediately prior to being moved. </li>
+ <li> $x1 and $y1 are the x and y co-ordinates of the piece's original square. </li>
+ <li> $x2 and $y2 are the x and y co-ordinates of the piece's destination square. </li>
+ <li> Qchess does <b> not </b> provide any indication as to whether the move captured a piece or not </li>
+</ol>
+
+
+<hr>
+
+<h2> Game ends </h2>
+
+<p> << QUIT </p>
+
+<p> Where: </p>
+
+<ol>
+ <li> The agent should immediately exit cleanly without sending any response. </li>
+ <li> Agents which do not exit after 2 seconds shall be sent SIGKILL </li>
+</ol>
+
+<hr>
+
+<h2> Notes: </h2>
+<ol>
+ <li> The "update" messages give no indication as to which player performed the selection or movement. However this is trivial for agents to keep track of. </li>
+ <li> Agents can expect to receive an "update" message after responding successfully to the corresponding "request" </li>
+ <li> If no request was made, the agent can assume the "update" is due to the action of the opponent. </li>
+</ol>
+<hr>
+<p> Page last updated 2013-02-18 by matches </p>
+
+<p> <a href="http://www.ucc.asn.au">The UCC Website</a> </p>
+<p> <a href="http://progcomp.ucc.asn.au/2013/web">UCC::Progcomp 2013</a> </p>
+
+</body>
+
+</html>
--- /dev/null
+
+<html>
+
+<head>
+<title> UCC::Progcomp 2013 </title>
+</head>
+
+<body bgcolor=white>
+
+<hr>
+
+<p> Page last updated 2013-02-18 by matches </p>
+
+<p> <a href="http://www.ucc.asn.au">The UCC Website</a> </p>
+<p> <a href="http://progcomp.ucc.asn.au/2013/web">UCC::Progcomp 2013</a> </p>
+
+</body>
+
+</html>
--- /dev/null
+<html>
+
+<head>
+<title> UCC::Progcomp 2013 - Getting qchess </title>
+</head>
+
+<body bgcolor=white>
+
+<p> qchess is a python2.7 implementation of <a href="http://research.cs.queensu.ca/Parallel/QuantumChess/QuantumChess.html"/>Quantum Chess</a> </p>
+
+<h1> tl;dr </h1>
+
+<table border="1">
+
+<tr> <th> </th> <th> Binary </th> <th> Script (requires python2.7 and pygame1.9) </th> </tr>
+<tr> <th> Windows </th> <td> <a href="http://git.ucc.asn.au/?p=progcomp2013.git;a=blob;f=qchess/build/exe.win32-2.7.zip"/>32 bit</a> </td> <td> <a href="http://git.ucc.asn.au/?p=progcomp2013.git;a=blob_plain;f=qchess/qchess.py"/>qchess.py</a></td> </tr>
+<tr> <th> Linux </th> <td> <a href="http://git.ucc.asn.au/?p=progcomp2013.git;a=blob;f=qchess/build/exe.linux-x86_64-2.7.zip"/>64 bit</a></td> <td> <a href="http://git.ucc.asn.au/?p=progcomp2013.git;a=blob_plain;f=qchess/qchess.py"/>qchess.py</a></td> </tr>
+
+
+
+
+</table>
+
+<p> <b> Warning: </b> Some things in the windows version will not work. </p>
+<p> <b> Warning: </b> The actual competition will be run on linux. If your program doesn't work on linux, you may not be able to enter. </p>
+
+
+<hr>
+
+
+<h3> Git </h3>
+<p> The best way to do things is to use <a href="http://git-scm.com/"/>git</a> and clone the repository at <a href="http://git.ucc.asn.au/?p=progcomp2013.git"/>git://git.ucc.asn.au/progcomp2013.git</a>. Run "git pull" everytime a major change is announced. </p>
+
+
+<hr>
+
+
+<h3> Files and Directories </h3>
+
+<ul>
+ <li> qchess/qchess.py - Python script version of qchess </li>
+ <li> agents/ - Where all the agents will go when the competition runs
+ <li> agents/sample.py - A sample agent in python </li>
+ <li> qchess/build/ - Compiled binaries of the qchess program </li>
+ <li> qchess/src/ - Source python files for qchess </li>
+ <li> web/ - This website </li>
+</ul>
+
+<hr>
+
+<h3> qchess.py </h3>
+
+<ul>
+
+ <li> You will need <a href="http://www.python.org/download/releases/2.7.3"/>python 2.7.3</a> </li>
+ <ul> <li> On Debian/Ubuntu just run `sudo apt-get install python` </li>
+ <li> On Windows, download and install the x86 (32bit) MSI, <b>not</b> the x86-64 (64bit) MSI) </li> </ul>
+ <li> You will need <a href="http://www.pygame.org/download.shtml"/>pygame 1.9.1</a> </li>
+ <ul> <li> On Debian/Ubuntu just run `sudo apt-get install python-pygame` </li>
+ <li> On Windows, ,ake sure you get the pygame for python 2.7 MSI </li> </ul>
+
+ <li> Hopefully, if you have those, things will just work (TM) </li>
+ <ul> <li> In linux, navigate to the qchess directory, then run with ./qchess.py </li>
+ <li> In windows, the application <i>should</i> start when you double click on it </li>
+ <li> If you want to give command line arguments, you will need to use cmd on windows </li>
+ </ul>
+</ul>
+
+<hr>
+
+<h3> Compiled Binaries </h3>
+
+<p> <b> Warning:</b> I am no longer testing the binaries. I believe the linux binary works, but the Windows binary might not. </p>
+<p> If they work for you, that is awesome, but I recommend installing python and using the python script. </p>
+<p> You'll probably want to enter in python, since the python script gives you a lot of useful functions. </p>
+
+<p> <b> On the other hand... </b>, if you have problems with an incompatable version of python, try the binaries! </p>
+
+<hr>
+
+<p> Page last updated 2013-02-18 by matches </p>
+
+<p> <a href="http://www.ucc.asn.au">The UCC Website</a> </p>
+<p> <a href="http://progcomp.ucc.asn.au/2013/web">UCC::Progcomp 2013</a> </p>
+
+</body>
+</html>
+
<li> <a href="http://lists.ucc.gu.uwa.edu.au/mailman/listinfo/progcomp" target="_blank"/>Join the mailing list</a> </li>
<ul> <li> <b> Important: </b> Don't email the mailing list directly; email the competition organiser (matches at ucc dot asn dot au) </li> </ul>
<li> <a href="http://www.ucc.asn.au/services/irc.ucc"/>Join the #progcomp channel on IRC</a> </li>
- <li> <a href="get_qchess.html"/>Obtain a copy of the qchess program</a> </li>
- <li> <a href="using_qchess.html"/>Using the qchess program</a> </li>
+ <li> <a href="get.html"/>Obtain a copy of the qchess program</a> </li>
+ <li> <a href="using.html"/>Using the qchess program</a> </li>
<li> <a href="agent.html"/>Writing an agent for the qchess program</a> </li>
<li> <a href="enter.html"/>Entering the competition</a> </li>
</ol>
<hr>
-<p> Page last updated 2012-01-30 by matches </p>
+<p> Page last updated 2013-02-18 by matches </p>
<p> <a href="http://www.ucc.asn.au">The UCC Website</a> </p>
<p> <a href="http://progcomp.ucc.asn.au">UCC::Progcomp Website</a> </p>
--- /dev/null
+
+<html>
+
+<head>
+<title> UCC::Progcomp 2013 - Using qchess </title>
+</head>
+
+<body bgcolor=white>
+
+Assuming you have <a href="get.html"/>obtained qchess</a>, here is how to use it.
+
+<h1> GUI - Playing a game </h1>
+
+<p> You'll probably want to play against sample agents to learn the game. Or you'll want to play against your own agent to test it. </p>
+
+<ol>
+ <li> <b> Start qchess </b> </li>
+ <ul> <li> Open a terminal </li>
+ <li> Navigate to the directory where you downloaded qchess </li>
+ <li> Run `./qchess.py' </li>
+ <li> You should see a chess board with "Choose white player" and some rather stylish buttons. </li> </ul>
+ <li> <b> Choose players </b> </li>
+ <ul> <li> A "human" player plays using the mouse. That's you. </li>
+ <li> If you click "agent", you can choose between "internal" or "external" </li>
+ <ul> <li> "internal" gives you a choice between the sample agents that come with qchess </li>
+ <li> "external" lets you browse select an executable file as an agent. Use this to choose your own agent. </li>
+ <li> If there is an error, qchess usually restarts the selection process. Usually. </li> </ul>
+ <li> In theory, "network" lets you connect to a player (human or agent) running remotely via another qchess program </li>
+ <ul> <li> Best to leave this button alone. It probably works, but it won't be that useful. </li> </ul>
+ <li> You can have any combination of types for the two players. So you can play against your friends.</li> </ul>
+ <li> <b> Play / Watch game </b> </li>
+ <ul> <li> For a human player, a border around the square under the mouse indicates it is that player's turn </li>
+ <li> You can't undo selections, because selecting a piece can affect its state. Quantum Chess is "touch move". </li>
+ <li> Be careful not to select a piece that cannot move. You will lose a turn. Even if you don't affect its state, and even if you didn't know for sure that it couldn't move. </li>
+ <li> Click on pieces to select them. Selected piece and possible moves are highlighted. Click again to move. </li>
+ <li> Right click on a piece to overlay the squares it may move into with probabilities </li>
+ <li> Middle click on any square to overlay all pieces which could reach the square if it were occupied. </li>
+ <li> You can quit with the close window button </li> </ul>
+</ol>
+
+<h1> Advanced stuff - command line options </h1>
+
+<p> On unix systems, running `./qchess.py --help' should show you a help file. </p>
+<p> On windows (or on unix) you can also find the help file in data/help.txt </p>
+<p> Or you can click <a href="../qchess/data/help.txt"/>here</a> </p>
+
+<p> I'll explain some options here anyway, because no one reads help files. Also it might not be up to date.</p>
+
+<ul>
+ <li> Any argument that doesn't start with '--' is treated as the white or black player, in the order these arguments appear </li>
+ <ul> <li> If the player name starts with '@', it is a special player. "@human" is a human player; "@internal:AgentName" is an internal agent, and "@network:server_address" is a network player. </li>
+ <li> Any player name that doesn't start with '@' is considered an executable file which will play qchess as an external agent. </li> </ul>
+ <li> You can save moves to a log file with the --log=filename option. Don't supply a filename to log to stdout. </li>
+ <ul> <li> You can save the state of the board and last two events by adding a '@' before the filename. The file is re-written every two events. </li>
+ <li> Normally the log file contains all moves; the "state file" contains the state of the board and at most 2 events after that. </li>
+ <li> You can specify multiple log files. </li> </ul>
+ <li> You can replay moves from a log file with --file=logfile </li>
+ <ul>
+ <li> This works regardless of whether the log file contains all moves or just the last state </li>
+ <li> If the file is still being logged to, the replay waits for moves to be logged </li>
+ <li> If you supply two players for the game, those two players will resume play at the end of the replay </li>
+ <li> Otherwise the program will wait for you to exit at the end of the replay. </li>
+ <li> You can log to a file and replay from a log file simultaneously </ul>
+
+ <li> During the actual competition, you can watch games live with --file=http://progcomp.ucc.asn.au/2013/web/current0.log </li>
+ <ul> <li> I will advertise exactly what url to use </li> </ul>
+ <li> You can set the time limit on agent (not human) moves with the --timeout=time option </li>
+ <li> qchess sleeps a bit after each action so that you can see what agents are doing. You can change this interval with --delay=interval </li> </ul>
+
+<h2> Output of qchess </h2>
+
+<p> If you want to be clever and do something like evolutionary code, you'll need to play lots of games and do stuff based on the output. </p>
+
+<p> qchess outputs lines of the form: `colour [result]' </p>
+<ul>
+ <li> colour indicates which player's turn the game ended on. So it is "white" or "black". </li>
+ <li> result is only present if the game didn't end in a normal victory. </li>
+ <ul> <li> A result of "DRAW" indicates a draw. It's in all caps because draws are exciting. </li>
+ <li> A result of "terminated" indicates the game was manually quit by a human being. </li>
+ <li> A result of "ILLEGAL" followed by either "white" or "black" indicates that that player (an agent) did something illegal. </li>
+
+ <ul> <li> The rest of the output indicates exactly what the player did </li>
+ <li> Illegal things include: </li>
+ <ul> <li> "timeout" didn't make a move before a timeout </li>
+ <li> "not_your_piece" selected wrong colour piece </li>
+ <li> "empty_square" selected empty square </li>
+ <li> "illegal_move" the selected piece can't move the way that the player tried to move it </li>
+ <li> "gibberish" sent a response that made no sense </li>
+ <li> "unresponsive" an agent didn't respond; we assume it crashed (and kill it with SIGKILL just in case). </li>
+ <li> A human player should (we hope) not be able to cause the "ILLEGAL" output </li> </ul> </ul> </ul>
+</ul>
+
+<hr>
+<p> The actual competition "simulator" is a bash script that runs lots of qchess instances and creates scores for each agent based on the outputs. </p>
+
+
+<hr>
+
+<p> Page last updated 2013-02-18 by matches </p>
+
+<p> <a href="http://www.ucc.asn.au">The UCC Website</a> </p>
+<p> <a href="http://progcomp.ucc.asn.au/2013/web">UCC::Progcomp 2013</a> </p>
+
+
+
+</body>
+
+</html>
git.ucc.asn.au / progcomp2013.git / commitdiff
UCC git Repository :: git.ucc.asn.au