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
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:
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").
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.
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