Table Configuration

Configuration allows players seated at a table to specify certain attributes and behaviors for it. These come in two basic types: table configuration, which defines some attributes common to all tables and defined by the core Volity protocol, and game configuration, which sets up rules and other features specific to the table's ruleset.

In either case, players perform configuration by sending certain Jabber-RPC requests to the table's referee. Conversely, players are informed about changes to a table's configuration through RPC requests sent from the same referee.

Table configuration

All volity tables have several attributes that are always configurable, regardless of their loaded ruleset. Players can configure these attributes using certain RPC requests in the core volity namespace. At present, the protocol defines the following configuration requests:

volity.show_table( true | false )

Defines whether or not the table is visible through the game browser.

volity.record_games( true | false )

Defines whether or not game records are sent to the bookkeeper.

volity.set_language(language code)

Defines the preferred language to be used at the table. The argument is a two-letter language code.

volity.set_timeout(seconds)

Defines the length of this table's timeout. The argument is a positive integer.

volity.set_timeout_reaction(reaction-type)

Defines what the referee will do upon a user departure timeout. The argument is a string, one of "throw", "suspend" or "bot".

Game configuration

Rulesets are free to define any sort of configuration functions in their ruleset APIs as they see fit. However, a ruleset should be carefully specific about which functions are meant for configuration, and which are intended to be called once a game is underway.

These functions operate like any other game-specific RPC request, existing within the game namespace.

As an example, see the best_of and no_ties functions in the rock, paper, scissors API.

A referee can implement as many or as few of a ruleset's configuration methods as it wishes. (Should we define some sort of disco-based query pattern for asking a server what sorts of config it supports?) (Would be easier to just allow server config variables, which the game module reads. This puts more work on the game designer -- he has to write code to constrain his own config system -- but it avoids issues with possibly inconsistent configurations.)

The effect of reconfiguation

When a player succeeds in changing any part of a table's configuration, several things happen.

• All players who have declared readiness get knocked back to an unready state. After all, the nature of the game has changed away from the format they had agreed upon.

• The referee sends a RPC request to every player, informing it of the configuration change. Generally, the call contains two arguments: the JID of the player who made the request, and the new value. The RPC requests page defines several of these (such as volity.language( JID, language), and rulesets can define as many more as they need.

• If the reconfiguration affected the game's rules, then the table's full ruleset URI changes appropriately. Its base part remains the same, but its query string adjusts itself to reflect the new rule change.

• If the reconfiguration used one of the volity.* calls, then the referee adjusts how it responds to disco? queries, as defined by the game finder page.