Pool XMLRPC API documentation

The pool competition and physics server includes a web service API based on XML-RPC. This API document assumes the user is familiar with XML-RPC, and proceeds to list the supported methods.

The XML-RPC endpoint for all methods is api.pl in the directory where the web interface (and this document) is installed

Agent API

These methods allow agents to request tasks and submit shots. The supplied client will use these methods to communicate with the server.

register_agent

Submit agent to server and get ID.

Parameters: Agent Name (string), Configuration file name (string), Agent password (string), Agent Owner ID (integer).

Returns: Agent ID (integer)

This function allows an agent to register with the server and know its agent ID. If a matching agent does not exist, a new one will be created under the ownership of the specified owner (use 0 for no owner).

If the agent does exist but the password is incorrect "Bad Password" will be returned.

get_shot

Get a table state requiring a shot for specified agent.

Parameters: Agent ID (integer), Agent Password (string)

Returns: Structure with the following fields:

shot_available
(boolean) True iff a new game state requiring a shot is available. This shot is now assigned to the client.
gameid
(integer) Identifier of the game for which the shot is required. Should be sent back to the server with the shot parameters.
stateid
(integer) Identifier of the game state for which the shot is required. Should be sent back to the server with the shot parameters.
state_info
(string) Full information about the current game and table state, encoded appropriately for GameState::Factory.
noise_info
(string) Full information about the noise to be added, encoded appropriately for Noise::Factory.

submit_shot

Submit shot for a previously assigned game state to the server.

Parameters: Game ID (integer), Agent ID (integer), Password (string), State ID (integer), a,b,theta,phi,v,cue_x,cue_y (double), Called Ball (integer), Called Pocket (integer), Decision (integer), Time spent in seconds (double).

Returns: true (boolean) if the shot was submitted successfully, and an error string otherwise.

The server will process the shot. No indication of success or failure of the shot itself is returned to the client. If the client has kept its turn, it may, but not always, get the next state in the game using a subsequent call to get_shot. Game history is currently not directly available The "Time spent" parameter is ignored unless the server is set to trust the clients' time usage (in case of "fake time").

Database access API

These methods allow clients to access the database and physics library. Most methods require user authentication via cookies or by appending ?username=USER&password=PASS to the script URL.

getgame

Returns a detailed log of a game including XML encoded states and shots.

Parameters: Game ID (string) -- this could begin with G to mark a game, S to mark a shot, or L to mark uploaded logfile.

Returns: Array of shot structures with detailed information about table state and shot.

coltitle

Returns a string representing the title for a column in the database by column name

coltext

Given a column name and value from that column, returns human-readable text for that value.

execshot

Given a table state and shot parameters, returns the event list from executing that shot. Used by the JavaScript game viewer.

Debugging methods

gettestgame

Returns similar to getgame but requires no arguments.

testshot

Returns similar to execshot but requires no arguments.

dump

Returns a string representation of the concatenation of its arguments