This document describes the TCP-based protocol for interacting with the Zetangole™ game server.
The game server is a TCP daemon listening on port 5001 of Zetangole™.com (70.89.159.116).
The game client should strictly adhere to the protocol specified below.
Please do not abuse the server using your knowledge of this protocol. Help us to
provide users with an enjoyable playing experience. We will be glad to publish your
client through our website. However, your game-client must meet a minimum set of
standards and criteria that can be obtained by
registering as a
Zetangole™ client developer.
The Protocol
The client can only perform the following actions:
- Connect to the Zetangole™ server
- Send the INIT command
- Send the SET command
- Transfer a file via FTP to a prearranged destination
- Send the DIST command
- Send the END command
The following section explains each of the above actions in more detail. All server responses will
consist of lines ending with "\n". A period on a line by itself will act as a sentinel indicating
end of server response. The client can stop reading the socket on receipt of this sentinel. Below,
text in square brackets is variable. [n] usually stands for a number. In general, if the first word
in the server's response is
OK, that's a good sign. If the first word is instead an
NOK,
then that means an error of some kind occurred and usually a reason will be given.
The Connection Phase
Upon connection to port TCP port 5001 of the Zetangole™ primary server at Zetangole™.com, the client
should immediately read the "connection response" from the connected socket. The connection response
of the server may be
OK M000 Zetangole™ [n] which means that the connection has been accepted. [n]
will be a number indicating the total number of active games running on the server at this time.
Alternately, the response may be
NOK E001 [host1:port1 host2:port2 ...]. In this case, the client
must disconnect and successively try to connect instead to the servers in the suggested order. If
any of the named servers also responds with an
E001 message, the client must ignore the suggested
host list in favor of the originally suggested server list. The connection phase ends when a successful
connection has been established.
Game initialization
Once a connection has been established, a game may be initialized. To do this, the client may send the
string "INIT [passphrase] [player-1] [player-2] ..." where the portions in square brackets are to be
substituted by a valid passphrase and player names respectively. A unique passphrase is assigned to each
registered client developer along with a hostname to which he or she should try to connect during the
developmental phase. Up to 6 player names may be given to the INIT command after the passphrase. If the
client is already in the middle of a game, the server will respond with
NOK E002. Otherwise, if a game
was able to be successfully initialized, the server will respond as follows:
The client should save the GAME_ID, typically a 10 digit hexadecimal number. The path to each target
is the path name of an image file on the server. A URL to access the target image via http (for display
of that image in a html window) can be constructed by substituting the /var/www portion by
"http://Zetangole™.com". Thus, for example, "/var/www/zeta/images/testimage.jpg" can be viewed at
"http://Zetangole™.com/zeta/images/testimage.jpg". The target names can and usually do contain white space.
The client may assume that everything on the same line as the target path other than the path itself is
part of the target name. The client should save both, the set of paths and the corresponding set of names,
in its own internal structure and iterate through it in the specified order through the game. That is,
use target 1 for round 1, target 2 for round 2 and so on. If the players abandon the game before 10 rounds,
then any remaining targets will be unused.
A successful GAME_ID message from the server means that the server has been able to do the following:
(a) allocate resources to manage your game,
(b) determine unique locations on disk for the game archive
((c) determine a set of target images for the game and
(d) establish a location for transfer, via ftp, of image data during the game.
Setting the target
At the start of each round, the client is expected to set the target for that round.
This allows the server to precompute features from the target exactly once for all the
players in that round. A target may be set by issuing the command "SET [path/to/target]"
to the server, where the portion within square brackets is to be substituted by one of the
absolute pathnames retrieved from the server and stored by the client. The typical server
response to this is
OK. In case of an unexpected error a
NOK [Error-code] may be sent. But
if the game state allows it, and the target path is exactly one of the target paths sent by
the server, you may invariably expect an
OK here.
Transferring an image file
Assuming that a game has been properly initialized, the server would have pre-created a special
directory for incoming ftp transfers for the sole purpose of receiving data for this game only.
This directory can be reached at "ftp://ftp.Zetangole™.com/pub/zinc/[GAME_ID]", where the portion
in square brackets must be substituted by your GAME_ID. Image files must be transferred into this
directory via anonymous ftp using exactly the following convention: In Round i, the image of player j
captured by snapper k, must be named "ri-pj-ck.jpg". Needless to say the incoming image must also be
encoded in JPEG format. As an example, after a successful transfer of the image of player 4, snapped by
player 3, in round 2 of GAME with ID 043c09a15d, the file "ftp://ftp.Zetangole™.com/pub/zinc/043c09a15d/r2-p4-c3.jpg"
would exist. The client must use the FTP protocol and use any of a number of widely available client-side
FTP APIs (e.g. Microsoft WinInet, or Java FTPClient) to execute the transfer. Click here for
example code fragments.
Getting a distance
Assuming that an image has been transferred successfully as per the previous step, you are ready to obtain the distance
between it and the target. To get the distance, simply send the string "DIST r p c" to the server, where r is the round number,
p is the player number and c is the player number of the snapper. The server will respond either with
OK [DIST] where [DIST]
will be a floating point number indicating the distance in Hash Space miles from the image to the target. If the server failed
to register a face in the submitted image, or if there were other unexpected errors, the server will return an
NOK [Error-code].
You may assume a distance of 9999 miles in this case since Hash Space can be imagined to be a closed hypersphere of radius 9998 miles.
Viewing a game archive
The archive of a game is dynamically updated and can be viewed any time after a game has been initialized, at
"http://Zetangole™.com/cgi/a?i=[GAME_ID]". The client may construct this URL using the GAME_ID obtained in
the INIT step and provide it to the players.
Ending a game
When a game has ended, the client may send the "END" command to the server. This causes the server to mark the
game directory READ-ONLY and conclude the archiving for the game. A game that has not been marked as ended
will show up in the game archive as an incomplete game without final scores. The server response to an END
request is usually an
OK.
Message Codes
The complete list of message codes from the server along with their explanations can be found
here.
Go back to Developers Connection