1Standard: Portable Game Notation Specification and Implementation Guide 2(Supplement) 3Revised: 8 September 2001 4Status: Final draft 5Authors: Alan Cowderoy (Palamede), Ben Bulsink (DGT Projects), Andrew Templeton 6(Palamede/Palview), Eric Bentzen (Enpassant.dk, Palamede), Mathias Feist 7(Chessbase), Victor Zakharov (Chess Assistant). 8Contact: alan@cowderoy.com 9 101. Introduction 11 12PGNs combination of a formal specification for computer use with easy 13readability and manipulation by humans has firmly established it as the data 14format of choice for representing chess games. This is a major success and a 15tribute to the quality of the work done by the original authors. 16 17Steven Edwards, the author, appears unfortunately to be no longer involved with 18PGN and there is now no defined means of arbitrating and implementing proposed 19changes. There is also a huge body of software which implements the current 20standard and would break in various ways if it were changed. 21 22At the same time the increased use of DGT boards in major tournaments for the 23retransmission of live games has rendered one of the features that was planned 24for PGN but never implemented increasingly important, namely the possibility of 25encoding time information relating to each move. 26 27Without the possibility of encoding time information in PGN its usefulness in 28the retransmission of live games is significantly weakened forcing developpers 29either to resort to proprietary formats or to break the standard. 30 31Computer chess program authors are also now finding that they have no accepted 32way to encode such simple and recognised concepts as numeric position 33evaluations or search depth. 34 35Given this situation some have understandably set about defining wholly new XML 36based definitions for encoding chess games. While this work is interesting, as 37of today there is no widely accepted and supported XML schema. 38 39It thus seems important to us to attempt an incremental improvement to PGN 40intended to eliminate the functional weaknesses described above. 41 42This document proposes an extension to PGN designed to offer an immediate 'work 43around' solution to the problems outlined above. 44 452. Design aims 462.1 The enhancements must not break the existing standard. 47 48This rules out new syntactical elements. Steve Edwards himself proposed a format 49(BIF) that would have resolved these problems but it was never implemented and 50doing so now would break large quantities of software. 51 522.2 The enhancements should maintain the ease of use and legibility so 53characteristic of PGN. 54 55This rules out very precise but possibly more computer readable formats in 56favour of clearer human readable ones. 57 582.3 If new command structures are to be introduced they should be specified in 59such a way that they are usable for other extensions if needed. 60 61The intention here is to provide a generalised syntax that will enable other 62extensions rather than only solving one particular problem (time handling in our 63case). 64 653. Proposals 663.1 Introduction 67 68The only way to extend the syntax without breaking the standard is to embed the 69new command syntax into PGN comments. This is a kludge and such an obvious one 70that it was already suggested when Steve Edwards proposed the BIF format in 711996. It is still the only option available. 72 73Apart from a general command syntax we propose several specific commands 74designed for the handling of time information. 75 76We also propose the addition of a tag to the header to handle the state of the 77"running clock" where the game is being transmitted live and two other optional 78tags designed to handle special cases where the clock start times are needed. 79 80These additions are not problematic as the standard concedes the possibility of 81adding new tags to the header (outside the mandatory seven tag roster) 82 83Interpreting time information for a game is either difficult or impossible if 84the time controls in force are not known. PGN has a TimeControl tag for this and 85it should be regarded as mandatory when time information is to be embedded into 86the pgn. 87 883.2 A generalised format for embedding commands in comments. 893.2.1 Position 90An embedded command may occur at any position in a standard PGN comment, ie 91between { } . 92For example: 93{Optional leading comments [%clk 1:05:23] optional trailing comments} where 94[%clk 1:05:23] is the embedded command string. 95 963.2.2 Structure 97The command string is structured as follows. 98 99A leading tag of [% 100A command name consisting of one or more alphanumeric characters. 101A space character. 102Either a single parameter or a comma delimited list of parameter values. 103A closing tag of ] 104 105For example: 106[%clk 1:05:23] 107 1083.2.3 Opening delimiter 109The characters [% are redefined to indicate the start of a command sequence when 110found in between pgn comment tags. 111 112As all ASCII characters are legal in a comment string it is not possible to rely 113on any single character as an unambiguous opening delimiter. We have chosen to 114use [%. While this also could technicaly occur in some other context it seems 115highly unlikely. 116 1173.2.3 Commands 118 119Command names start immediately after the [%. 120They consist of one or more alphanumeric characters 121They are terminated by the first space character encountered. 122 123We are *not* proposing any fixed canonical list of commands. The idea is to 124describe a generalised command syntax, not to impose a particular set of 125commands. 126 127We *are* proposing a set of commands to deal with time handling. "clk" in the 128example above is the proposed command name for recording move times. See section 1294 for the detailed specification of this and other time related commands. 130 131In general software encountering an embedded command it does not understand 132should take no special action and pass the string through unchanged as part of 133the comment. 134 135For display purposes only presentation software, such as pgn readers, should by 136default strip out all commands before display in order to improve legibility. 137 1383.2.4 Parameters 139 140This parameter syntax is based on the epd opcode syntax described at 16.2.4 of 141the pgn spec. 142 143A command is followed by a single space and then either by a single operand or 144by a comma separated list of operands. 145 146An operand is either: 147i) a set containing any ascii characters except the comma and right hand square 148bracket 149or 150ii) a double quoted string containing a set of any ascii characters except the 151double quote. 152 153For instance: 154[%command 1:45:12,Nf6,"very interesting, but wrong"] 155 156This command has four operands, a time value, a san move value and a double 157quote delimitted string. Note that the quote delimitted string may contain 158commas. 159 160Commas are illegal in non quote delimitted strings because the comma serves as 161the operand list separator. 162 163Right hand square brackets are illegal in non quote delimitted strings because 164they terminate both the last operand and the command. 165 166We have thus departed from the epd opcode specification in two ways: 167i) The operand list is separated using a comma rather than a space. 168ii) Space characters are allowed in non quote delimited operands 169 170So it is possible to pass a full FEN string as an unquoted operand as in the 171example below. 172 173[%command "very tense start to the 174game",4r1k1/pp1b2r1/2n1pq1p/3p2pP/2pP2B1/P1P1Q3/2P2PPB/R4RK1 w - - 0 1,e4,d4] 175 176This command has four operands, the first is a double quote delimitted string, 177the second is a FEN, the third is e4 and the fourth is d4. 178 1793.2.5 Terminator 180The command is terminated by a single ] character. 181 1823.2.6 Multiple commands. 183A single comment tag may contain multiple embedded commands. 184For instance: 185{[%clk 0:00:07][%eval -6.05] White is toast} 186 1874. Time handling commands. 1884.1 Introduction. 189We propose the following commands for time handling The first is the command 190that DGT boards will be using to transmit times via pgn. 191 192The other commands are optional and cover times that can be derived from the 193clock time. They are technicaly redundant but may be usefull for highlighting 194aspects of the game and the players use of time. 195 196All these commands take one and only one parameter which is a time value in the 197format h:mm:ss (except for the mct command which requires hh:mm:ss) 198 199The comments containing the embedded commands are to be taken as referring to 200the move immediately preceding them. 201 2024.2 The clk command. 203 204{[%clk 1:55:21]} 205 206This is the time displayed on the players clock. It represents the time 207remaining to the next time control. It is proposed that future versions of 208software producing pgn from games played on DGT boards include this command 209after every move. 210 211The clk command is intended for the *automatic* recording of time values by 212digital clock/board combinations. It is not normaly intended for use with 213mechanical clocks which show a clock time rather than the time remaining to the 214next control. 215 2164.3 Elapsed Game Time : the egt command 217 218{[%egt 1:25:42]} 219 220The elapsed time that a player has used for all moves in the game up to that 221point. 222Takes one parameter in the format h:mm:ss 223 2244.4 Elapsed Move Time : the emt command 225 226{[%emt 0:05:42]} 227 228The elapsed time that a player used for the commented move. 229Takes one parameter in the format h:mm:ss 230 2314.5 Mechanical Clock Time : the mct command 232 233{[%mct 17:10:42]} 234The time actualy displayed on a mechanical clock. Notice that here the time 235format is hh:mm:ss. 236 2375. The "Running Clock" 238The syntax described above allows us to encode a move time for a *completed 239move*. This is all well and good but during transmission of a live game it can 240also be interesting to know the state of the clock of the player whose turn it 241is to move *but who has not yet done so*. 242 2435.1 The Clock tag 244We propose that this information should be encoded in a new header tag. 245 246[Clock "B/0:45:56"] 247 248As only one clock is running at a time only one tag is necessary. 249 250In the example above Blacks clock is running and is currently showing the time 251indicated by the string following the /. 252 253Clock is the name of the tag. 254It is followed by a string constructed as follows: 255The first character is either "W" (whites clock is running), "B" (blacks clock 256is running) or "N" (the clocks are stopped). 257This information is technicaly redundant as it could be calculated by looking at 258which side last moved. Encoding it here avoids this calculation and also covers 259the situation where a player forgets to switch the clocks. It also allows us to 260cover the admittedly rare case where the clocks are stopped. 261 262The second character is a "/" seperator. 263The rest of the string is a time in the format h:mm:ss which indicates the 264currently displayed clock time of the running clock. As for the clk command this 265represents the remaining time to the next time control. 266 2676. Clock Start Time. 2686.1 Introduction. 269Two optional tags are proposed to record the clock setting at the start of the 270play. 271While it may be helpfull to record normal clock start values here (as is done in 272the example below) they are mainly intended to cover the case where a game is 273adjourned and the displayed clock times at start of play are thus non standard. 274 275eg. 276[WhiteClock "1:07:00"] 277[BlackClock "0:56:00"] 278 2797. As explained above the existing pgn tag [TimeControl] (cf 9.6 and following 280of the standard) should be regarded as mandatory when move times are supplied. 281Clearly when manipulating time information about a game details of the time 282controls in use are vital. 283 2848. Example game. 285 286[Event "?"] 287[Site "Madrid"] 288[Date "1995.??.??"] 289[White "Beliavsky, A "] 290[Black "Timman, J "] 291[Result "1-0"] 292[ECO "E35"] 293[Round "2"] 294[TimeControl "40/7200:3600"] 295[WhiteClock "2:00:00"] 296[BlackClock "2:00:00"] 297[Clock "W/1:34:56"] 298 2991. d4 {[%clk 1:59:01]} Nf6 {[%clk 1:59:32] Timman hesitates slightly} 2. c4 300{[%clk 1:58:00]} e6 {[%clk 1:57:01]} 3. Nc3 {[%clk 1:37:00] Beliavsky clearly 301suprised here takes a full [%emt 0:20:00] on this move} Bb4 {[%clk 1:54:25]} 302 303Game notes: 304 3058.1. The time control is specified as 40 moves in two hours and then one hour to 306finish. This tag must be specified in order to permit calculation of such 307information as elapsed time since start of game. It is also particularly 308important that it be specified when fischer or bronstein time controls are used. 309 3108.2. In the example we have given the White and BlackClock tags but in this case 311this was redundant as the clocks were set as normal to show that two hours 312remained to the first time control. If the White and BlackClock tags are absent 313start times should be derived from the TimeControl tag and/or the Time tag, 314where they are specified they take precedence. 315 3168.3. The Clock tag, which is only relevant during live transmission of a game, 317here shows that it is whites turn to move and that he/she has 1 hour 34 minutes 318and 56 seconds remaining on their clock. 319 3208.4. PGN generated directly from DGT boards will have a clk command like the one 321following the first move after *all* subsequent moves. 322 3238.5. In this example we imagine that the pgn has been further edited to include 324additional text comments and commands (cf the %emt command after whites third 325move.) 326 3278.6. Notice that commands can appear at any point inside comments and that there 328may be multiple commands in a single comment. 329 3308.7. The Beliavsky/Timman game is real, all the rest is pure invention. 331 3329 Authors websites: 333DGT Projects: http://www.dgtprojects.com/ 334Chess Base: http://www.chessbase.com/ 335Chess Assistant: http://www.chessassistant.com/ 336Palview: http://www.enpassant.dk/chess/palview/ 337 33810. Thanks 339Many thanks to Axel Fritz and Robert Ericsson 340 341*additional notes: 342 3431. Cf Steve Edwards discussion of the planned implementation of BIF format here: 344http://groups.google.com/groups?hl=en&safe=off&ic=1&th=1fe06718d5ec89a5,20&seekm 345=4psfnl%24i5m%40darkstar.UCSC.EDU 346We ruled out the use of < > as delimiters specified in the BIF format because if 347this syntax is pasted into an html document then parsers will ignore the 348contents as an unrecognised tag. This is not the effect we want. 349 3502. While the seven tag roster is very precisely specified the PGN specification 351does envisage the specification of new optional tags. We have taken advantage of 352this to specify several new tags. 353 354Note also that there is already a [Time] tag - this denotes the time of the game 355start (and not anything else). 356 3573. For reference the current pgn standard is here 358http://www.clark.net/pub/pribut/standard.txt 359