This documents describes the protocol that JagoClient uses to communicate with Go partners. Its purpose is to allow third party programs to connect to Jago.
The program uses a standard socket connection. For the purpose of connecting only, one partner acts as the server, running a demon thread, which will wait for connections on a specific port (default is 6970). The other partner acts as a client, which tries to connect to this server. If the connection is successful, the server will start a new thread and a connection window, which can communicate to with the client. The client will also open a connection window. After this, both partners communicate on equal level.
Clearly, a certain prodecure must be followed by both partners to agree about what is chat, and what is a command, and how to ask and answer a request. This procedure is described in the sequel.
In general commands will start with @@
, while everything else will be chat and is echoed to the chat window. Confirmation commands
start with @@!
, while denials
start with @@-
.
You can check the connection using a telnet program. E.g., type
telnet localhost 6970
This way, you can try out all commands.
First of all, if the server is busy and unable to service request, it will return
@@busy
to you and cut down the connection after this. The client should identify itself by sending
@@name name
where name is any string (with or without space). This string will appear in the connection window title. it may be set by the "Your Name" menu item.
The connection ends with the termination of the socket.
To ask for a game, one partner sends the following request
@@board color size time extra-time extra-moves handicap
where color is either b or w (in small caps) and will be the other player's color, size is the board size, time is the time for the game in seconds, extra-time the byo-yomi time in minutes, extra-moves the number of moves per extra time period, and handicap is the handicap for the game. An example would be
@@board b 19 1 10 25 0
This asks for a game as white on a normal board in the 1/10 timing fashion with 25 moves per 10 minute period, and no hadicap. If the other partner agrees to the game, he will send back the same command with the confirmation mark
@@!board color size time extra-time extra-moves handicap
and generate a local board. Upon receipt of this confirmation, the first partner will generate a local board and send
@@start
The other partner will confirm to the start command with
@@!start
At this time, the clocks start running down and the handicap stones are generated on both boards.
To decline the match, he will answer
@@-board
and no board will be generated.
A move is sent as
@@move color x-coord y-coord black-time black-moves white-time white-moves
where color is the color of the move, x-coord is the column coordinate (left is 0), y-coord is the row coordinate (in reverse order, top is 0), black-time is the remaining black time in seconds, black-moves the moves black has to make in this extra time period (-1, if not in byo-yomi), white-time and white-moves are defined correspondingly. The move must be confimed by the other partner as valid in the usual fashion
@@!move ...
with an exact repetition of parameters. It will be displayed by the partner. The time will be taken from the point, where the move is displayed. The partner will believe in the times send by the move command entirely. Remember, this is a cooperative protocol, which does not assume cheating.
A pass is sent as
@@pass black-time black-moves white-time white-moves
and confirmed as usual with
@@!pass
To end a game, you have to send the end-game request
@@endgame
This has to be confirmed by the partner with
@@!endgame
At this point, no more moves are accepted. Instead, each player is responsible to determine the correct result by removing the prisoners and determine the local count. Once either player has determined the count, he can send it to the partner with
@@result black-points white-points
The partner should then accept or decline this result, with
@@!result ...
or
@@-result ...
There are some more commands. First of all, there might be a request for undo.
@@undo
This must be either confirmed or declined in the usual way. Then there is the adjourn command.
@@adjourn
This is sent, whenever the opponent closes the board. It will effectively end the game.
To reload an old game, a partner will send the
@@restore
command. This command must be either declined or accepted. It can only be sent, if there is no current game going on. The partner, who starts the restore procedure must send the moves after the confirmation command. This is done with
@@@board ...
to set up the board in the same fashion as above (see the @@board
command). The command must not be accepted. To send a black move, use
@@@b x-coord y-coord black-time black-moves white-time white-moves
In the same way as with @@move
. To send a white move, use
@@@w ...
in the same fashion.
This ends the explanation of the protocol. All other commands are chat. You must use only complete lines for chat.