Definition of the Smart Game Format

Visit red-bean.com for the Latest definitions

From the Dissertation of Anders Kierulf
"Smart Game Board: a Workbench for Game-Playing Programs, with Go and Othello as Case Studies"

A standard file format to exchange machine-readable games, problems, and opening libraries would save time and work. That goal may not be too far away. A standard for exchanging collections of Othello games is being worked out by Erik Jensen, Emmanuel Lazard, and Brian Rose in collaboration with the author. For Go, a new standard has recently been proposed [Connelley 89, High 89]; it seems to suffer from a wealth of features, but any standard for exchanging Go games is welcome, and will be supported by the Smart Game Board.

The current file format is specialized for the needs of the Smart Game Board. It is based on an earlier proposal for a standard for Go games [Kierulf 87b] which was not widely adopted. The following description is not a new proposal; it is intended for those who want to read or white files that are compatible with the Smart Game Board.

The game collections (documents) of the Smart Game Board are stored as text files. This has the advantage that files can be manipulated with standard text utilities, and that it's easier to exchange games by electronic mail. The disadvantage is that text files are less compact than binary files.

The Smart Game Board stores the game trees of each document, with all their nodes and properties, and nothing more. Thus the file format reflects the regular internal structure of a tree of property lists. There are no exceptions; if a game needs to store some information on file with the document, a (game-specific) property must be defined for that purpose.

I will first define the syntax of the game collections, then discuss syntax and semantic of various properties.

Game Collections

A collection of games is simply the concatenation of the game trees. The structure of each tree is indicated by parentheses. A tree is written as "(" followed by a sequence of nodes (as long as the tree is unbranched) and a tree for each son, and terminated by ")". Each node is preceded by a separator, and contains a list of zero or more properties.

Thus the main branch of the game is stored first in the file, and programs can easily read that part (until the first closing parenthesis) and ignore the rest.

The conventions of EBNF are discussed in [Wirth 85]. A quick summary:

"..." : terminal symbols
[...] : option: occurs at most once
{...} : repetition: any number of times, including zero
(...) : grouping
  |   : exclusive-or

The overall definition of the file format is as follows:

        Collection      = {GameTree}.
        GameTree        = "(" Sequence {GameTree} ")".
        Sequence        = Node {Node}.
        Node            = ";" {Property}

Any text before the first opening parenthesis is reserved for future extensions and is ignored when reading a file. Spaces, tabs, line breaks and so on can be inserted anywhere between properties and are also ignored.

Game-Independent Properties

