A Volity ruleset is the abstract definition of how a particular game is played, including both its rules and its specialized slice of communication protocol. Every parlor must support exactly one ruleset. This defines (for human players) the game that it lets people play, and (for clients) the Jabber-RPC requests that it will send and receive during play. A client prepares itself for a given ruleset by obtaining a UI file through the UI finder.

In Volity parlance, a game specifically refers to a single instantiation of a particular ruleset. To put it in object-oriented programming terms, a ruleset is to a game as a class is to an object.

Rulesets are sometimes called base rulesets to distinguish them from ruleset variants (see below).

Ruleset Attributes

Rulesets contain the following attributes:

• A globally unique ruleset URI, which allows other Volity entities to refer to this ruleset. Ideally, this URI also serves as a URL pointing to a Web page that defines the whole ruleset in human-readable terms; see rock, paper, scissors for an example.

• A standard set of rules, written in good old human-readable prose, describing how the game is played. A parlor claiming to support this ruleset must support all the rules, exactly as they are written.

• A ruleset API with two lists of Jabber-RPC requests that this ruleset defines.
  • Player-to-server requests, which can be requests to move pieces, play cards, or otherwise affect the game state, or requests for game-specific information. Table configuration requests go here as well.
  • Server-to-player requests, largely the server informing the players of changes in the game state or table configuration. They can be directed at a single player, some of them, or all of them, whichever is most appropriate.

• A list of game error codes that might result from illegal plays or malformed RPC requests to the referee, and what they mean. A game implementation must be able to handle all of these errors, displaying some appropriate message or other visual to the user for each one. Or possibly we want a fixed list of error codes -- see RPC replies.

• A list of table configuration options specific to the game, each of which in turn sports a couple of features:
  • A human-readable description of the option,
  • The key and allowed range of values used to represent this option in the query string part of the ruleset URI.

Example Rulesets

The following examples happen to have URIs pointing at webservers run by the Volity development team; this shouldn't imply that all rulesets must exist within the volity.org domain. Indeed, we expect to see URIs pointing at domains all over the world, once people start inventing their own. For now, though, the first rulesets will all look physically rather similar.

• http://volity.org/games/rps

• Crazy Eights: http://volity.org/games/eights

Where rulesets are used

Rulesets are used by other other components throughout the volity system. In every case, the other entity refers to the ruleset by its URI.

• Each parlor proclaims loyalty to exactly one base ruleset. The bookkeeper knows which servers correspond with which rulesets, visible through the game browser. Servers themselves may be queried about the rulesets they support through the UI finder.

• Every UI file supports exactly one ruleset.

• Every game record notes the URI of the ruleset that was used to play the game it describes.

• Each player on the Volity system has a separate ELO score for each ruleset that it has every played. This includes variants; playing regular Hearts affects one ELO score, while playing Hearts with the 10J and QS rule variant affects a different one, resulting in two distinct ELO scores attached to that player. Put another way, every ELO score has both a player and a ruleset attached to it.