Zetangole™ HTTP-based Protocol

This document describes the HTTP-based protocol for interacting with the Zetangole™ game server. The CGI script http://Zetangole™.com/cgi/z mediates all communication with the game server (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 DIST command
• Send the SYNC command
• Send the END command

The following section explains each of the above actions in more detail. All server responses will consist of plain-text (non-HTML) lines ending with "\n". A period on a line by itself will act as a sentinel indicating end of multi-line server responses. 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 CGI script, /cgi/z, accepts one optional and one mandatory parameter. The mandatory parameter, r, consists of a text string specifying the actual request. The optional parameter consists of an uploaded file and is only required when the mandatory parameter specifies the DIST command.


Game initialization

To initialize a new game, 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. Do not upload a file with this command. An uploaded file, if present, will be ignored. 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 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 and
(c) determine a set of target images for the game.


Getting a distance

To get the distance of a player's image to that of a target, the client must issue the DIST command to /cgi/z. The DIST command takes the form "DIST [GAME_ID] [r] [p] [c] [PATH]" along with a file-upload. The [r], [p] and [c] terms stand for the round number, the player ] number and the snapper's player number. All player numbers are indexed starting from 1. [PATH] is the server's path name to one of the targets retrieved in the INIT step. The server will respond with OK [DIST] [ANGLE] in the case of a successful measurement. The client may choose to ignore the [ANGLE] and just use the [DIST] value. The server will respond with NOK [REASON] if for any reason a distance could not be measured, for example, the upload failed, or a face did not register in the uploaded file. The client 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.


Conforming to a playing order

In order to ensure consistency of log file entries, clients should strictly conform to the intuitive playing order. That is, distances should be requested for each round from 1 to the last round in strict sequence and within each round for each player from 1 to n in strict sequence. For example, "DIST [GAME_ID] 5 2 4" may follow "DIST [GAME_ID] 5 1 3" but not the other way around. (The former command asks for the distance of the image of player 2 in round 5, snapped by player 4. The latter command asks for the distance of the image of player 1 in round 5, snapped by player 3).


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.

Go back to Developers Connection