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).
Three additional, predefined calls bracket the recovery calls:
volity.receive_state
to the client.
volity.game_has_started
call.
volity.state_sent
on the client.
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.
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.