Each property is identified by one or two capital letters. The property value is enclosed in brackets; lists of points or integers are written as a sequence of property values. Within text, a closing bracket is prefixed by a backslash, and a backslash is doubled. Moves and points are game-specific and are defined later.

        Property        = PropIdent PropValue {PropValue}.
        PropIdent       = UpperCase [UpperCase | Digit].
        PropValue       = "[" [Number | Text | Real | Triple
                                  | Color | Move | Point | ... ] "]"
        Number          = ["+" | "-"] Digit {Digit}.
        Text            = { any character; "\]" = "]", "\\" = "\"}.
        Real            = { Number ["." {Digit}].
        Triple          = ("1" | "2").
        Color           = ("B" | "W").

Move and Point are game-specific and are described later. The following properties are understood by all games. The property type is given in brackets.

        "B" : Black move                [move, game-specific]
        "W" : White move                [move, game-specific]
        "C" : Comment                   [Text]
        "N" : Node Name                 [Text]

The purpose of providing both a node name and a comment is to have a short identifier like "doesn't work" or "Dia. 15" that can be displayed directly with the properties of the node, even if the comment is turned off or shown in a separate window. There is no limit to the length of texts; programs must be able to ignore the rest of texts that are too long for them to handle. Reasonable limits are 32 characters for node names and at least 2000 characters for comments.

        "V" : Node value                [number]

Positive values are good for Black, negative values are good for White. The interpretation of particular values is game-specific.

        "CH": Check mark                [triple]
        "GB": good for black            [triple]
        "GW": good for white            [triple]
        "TE": good move (tesuji)        [triple]
        "BM": bad move                  [triple]

The normal value for such properties is one, properties that are doubled for emphasis have the value two.

        "BL": time left for Black       [real]
        "WL": time left for White       [real]

All times are given in seconds, or fractions thereof {Hale: these can be negative, indicating player is playing past time limit set}.

        "FG": figure                    [none]

The figure property is used to divide a game into different figures for printing: a new figure starts at the node with a figure property.

        "AB": add black stones          [point list, game specific]
        "AW": add white stones          [point list, game specific]
        "AE": add empty stones          [point list, game specific]
        "PL": player to play first      [color]

The above properties are used to set up positions in games with only black and white stones. The following properties are all part of the game info:

        "GN": game name                 [text]
        "GC": game comment              [text]
        "EV": event (tournament)        [text]
        "RO": round                     [text]
        "DT": date                      [text]
        "PC": place                     [text]
        "PB": black player name         [text]
        "PW": white player name         [text]
        "RE": result, outcome           [text]
        "US": user (who entered game)   [text]
        "TM": time limit per player     [text]
        "SO": source (book, journal...) [text]

The format in these game-info strings is free, but to be able to search for specific games in game collections, it is recommended to adhere to the following conventions:

        - Date is ISO-standard: "YYYY-MM-DD".
        - Result as "0" (zero) for a draw, "B+score" for a black win,
                and "W+score" for a white win, e.g. "B+2.5", "W+64"
        - Time limit as a number, in minutes.

In addition, names, events, and places should be spelled the same im all games.

The following properties may only be present at the root node:

        "GM": game [number] (Go=1, Othello=2, chess=3, Nine Mens Morris=5)
        "SZ": board size        [number]
        "VW": partial view      [point list, game-specific]
        "BS": black species     [number] (human=0, modem=-1, computer>0)
        "WS": white species     [number]

The game number helps the program reject games it cannot handle (this property was mandatory as long sa an application could play different games). The view gives two corner points of a rectangular subsection; an empty list denotes the whole board. The species denotes the kind of player (the source of the more input), with different version of computer algorithms denoted by positive numbers (default algorithm = 1).

Computer algorithms may add the following properties:

        "EL": evaluation of computer move       [number]
        "EX": expected next move                [move, game-specific]

Some games support markings on the board: selected points, triangles/crosses, or letters (a sequence of letters is shown on the points given in the list, starting with "A"):

        "SL": selected points                   [point list, game-specific]
        "M" : marked points                     [point list, game-specific]
        "L" : letters on points                 [point list, game-specific]

Go-Specific Properties

In my proposal for a standard [Kierul 87b], I intentionally broke with the tradition of labeling moves (and points) with letters "A"-"T" (excluding "i") and numbers 1-19. Two lowercase letters in the range "a"-"s" were used instead, for reasons of simplicity and compactness. This was criticized mainly because it was not human-readable, but as that is not an important feature of this file format, I continue to use that notation.

(Hale: diagram omitted)

The first letter designated the column (left to right), the second the row (top to bottom). The upper left part of the board is used for smaller boards, e.g. letters "a"-"m" for 13*13. (Column before row follows the principle "horizontal before vertical" used in x-y coordinate systems. The upper left corner as origin of the board corresponds to the way we read, and most modern computers use it as origin of the screen coordinates to simplify integration of text and graphics.) A pass move is written as "tt".

The board must be quadratic, no smaller than 2x2, and no larger than 19x19.

Additional game info properties are defined for Go:

        "BR": Black's rank              [text]
        "WR": White's rank              [text]
        "HA": handicap                  [number]
        "KM": komi                      [real]

Sets of board points can be marked as territory, as secure stones, or just as a region of the board (e.g. to designate eye space):

        "TB": Black's territory         [point list]
        "TW": White's territory         [point list]
        "SC": secure stones             [point list]
        "RG": region of the board       [point list]