X-Git-Url: https://git.ucc.asn.au/?p=progcomp2013.git;a=blobdiff_plain;f=web%2Fusing.html;fp=web%2Fusing.html;h=24f96b53319336c80e9ebc979081cbe0590e09a8;hp=0000000000000000000000000000000000000000;hb=baa4d9d6440dac63367a80b88b1c466deb9263a9;hpb=a6d91c8bb286fa91f9e2a56b304043ff48154322 diff --git a/web/using.html b/web/using.html new file mode 100644 index 0000000..24f96b5 --- /dev/null +++ b/web/using.html @@ -0,0 +1,108 @@ + + + + + UCC::Progcomp 2013 - Using qchess + + + + +Assuming you have obtained qchess, here is how to use it. + +

GUI - Playing a game

+ +

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.

+ +

Start qchess

Open a terminal
Navigate to the directory where you downloaded qchess
Run `./qchess.py'
You should see a chess board with "Choose white player" and some rather stylish buttons.

Choose players

A "human" player plays using the mouse. That's you.
If you click "agent", you can choose between "internal" or "external"

"internal" gives you a choice between the sample agents that come with qchess
"external" lets you browse select an executable file as an agent. Use this to choose your own agent.
If there is an error, qchess usually restarts the selection process. Usually.

In theory, "network" lets you connect to a player (human or agent) running remotely via another qchess program

Best to leave this button alone. It probably works, but it won't be that useful.

You can have any combination of types for the two players. So you can play against your friends.

Play / Watch game

For a human player, a border around the square under the mouse indicates it is that player's turn
You can't undo selections, because selecting a piece can affect its state. Quantum Chess is "touch move".
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.
Click on pieces to select them. Selected piece and possible moves are highlighted. Click again to move.
Right click on a piece to overlay the squares it may move into with probabilities
Middle click on any square to overlay all pieces which could reach the square if it were occupied.
You can quit with the close window button

+ +

Advanced stuff - command line options

+ +

On unix systems, running `./qchess.py --help' should show you a help file.

On windows (or on unix) you can also find the help file in data/help.txt

Or you can click here

+ +

I'll explain some options here anyway, because no one reads help files. Also it might not be up to date.

+ +

Any argument that doesn't start with '--' is treated as the white or black player, in the order these arguments appear

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.
Any player name that doesn't start with '@' is considered an executable file which will play qchess as an external agent.

You can save moves to a log file with the --log=filename option. Don't supply a filename to log to stdout.

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.
Normally the log file contains all moves; the "state file" contains the state of the board and at most 2 events after that.
You can specify multiple log files.

You can replay moves from a log file with --file=logfile

This works regardless of whether the log file contains all moves or just the last state
If the file is still being logged to, the replay waits for moves to be logged
If you supply two players for the game, those two players will resume play at the end of the replay
Otherwise the program will wait for you to exit at the end of the replay.
You can log to a file and replay from a log file simultaneously

During the actual competition, you can watch games live with --file=http://progcomp.ucc.asn.au/2013/web/current0.log

I will advertise exactly what url to use

You can set the time limit on agent (not human) moves with the --timeout=time option
qchess sleeps a bit after each action so that you can see what agents are doing. You can change this interval with --delay=interval

+ +

Output of qchess

+ +

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.

+ +

qchess outputs lines of the form: `colour [result]'

colour indicates which player's turn the game ended on. So it is "white" or "black".
result is only present if the game didn't end in a normal victory.

A result of "DRAW" indicates a draw. It's in all caps because draws are exciting.
A result of "terminated" indicates the game was manually quit by a human being.
A result of "ILLEGAL" followed by either "white" or "black" indicates that that player (an agent) did something illegal.

The rest of the output indicates exactly what the player did
Illegal things include:

"timeout" didn't make a move before a timeout
"not_your_piece" selected wrong colour piece
"empty_square" selected empty square
"illegal_move" the selected piece can't move the way that the player tried to move it
"gibberish" sent a response that made no sense
"unresponsive" an agent didn't respond; we assume it crashed (and kill it with SIGKILL just in case).
A human player should (we hope) not be able to cause the "ILLEGAL" output

+ +

The actual competition "simulator" is a bash script that runs lots of qchess instances and creates scores for each agent based on the outputs.

+ + +

+ +

Page last updated 2013-02-18 by matches

+ +

The UCC Website

UCC::Progcomp 2013

+ + + + + +