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.


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 a table state requiring a shot for specified agent.

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

Returns: Structure with the following fields:

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


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.


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.


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


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


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

Debugging methods


Returns similar to getgame but requires no arguments.


Returns similar to execshot but requires no arguments.


Returns a string representation of the concatenation of its arguments