The HTTP protocol is used for communication between the clients and the gameroom/gameserver. Sets of key=value pairs are sent by the clients using the usual HTTP POST method. The HTTP RESPONSE is a web page of type 'text/plain' and also contains key=value pairs seperated by '\n'. In the response all value strings are modified so that '%' chars are replaced with "%25" and all '\n' chars are replaced with "%13" (in that order of course). So a client must undo these subsitutions in reverse order before looking at the values. All responses end with a line containing only the string:
--END--The client program must be supplied with the gameroom URL along with the user's login and password. The client program then POSTs to the given URL to allow the user to login and play games.
Gameroom Protocol
The URL for clients to access the gameroom is:
http://arimaa.com/arimaa/gameroom/client1gr.cgiLogin
POSTRESPONSEaction=login username=[as provided by the user] password=[as provided by the user]Note that bot accounts cannot login with this interface. Bots should use the 'Arimaa Gameroom Interface' package mentioned on the Download page.sid=[the gameroom session id which must be provided with all future POSTs] grid=[the id of this gameroom] error=[if there was a problem, this contains the error message which can be displayed to the user]Create Game
POSTRESPONSEaction=newgame sid=[gameroom session id] role=[w or b; which side the user will be playing] timecontrol=[Arimaa time control string; see Match Rules for specs] rated=[0 for unrated; 1 for rated]gid=[id of the new game] gsurl=[URL of the gameserver where the game will be hosted] tid=[authentication string that needs to be passed to the gameserver later] error=[if there was a problem, this contains the error message which can be displayed to the user]Find My Games
POSTRESPONSEaction=mygames sid=[gameroom session id]error=[if there was a problem, this contains the error message which can be displayed to the user] num=[number of games found] 1=[game information record for the first game; see below for format] 2=[game information record for the second game] ... ... [num]=[game information record for the last game in the list]Each game information record is a set of key=value pairs seperated by '\n' and with all value strings modified so that '%' chars are replaced with "%25" and all '\n' chars are replaced with "%13". Each record contains the following fields:
gid=[game id] role=[role=[w or b; which side the user will be playing] timecontrol=[time control string] rated=[[0 for unrated; 1 for rated] postal=[1 if game is postal; 0 if game is not postal] createdts=[unix timestamp of when the game was created] opponent=[username of opponent]Find Invited Me Games - Games where someone has invited us to play
POSTRESPONSEaction=invitedmegames sid=[gameroom session id]Same as for 'Find My Games'.Find Open Games
POSTRESPONSEaction=opengames sid=[gameroom session id]Same as for 'Find My Games'.Reserve Seat - Put our name on an open seat; or view game
POSTRESPONSEaction=reserveseat sid=[gameroom session id] gid=[game id] role=[w or b or v; which side the user will be playing or v if viewing]gid=[id of the new game] gsurl=[URL of the gameserver where the game will be hosted] tid=[authentication string that needs to be passed to the gameserver later] error=[if there was a problem, this contains the error message which can be displayed to the user]This can be used to join an open game (or rejoin a game) if role is set to 'w' or 'b' or to watch a game if role is set to 'v'.
Cancel Game
POSTRESPONSEaction=cancelopengame sid=[gameroom session id] gid=[game id]error=[if there was a problem, this contains the error message which can be displayed to the user] ok=[1 if game canceled sucessfully]Find Game ID - find the permanent game id using the temporary game id
POSTRESPONSEaction=findgameid tid=[temporary game id]error=[if there was a problem, this contains the error message which can be displayed to the user] gid=[permanent game id]Logout
POSTRESPONSEaction=logout sid=[gameroom session id]error=[if there was a problem, this contains the error message which can be displayed to the user] ok=[1 if logged out sucessfully]
Gameserver Protocol
Once a client program has interacted with the gameroom to create a game or reserve an open seat, the client will have the information needed to begin interactions with the gameserver and allow the user to play the game.
The URL to access this service is provided by the gameroom as the gsurl field.
Sit at Game
POST to gameserverRESPONSEaction=sit tid=[temporary authentication id that was provided by the gameroom] grid=[gameroom id, of the gameroom that provided the tid]sid=[game server session id, to be passed in future requests] side=[w or b; side from which the game is being viewed] role=[w, b or v; our role in the game, w or b player or viewer] error=[if there was a problem, this contains the error message which can be displayed to the user]Get Game State
POST to gameserverRESPONSEaction=gamestate sid=[gameserver session id] wait=[1 if we are waiting for the next change; 0 otherwise] lastchange=[previous value of lastchange that was given or 0 if first request; not needed if wait=0] maxwait=[maximum number of seconds to wait; optional, default 60]Note that the HTTP server may close the connection while you are waiting for a response. Thus it is possible that you could get no data at all in the response. Your client should try connecting again and waiting for the data when this happens. However, the client should be careful not to hit the server with too many requests or go into an infinite loop in case the connection is being closed very quickly every time due to various possible conditions such as: the server being offline, the HTTP deamon not responding, the server reporting an error on every request, ect.error=[if there was a problem, this contains the error message which can be displayed to the user] auth=[auth code to be sent with requests which change the game state; such as a move] lastchange=[value to be passed back in next gamestate request if waiting] role=[our role in the game; w=white player; b=black player; v=viewer] moves=[list of all moves made in the game using the Arimaa game notation] chat=[chat messages exchanged between the players; oldest first] moveslength=[length of 'moves' string; used when getting updates] chatlength=[length of 'chat' string; used when getting updates] position=[position diagram; see the Notation for Recording Games] title=[the title of the table for displaying to users] wplayer=[username of the white (gold) player; may contain * and spaces] bplayer=[username of the black (silver) player; may contain * and spaces] timecontrol=[Arimaa time control string; see Match Rules for specs] rated=[1 if it a rated game; 0 otherwise] postal=[1 if it a postal game; 0 otherwise] movenum=[the current move; like 10w] turn=[which players turn it is (w or b)] plycount=[the current move number (1 if 1w or 1b; 2 if 2w or 2b)] tcmove=[number of seconds per move set in the timecontrol; M parameter] tcreserve=[number of seconds set for the reserve in the timecontrol; R parameter] tcpercent=[the percent of time per move to add to the reserver; P parameter] tcmax=[number of seconds set for maximum reserve in the timecontrol; L parameter] tctotal=[the total time for the game; G parameter when G is specifed as a time] tcturns=[the total turns for the game; G parameter when G is specifed as turns] tcturntime=[max time per turn; T parameter] tcwreserve=[the number of seconds left for white reserve time] tcbreserve=[the number of seconds left for black reserve time] tcgame=[number of seconds since start of game to start of last move] tcgamenow=[number of seconds since start of game to now] lastmoveused=[number of seconds used in the last move] lastmovereserve=[number of seconds left in reserve after last move] createtime=[unix timestamp of when the game began] wpresent=[timestamp of when the white player joined; 0 if not present] bpresent=[timestamp of when the black player joined; 0 if not present] timeonserver=[timestamp of the current time on the server] takeback=[something like "b 10w" if the black player is requesting a takeback when the current move is 10w] wstartmove=[timestamp when w player started the move] bstartmove=[timestamp when b player started the move] starttime=[timestamp when the game was started]Note there may be additional fields in the response, but do not use them unless they are added to the protocol specs.Update Game State
POST to gameserverRESPONSEaction=updategamestate sid=[gameserver session id] wait=[1 if we are waiting for the next change; 0 otherwise] lastchange=[previous value of lastchange that was given or 0 if first request; not needed if wait=0] maxwait=[maximum number of seconds to wait; optional, default 60] moveslength=[the value given in the last 'gamestate' or 'updategamestate' request] chatlength=[the value given in the last 'gamestate' or 'updategamestate' request]Same fields as for 'Get Game State', but the moves and chat fields only contain updates. The client can concatenate these fields to the previous values obtained with 'Get Game State'. Also note that the moveslength and chatlength fields are not the length of the coresponding fields in the response, but as they are on the server. These fields should be sent to server in the next 'Update Game State' request.Start the Game
POST to gameserverRESPONSEaction=startgame sid=[gameserver session id] auth=[auth given in the gamestate request]error=[if there was a problem, this contains the error message which can be displayed to the user] ok=[1 if started sucessfully]Send a Move
POST to gameserverRESPONSEaction=move sid=[gameserver session id] auth=[auth given in the gamestate request] move=[Arimaa notation for the move (without move number); see Notation for Recording Games]error=[if there was a problem, this contains the error message which can be displayed to the user] ok=[1 if started sucessfully]Resign Game
POST to gameserverRESPONSEaction=resign sid=[gameserver session id] auth=[auth given in the gamestate request]error=[if there was a problem, this contains the error message which can be displayed to the user] ok=[1 if resigned sucessfully]Request Takeback
POST to gameserverRESPONSEaction=takeback sid=[gameserver session id] auth=[auth given in the gamestate request] takeback=reqNote that for rated games takeback requests are ignored by the server.error=[if there was a problem, this contains the error message which can be displayed to the user] ok=[1 if request submitted sucessfully]Reply to Takeback Request
POST to gameserverRESPONSEaction=takebackreply sid=[gameserver session id] auth=[auth given in the gamestate request] takebackreply=[yes if takeback request was granted; no otherwise]error=[if there was a problem, this contains the error message which can be displayed to the user] ok=[1 if reply submitted sucessfully]Send Chat
POST to gameserverRESPONSEaction=chat sid=[gameserver session id] auth=[auth given in the gamestate request] chat=[chat message text]error=[if there was a problem, this contains the error message which can be displayed to the user] ok=[1 if chat submitted sucessfully]Leave Game
POST to gameserverRESPONSEaction=leave sid=[gameserver session id] auth=[auth given in the gamestate request]Note that leaving a game does not cause it to be removed from the gameserver (even if both players leave). A player can sit down again at a later time.error=[if there was a problem, this contains the error message which can be displayed to the user] ok=[1 if leave processed sucessfully]