A client should have a Volity role of player.
Clients must implement the following predefined requests, which always come from a referee.
The various requests having to do with table configuration specifically deal with the case of a player modifying those settings on a table, which is why the first argument to all of them is some player's JID. A client can use disco at any time to learn a table's current configuration settings.
Note: Most of these volity.* requests (as marked) imply that all players become unready. The referee will not send actual volity.player_unready RPCs; the client must consider the players unready when the volity.* request is received.
A notification that a game has begun at a table at which the receiver is seater.
(All players become unready.)
A notification that a game that the receiver was playing in just ended.
(All players become unready.)
The referee has suspended the game. (See the next method for the player-thrown version.)
(All players become unready.)
The player with the given JID has suspended the game. (JID may also be the referee, in the case of an abandoned game.)
(All players become unready.)
The game has been resumed (after suspension).
(All players become unready.)
The referee is about to begin sending a lot of configuration RPCs (mostly game-specific ones, but also seating information and so on). The blast of configuration will be closed with a volity.state_sent() RPC. This generally occurs when the player joins a table, but may also be the result of a volity.send_state request. See state recovery.
The struct argument provides yet more information. At the moment, this is just one field:
The referee has finished sending configuration information, and is about to begin sending game state. This only occurs during state recovery, and only if a game is in progress.
The referee has moved to the given state, which will be one of the strings active, disrupted, abandoned. (The other states, setup and suspended, are signalled by other RPCs.)
This call is only used when moving from one of those three states. (When leaving setup or suspended, the referee always goes to active, so no volity.game_activity() call is necessary.)
The referee has finished sending configuration information and game state. This concludes a state recovery burst, which started with volity.receive_state().
The player with the given JID has either proposed that the game be killed upon resumption of play (if the second argument is true), or that the game resume normally (if it's false). This is only legal when the game is suspended.
(All players become unready.)
The player with the given JID has changed the table's visibility in the the game browser. (See also table configuration.)
(All players become unready.)
The player with the given JID has that the table will send game records to the bookkeeper at the end of each game (if the argument is true) or not (if the argument is false). (See also table configuration.)
(All players become unready.)
The player with the given JID changed the table's preferred language. The argument is a two-letter language code.
(All players become unready.)
The player with the given JID has indicated that it is ready to play, agreeing with the present table configuration.
The player with the given JID has indicated that it is not ready to play. It's likely that the table configuration changed somehow, and the referee called this not just on this player but every ready player at the table, but it could be that this player is individially changing its mind about its own readiness.
The player with the given JID has indicated that it no longer wishes to play, and instead simply observe. This is also sent when a seated player disconnects from the table.
(All players become unready.)
The player with the given JID wishes the play the game, and has sat in the seat with the given ID. This is also sent when an absent player reconnects to a game in progress, and therefore returns to the seat which belongs to him.
(All players, including this one, become unready.)
The given array represents the IDs of all the seats that the referee might ever refer to over the lifetime of the table.
Usually called on a player only as it joins the table.
The given array represents the IDs of all the seats that must be occupied before the game can start. This is useful for games where seats have roles pertinent to the ruleset, such as (black, white) in chess, or (north, south, east, west) in Bridge. Referees of rulesets with no such role-driven seats may elect to not bother with this request.
The array must be a subset of the array provided with a preceding volity.seat_list request.
Usually called on a player only as it joins the table.
A player at some table is inviting you to join it. The contents of the struct are described on the invitation page.
Note that this RPC is sent by the table's referee, not by a player. It is the only RPC which the client will receive from a referee of a table you have not joined.
The referee is sending a symbolic message, which should be localized and displayed in the client's message stream. The list is a nonempty array of tokens, as described in RPC replies. It may not begin with volity.ok; any other token in any namespace is legitimate.
Note: Not yet implemented.
Request information about the client. The result is a struct with fields and values identical to the result of a disco info query.
Note that all the above RPC requests lie in the volity namespace, marking them as systemwide methods. Another Volity RPC namespace, game, serves as the container for game-specific requests; that is, requests defined by a certain ruleset.
game.* RPCs never implicitly cause players to become unready. If the game configuration changes, the referee will send out a burst of volity.player_unready RPCs.