State Recovery

Through game state recovery, a player can ask a referee for a summary of a game's current state.

To request recovery, the player's client sends a volity.send_state RPC request to the referee. If it judges that the player is qualified to receive such information (usually any player at the table qualifies), the referee reacts by calling some number of RPC requests back on the client. In total, the requests should give the receiving client enough information to build an accurate representation of the game's state from that player's perspective.

The RPC sequence will begin with seating information: volity.seat_list, possibly volity.required_seat_list. There may then be some number of volity.player_sat RPCs, followed by some number of volity.player_ready RPCs, to convey the current seating/readiness arrangement. (The player_ready RPCs, if present, will be the last volity-namespace calls in the sequence.)

The sequence then continues with a description of the game configuration, and (if the game has already started) a description of the game's state. There's nothing special about these requests; each one is an ordinary game-namespaced request defined in the table's current ruleset API.

For example, in a game of Chess, a recovery request would result in the client receiving RPC requests letting it know the positions of all the pieces on the board. In a Poker game, the client would be told about the size of the pot, how many chips each player held, and its own hand, and its opponents' hand sizes (but not the specific cards they hold; presumably, no methods would exist in the ruleset API to support that, anyway).

Sending state

Three additional, predefined calls bracket the recovery calls:

The typical use-case for a graphical client has it disabling its own automatic display refresh of the gameplay area once it receives the first call, and the reenabling it (with an additional redraw of that area) upon receipt of the second call.

It's worth noting that a client can request state at any time -- not just at the beginning of the game. This can be very useful for players who wander in after some table configuration has already started to take place and need to know the current pregame settings, or for players who come in midgame simply to observe the play.

The sending of the initial state

When a client first joins the table, the referee will treat it as an ordinary Jabber MUC client; the referee will not send state RPCs (or any other RPCs) to the client.

As soon as the client is able, it should send volity.send_state to the referee. This tells the referee that the client is in fact a Volity-capable client, and ready to receive RPCs. After the receive_state / state_sent sequence, the referee will continue to update the client (via RPCs) as the game state continues to change.