web/using.html

   1
   2 <html>
   3
   4 <head>
   5 <title> UCC::Progcomp 2013 - Using qchess </title>
   6 </head>
   7
   8 <body bgcolor=white>
   9
  10 Assuming you have <a href="get.html"/>obtained qchess</a>, here is how to use it.
  11
  12 <h1> GUI - Playing a game </h1>
  13
  14 <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>
  15
  16 <ol>
  17         <li> <b> Start qchess </b> </li>
  18         <ul> <li> Open a terminal </li>
  19              <li> Navigate to the directory where you downloaded qchess </li>
  20              <li> Run `./qchess.py' </li>
  21              <li> You should see a chess board with "Choose white player" and some rather stylish buttons. </li> </ul>
  22         <li> <b> Choose players </b> </li>
  23         <ul> <li> A "human" player plays using the mouse. That's you. </li>
  24              <li> If you click "agent", you can choose between "internal" or "external" </li>
  25              <ul> <li> "internal" gives you a choice between the sample agents that come with qchess </li>
  26                   <li> "external" lets you browse select an executable file as an agent. Use this to choose your own agent. </li>
  27                   <li> If there is an error, qchess usually restarts the selection process. Usually. </li> </ul>
  28              <li> In theory, "network" lets you connect to a player (human or agent) running remotely via another qchess program </li>
  29              <ul> <li> Best to leave this button alone. It probably works, but it won't be that useful. </li> </ul>
  30              <li> You can have any combination of types for the two players. So you can play against your friends.</li> </ul>
  31         <li> <b> Play / Watch game </b> </li>
  32         <ul> <li> For a human player, a border around the square under the mouse indicates it is that player's turn </li>
  33              <li> You can't undo selections, because selecting a piece can affect its state. Quantum Chess is "touch move". </li>
  34              <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>
  35              <li> Click on pieces to select them. Selected piece and possible moves are highlighted. Click again to move. </li>
  36              <li> Right click on a piece to overlay the squares it may move into with probabilities </li>
  37              <li> Middle click on any square to overlay all pieces which could reach the square if it were occupied. </li>
  38              <li> You can quit with the close window button </li> </ul>
  39 </ol>
  40
  41 <h1> Advanced stuff - command line options </h1>
  42
  43 <p> On unix systems, running `./qchess.py --help' should show you a help file. </p>
  44 <p> On windows (or on unix) you can also find the help file in data/help.txt </p>
  45 <p> Or you can click <a href="../qchess/data/help.txt"/>here</a> </p>
  46
  47 <p> I'll explain some options here anyway, because no one reads help files. Also it might not be up to date.</p>
  48
  49 <ul>
  50         <li> Any argument that doesn't start with '--' is treated as the white or black player, in the order these arguments appear </li>
  51         <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>
  52              <li> Any player name that doesn't start with '@' is considered an executable file which will play qchess as an external agent. </li> </ul>
  53         <li> You can save moves to a log file with the --log=filename option. Don't supply a filename to log to stdout. </li>
  54         <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>
  55              <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>
  56              <li> You can specify multiple log files. </li> </ul>
  57         <li> You can replay moves from a log file with --file=logfile </li>
  58         <ul>
  59              <li> This works regardless of whether the log file contains all moves or just the last state </li>
  60              <li> If the file is still being logged to, the replay waits for moves to be logged </li>
  61              <li> If you supply two players for the game, those two players will resume play at the end of the replay </li>
  62              <li> Otherwise the program will wait for you to exit at the end of the replay. </li>
  63              <li> You can log to a file and replay from a log file simultaneously </ul>
  64
  65         <li> During the actual competition, you can watch games live with --file=http://progcomp.ucc.asn.au/2013/web/current0.log </li>
  66         <ul> <li> I will advertise exactly what url to use </li> </ul>
  67         <li> You can set the time limit on agent (not human) moves with the --timeout=time option </li>
  68         <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>
  69
  70 <h2> Output of qchess </h2>
  71
  72 <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>
  73
  74 <p> qchess outputs lines of the form: `colour [result]' </p>
  75 <ul>
  76         <li> colour indicates which player's turn the game ended on. So it is "white" or "black". </li>
  77         <li> result is only present if the game didn't end in a normal victory. </li>
  78         <ul> <li> A result of "DRAW" indicates a draw. It's in all caps because draws are exciting. </li>
  79              <li> A result of "terminated" indicates the game was manually quit by a human being. </li>
  80              <li> A result of "ILLEGAL" followed by either "white" or "black" indicates that that player (an agent) did something illegal. </li>
  81
  82              <ul> <li> The rest of the output indicates exactly what the player did </li>
  83                   <li> Illegal things include: </li>
  84                   <ul> <li> "timeout" didn't make a move before a timeout </li>
  85                        <li> "not_your_piece" selected wrong colour piece </li>
  86                        <li> "empty_square" selected empty square </li>
  87                        <li> "illegal_move" the selected piece can't move the way that the player tried to move it </li>
  88                        <li> "gibberish" sent a response that made no sense </li>
  89                        <li> "unresponsive" an agent didn't respond; we assume it crashed (and kill it with SIGKILL just in case). </li>
  90                   <li> A human player should (we hope) not be able to cause the "ILLEGAL" output </li> </ul> </ul> </ul>
  91 </ul>
  92
  93 <hr>
  94 <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>
  95
  96
  97 <hr>
  98
  99 <p> Page last updated 2013-02-18 by matches </p>
 100
 101 <p> <a href="http://www.ucc.asn.au">The UCC Website</a> </p>
 102 <p> <a href="http://progcomp.ucc.asn.au/2013/web">UCC::Progcomp 2013</a> </p>
 103
 104
 105
 106 </body>
 107
 108 </html>