Bookkeeper

The bookkeeper is the information center of a Volity network. It serves the following purposes:

The bookkeeper at volity.net

The official Volity network, VolityNet, runs a bookkeeper of its own. As the nerve center of the largest free Volity network, it quite commonly used and information-rich, and sometimes refereed to as "the bookkeeper", as if it were the only one in existence, even though anyone can technically run a separate bookkeeper of their own. It is maintained by the Volity core development team, as a free service to the community.

Most Volity players and servers will probably only use this one bookkeeper, and clients should connect to it by default.

The JabberID of VolityNet's bookkeeper is: 

 bookkeeper@volity.net/volity

RPC Requests

Right now, all the "reputation_system.html" class=wikipagelink>reputation system. In the arguments, identifier means either a JID (for players or parlors) or a URL (for UI files).

volity.get_reputation ( identifier )

Requests the total reputation score of the object with the given identifier. The return value is an integer representing this score.

volity.get_stance ( identifier, player-JID )

Requests the stance that the player with the given JID holds towards the identified object. Returns a fault if no such stance exists. Otherwise, returns an array of the format [stance, reason], where stance is one of (-1, 0, 1) and reason is a (possibly empty) text string.

volity.get_stances ( identifier )

Requests all the stances recorded for the identified object. Returns an array, each member of which is an array of the format [player-JID, stance, reason] (see previous definition).

volity.set_stance ( identifier, stance, reason )

A request to set the sending player's stance towards the identified object. Returns a fault if the provided stance is any value other than one of (-1, 0, 1), or if the sender hasn't played a game with the identified object (or, indeed, if the object appears to be the sending player). Otherwise, the bookkeeper updates its reputation database and returns truth.

volity.record_game ( game record )

Record the outcome of a game. The argument is a struct which contains the winners list, the timestamp of the game, and so on. See game record for the complete definition.

This RPC may be sent only by referees.

volity.get_rulesets ( )

Request a list of all the ruleset URIs that the bookkeeper knows about. (Not scalable; we may change this.)

This appears not to work, as of 2007-03-17; use a disco#items query instead. Although I can't be totally sure I'm not calling it wrong. -- Dankna?

volity.get_ruleset_info ( URI )

Request information about the ruleset with the given ruleset URI. The result is a struct; see the bookkeeper service discovery page for the fields this will contain.

volity.get_uis ( URI )

Request a list of UIs which require the given ruleset URI. (Ruleset may include a version number fragment, in which case the UIs must match that version number.) The result is a list of URLs (a list of strings).

volity.get_uis ( URI, constraints )

Same as above, but the additional constraints parameter allows the bookkeeper to filter the results. The constraints are a struct containing any or all of the following keys:

client-type
only return UIs matching this client type URI.
ruleset-version
only return UIs matching this ruleset version number. (Used if the ruleset parameter does not contain a version number fragment.)
ecmascript-api
only return UIs which match this version number. (See the "volity_metadata_terms.html" class=wikipagelink>UI metadata.)
language
only return UIs which include this language.
reputation
only return UIs with this reputation or better.

Constraint list is subject to change.

If the constraints struct contains several keys, the UI must match all of them. If the struct is empty, the bookkeeper returns all the UIs for the ruleset (same as the one-argument form of the RPC).

volity.get_ui_info ( URL )

Request information about the UI with the given URL. The result is a struct; see the bookkeeper service discovery page for the fields this will contain.

volity.get_ui_info ( list )

Batch form of get_ui_info(). The argument is a list of URLs; the result is a list of structs.

volity.get_parlors ( URI )

Returns a list of JID pointers to parlors that support the given ruleset.

volity.get_factories ( URI )

Returns a list of JID pointers to bot factories that support the given ruleset.

volity.get_lobbies ( URI )

Returns a list of JID pointers to chat lobbies for the given ruleset.

volity.get_resource_uris ( )

Request a list of all the resource URIs that the bookkeeper knows about. (Not scalable; we may change this.)

volity.get_resources ( URI )

Request a list of resources which provide the given resource URI. (Ruleset may include a version spec fragment, in which case the resource must match that spec.) The result is a list of URLs (a list of strings).

volity.get_resources ( URI, constraints )

Same as above, but with additional constraints:

resource-version
only return resources matching this ruleset version spec. (Used if the ruleset parameter does not contain a version spec fragment.)
language
only return resources which include this language.
reputation
only return resources with this reputation or better.

Constraint list is subject to change.

volity.get_resource_info ( URL )

Request information about the resource at the given URL. The result is a struct:

volity.get_resource_info ( list )

Batch form of get_resource_info(). The argument is a list of URLs; the result is a list of structs.

Service Discovery responses

The bookkeeper holds a complex disco-response structure, organized by nodes.

Info

If queried without a node, the bookkeeper returns its own identity: category "volity" and type "bookkeeper". It also returns a one-entry form describing its role:

volity-role
The string bookkeeper.

If the requested node appears to be a URI, the bookkeeper matches it against known ruleset URIs and UI file URLs to generate an appropriate response form.

Node: [some UI file's URL]

client-type
The client type URIs that this file supports. Can be multiple values.
languages
The two-letter codes for the languages this file supports. Can be multiple values.
ruleset
The ruleset URI that this file supports.
reputation
This file's ranking on the reputation system. As always, the higher the number, the more players have used and liked it.
contact-email
The email address of the person responsible for this file.
contact-jid
The JabberID of the person responsible for this file.
description
A text description of this file. (A shorter name of the file can be found in the "name" attribute of the info response.)

Node: [some ruleset URI]

description
A prose description of the given ruleset URI.

The attached JEP-0128 form contains the following additional fields:

server
The JID of this referee's parlor.
table
The JID of this referee's table.
afoot
1 if the game is in play (and therefore probably not joinable), 0 otherwise.
players
The number of occupied seats at the table.
max-players
How many seats this referee will allow.
language
The preferred human language for this table.

Items

This is also entirely node-driven; the bookkeeper returns an empty list on disco-items requests that include no nodes.

Node: rulesets

Returns a list of JID/node combinations, each pointing at a node with more information about a ruleset. The JID is always the bookkeeper's own JID, and the node is a ruleset URI.

Node: [some ruleset URI]|parlors

Returns a list of JID pointers to parlors that support the given ruleset.

Node: [some ruleset URI]|uis

Returns a list of JID/node combinations, each pointing at a node with more information about a UI file. The JID is always the bookkeeper's own JID, and the node is a UI file's URL.

Node: [some ruleset URI]|lobby

Returns a list of JID pointers to chat lobbies for the given ruleset.