web/agent_text.html

   1
   2 <html>
   3
   4 <head>
   5 <title> UCC::Progcomp 2013 - Writing an Agent - Text based </title>
   6 </head>
   7
   8 <body bgcolor=white>
   9
  10 <h1> Text based API </h1>
  11
  12 <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>
  13 <p> </p>
  14 <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>
  15 <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>
  16
  17 <hr>
  18
  19 <h2> Overview </h2>
  20
  21 <p> In the following, lines prefixed with "&lt;&lt; " indicate input to the agent, lines prefixed with "&gt;&gt; " indicate output. </p>
  22 <p> The end line character is a unix new line character '\n'. There is no carriage return. </p>
  23 <p> A token prefixed with '$' is taken to be variable, whilst all other tokens are to be interpreted literally. </p>
  24
  25 <hr>
  26
  27 <h2> Game start </h2>
  28
  29 <p> &lt;&lt; $colour </p>
  30 <p> Where: </p>
  31 <ol>
  32         <li> $colour is either "white" or "black" and indicates the colour the agent will be playing as. </li>
  33         <li> The agent should make <i>no response</i> to this message. If it does, it will be declared illegal. </li>
  34 </ol>
  35
  36 <hr>
  37
  38 <h2> Request: Selection </h2>
  39
  40 <p> &lt;&lt; SELECTION? </p>
  41 <p> &gt;&gt; $x $y </p>
  42 <p> &gt;&gt; $x $y $index $type
  43
  44 <p> Where: </p>
  45 <ol>
  46         <li> $x and $y are the x and y co-ordinates of the piece that the agent wishes to select. </li>
  47         <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>
  48              <ol type="a"> <li> The top left square is (x,y) = (0,0). The bottom right is at (x,y) = (7,7). </li>
  49                   <li> Qchess does <b>not</b> recognise standard chess square names (eg: E5) </li>
  50                   <li> A piece belongs to the agent if its colour matches that of the agent. </li> </ol>
  51         </ol>
  52         <li> An invalid selection results in the game ending with the offending agent declared illegal </li>
  53         <li> A valid selection results in a response from qchess; see <b> Update: Agent selects a piece </b> </li>
  54         </ol>
  55 </ol>
  56
  57 <hr>
  58
  59 <h2> Request: Movement </h2>
  60
  61 <p> &lt;&lt; MOVE? </p>
  62 <p> &gt;&gt; $x $y </p>
  63
  64 <p> If an agent selects a piece that cannot move, it will not receive this request before its next selection. </p>
  65
  66 <p> Where: </p>
  67
  68 <ol>
  69         <li> If an agent selected a piece that couldn't move, it will not receive this request before another selection request </li>
  70         <li> $x and $y are the co-ordinates of the destination square </li>
  71         <ol type="i">
  72                 <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>
  73                 <li> If the square was occupied by a piece of the opposing colour, that piece is "taken" and removed from the game </li>
  74                 <li> If the "taken" piece was the opposing king, the agent will win the game. </li>
  75                 <li> The agent must always make a move </li>
  76         </ol>
  77         <li> An invalid move results in the game ending with the offending agent declared illegal. </li>
  78         <li> A valid selection results in a response from qchess; see <b> Update: Agent moves a piece </b> </li>
  79 </ol>
  80
  81
  82 <hr>
  83
  84 <h2> Update: Agent selects a piece </h2>
  85
  86 <p> &lt;&lt; $x $y $index $type </p>
  87
  88 <p> Where: </p>
  89 <ol>
  90      <li> $x and $y are the x and y co-ordinates of the selected piece </li>
  91      <li> $index is either "0" or "1" and indicates which of its two states the selected piece is in. </li>
  92      <li> $type is a string indicating what the state of the piece actually is. </li>
  93      <ol type="a"> <li> This string is one of: "king", "queen", "rook", "knight", "bishop" or "pawn". </li>
  94                    <li> The piece's next move will obey traditional chess movement rules for a piece of this type. </li> </ol>
  95      <li> The agent should <b> not </b> respond to this message, or it will be declared illegal
  96 </ol>
  97
  98 <hr>
  99
 100 <h2> Update: Agent moves a piece </h2>
 101
 102 <p> &lt;&lt; $x1 $y1 -&gt; $x2 $y2 </p>
 103
 104 <p> Where: </p>
 105 <ol>
 106         <li> The piece will have been been selected immediately prior to being moved. </li>
 107         <li> $x1 and $y1 are the x and y co-ordinates of the piece's original square. </li>
 108         <li> $x2 and $y2 are the x and y co-ordinates of the piece's destination square. </li>
 109         <li> Qchess does <b> not </b> provide any indication as to whether the move captured a piece or not </li>
 110 </ol>
 111
 112 <p> <b> Note: </b> The token between the two pairs of co-ordinates is a minus sign followed by a greater than sign. It's supposed to look like an arrow, but in html it's a bit hard to see. </p>
 113
 114
 115 <hr>
 116
 117 <h2> Game ends </h2>
 118
 119 <p> &lt;&lt; QUIT </p>
 120
 121 <p> Where: </p>
 122
 123 <ol>
 124         <li> The agent should immediately exit cleanly without sending any response. </li>
 125         <li> Agents which do not exit after 2 seconds shall be sent SIGKILL </li>
 126 </ol>
 127
 128 <hr>
 129
 130 <h2> Notes: </h2>
 131 <ol>
 132         <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>
 133         <li> Agents can expect to receive an "update" message after responding successfully to the corresponding "request" </li>
 134         <li> If no request was made, the agent can assume the "update" is due to the action of the opponent. </li>
 135 </ol>
 136 <hr>
 137 <p> Page last updated 2013-02-19 by matches </p>
 138
 139 <p> <a href="http://www.ucc.asn.au">The UCC Website</a> </p>
 140 <p> <a href="http://progcomp.ucc.asn.au/2013/web">UCC::Progcomp 2013</a> </p>
 141
 142 </body>
 143
 144 </html>