There are six states that a game
referee can be in. Seven, if you count "destroyed". (A destroyed referee no longer exists, so it does not answer requests.)
- setup
- The initial state (after volity.new_table creates the referee). Also the state we return to after the game ends. Players can change the game configuration; players can sit and stand. During this state, the seat list may change. (Once the game leaves setup, the seat list is fixed.)
- authorizing
- The referee is waiting for permission to begin the game. (See payment protocol.)
- active
- Game in progress.
- disrupted
- Some people have disconnected from the game (but it is still in progress). To be more specific: at least one non-eliminated seat is entirely empty (neither humans nor robots left).
- abandoned
- All seated human players have disconnected from the game. It is still "in progress", but nothing can happen until the referee suspends it.
- suspended
- Someone has called for a pause in the game. The game configuration is locked, but players can sit and stand.
- (destroyed)
- The table and the referee have shut down, permanently.
Note that a bot in a seat prevents disrupted, but not abandoned. (A game can continue normally with a human playing a robot; but if only robots are left seated, the game is abandoned.) Also pedants may note that if the conditions for disrupted and abandoned both occur, the table counts as abandoned.
RPCs that indicate state transitions
A client can track the referee state by watching for the following RPC requests:
- start_game()
- now in active.
- suspend_game()
- now in suspended.
- resume_game()
- now in active.
- end_game()
- now in setup.
- game_activity(state)
- now in the given state, which will be active, disrupted, or abandoned.
- game_validation(state)
- now in the given state, which will be authorizing, setup, or suspended.
- receive_state(struct)
- now in the state given by the struct's state field. May be any of the six states. (Only occurs during state recovery.)
Note that it is technically possible for players to leave or rejoin the table during the authorizing state. A successful validation is still marked by start_game() or resume_game(), but that call may immediately be followed by game_activity() to indicate a disrupted or abandoned state.
State transition table
In my previous job, I wrote a lot of state transition tables. This one is actually kind of useful.
Timer intervals are suggested values, not required. Implementations may vary.
- From setup...
-
- to authorizing
- all seated players are ready
- to active
- (not possible)
- to suspended
- (not possible)
- to disrupted
- (not possible)
- to abandoned
- (not possible)
- to (destroyed)
- all human players (including observers) disconnect; then interval elapses (90 seconds)
- From authorizing...
-
- to setup
- not all players permitted to play (previous state was setup)
- to active
- all players permitted
- to suspended
- not all players permitted to play (previous state was suspended)
- to disrupted
- (not possible)
- to abandoned
- (not possible)
- to (destroyed)
- (not possible)
- From active...
-
- to setup
- game reaches end
- to authorizing
- (not possible)
- to suspended
- a seated player sends volity.suspend_game()
- to disrupted
- a seated player (in a non-eliminated seat) leaves, leaving the seat becomes entirely empty
- to abandoned
- a seated player leaves, leaving no seated human players in the game
- to (destroyed)
- (not possible)
- From suspended...
-
- to setup
- all seated players are ready, with kill_game flag set
- to authorizing
- all seated players are ready, with kill_game flag unset and no empty seats
- to active
- (not possible)
- to disrupted
- (not possible)
- to abandoned
- (not possible)
- to (destroyed)
- all human players (including observers) disconnect; then interval elapses (90 seconds)
- From disrupted...
-
- to setup
- game reaches end (could happen if the empty seat had no moves left)
- to authorizing
- (not possible)
- to active
- a player returns to his seat (and now there are no empty seats)
- to suspended
- a seated player sends volity.suspend_game()
- to abandoned
- a seated player leaves, leaving no seated human players in the game
- to (destroyed)
- (not possible)
- From abandoned...
-
- to setup
- (not possible)
- to authorizing
- (not possible)
- to active
- a player returns to his seat (and now there are no empty seats)
- to suspended
- table abandonment timer elapses (3 minutes)
- to disrupted
- a player returns to his seat (but there are still empty seats)
- to (destroyed)
- (not possible)