When a
game ends, the
referee creates a
game record, an information structure containing a summary of the game and its outcome. Unless the
table has been
configured not to do so, the referee then sends this record to the
bookkeeper, which stores it permanently, updating the different
players'
ELO scores for the game's
ruleset.
Game record structure
A game record takes the shape of an XML-RPC struct, and contains the following keys:
Required values
- end_time
- The time at which this game ended, expressed in one of the [W3 standard date and time formats], e.g. 2006-07-16T19:20:30+01:00
- seats
- An RPC struct describing this game's seats. Each member represents one seat: the key is its ID, and the value is an array of all the JIDs of the players in that seat.
- winners
- This game's winners list, an array ranking the seats in winning order, with each place-slots represented by a sub-array. Note that if the optional
finished flag (see below) is set to false, then the order of this list, while still recorded, has no effect on players' rankings (since the game didn't finish naturally).
- game_uri
- The URI of this game's ruleset.
- parlor
- The bare JID of the referee's parlor.
Optional values
- start_time
- The time at which this game began, expressed in one of the [W3 standard date and time formats], e.g. 2005-07-16T19:20:30+01:00
- notes
- A string, which can contain anything the referee cares to put here.
- finished
- A boolean that signals whether the game came to a natural conclusion (true), or if the referee ended it early due to user departure (false). If this value is not provided on an incoming record, then the bookkeeper will mark it as true. Therefore, when creating new records, it's perfectly OK to only define this (and define it as false) when a game ends abnormally.
- history
- An arbitrary data object (within the scope of Jabber-RPC data types -- most likely a struct or array) which represents the history of the game. The content of this field is game-specific; it is generated by the referee, and interpreted by game-specific UI code.
Maybe also have a history-URI and history-URI-version? It is not necessarily true that the format of the history record is tied to the ruleset by which the game was played. I.e., several chess rulesets could share a standard game record format. Or the ruleset of a game could evolve in a way that doesn't affect the game record. Or vice versa.
Record sizes
The bookkeeper can (and probably should) set a limit on the size of incoming game records.
Except that the history field will, in general, be unboundedly large.
Implementation notes
The format of game records is general enough that only referee implementations need worry about them. In other words, individual game modules needn't worry about these records in their own code. As long as the modules can correctly identify their own ruleset, and generate a winners list in the proper format, the game's referee will do the right thing.