Dedicated server stuff should now work
[progcomp2013.git] / 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>

UCC git Repository :: git.ucc.asn.au