1Standard: Portable Game Notation Specification and Implementation Guide
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
101. Introduction
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.
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.
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.
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.
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.
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.
39It thus seems important to us to attempt an incremental improvement to PGN
40intended to eliminate the functional weaknesses described above.
42This document proposes an extension to PGN designed to offer an immediate 'work
43around' solution to the problems outlined above.
452. Design aims
462.1 The enhancements must not break the existing standard.
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.
522.2  The enhancements should maintain the ease of use and legibility so
53characteristic of PGN.
55This rules out very precise but possibly more computer readable formats in
56favour of clearer human readable ones.
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.
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
653. Proposals
663.1 Introduction
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.
73Apart from a general command syntax we propose several specific commands
74designed for the handling of time information.
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.
80These additions are not problematic as the standard concedes the possibility of
81adding new tags to the header (outside the mandatory seven tag roster)
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.
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.
963.2.2 Structure
97The command string is structured as follows.
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 ]
105For example:
106[%clk 1:05:23]
1083.2.3 Opening delimiter
109The characters [% are redefined to indicate the start of a command sequence when
110found in between pgn comment tags.
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.
1173.2.3 Commands
119Command names start immediately after the [%.
120They consist of one or more alphanumeric characters
121They are terminated by the first space character encountered.
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
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.
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.
135For display purposes only presentation software, such as pgn readers, should by
136default strip out all commands before display in order to improve legibility.
1383.2.4 Parameters
140This parameter syntax is based on the epd opcode syntax described at 16.2.4 of
141the pgn spec.
143A command is followed by a single space and then either by a single operand or
144by a comma separated list of operands.
146An operand is either:
147i) a set containing any ascii characters except the comma and right hand square
150ii) a double quoted string containing a set of any ascii characters except the
151double quote.
153For instance:
154[%command 1:45:12,Nf6,"very interesting, but wrong"]
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
160Commas are illegal in non quote delimitted strings because the comma serves as
161the operand list separator.
163Right hand square brackets are illegal in non quote delimitted strings because
164they terminate both the last operand and the command.
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
170So it is possible to pass a full FEN string as an unquoted operand as in the
171example below.
173[%command "very tense start to the
174game",4r1k1/pp1b2r1/2n1pq1p/3p2pP/2pP2B1/P1P1Q3/2P2PPB/R4RK1 w - - 0 1,e4,d4]
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.
1793.2.5 Terminator
180The command is terminated by a single ] character.
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}
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.
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.
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)
199The comments containing the embedded commands are to be taken as referring to
200the move immediately preceding them.
2024.2 The clk command.
204{[%clk 1:55:21]}
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.
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.
2164.3 Elapsed Game Time : the egt command
218{[%egt 1:25:42]}
220The elapsed time that a player has used for all moves in the game up to that
222Takes one parameter in the format h:mm:ss
2244.4 Elapsed Move Time : the emt command
226{[%emt 0:05:42]}
228The elapsed time that a player used for the commented move.
229Takes one parameter in the format h:mm:ss
2314.5 Mechanical Clock Time : the mct command
233{[%mct 17:10:42]}
234The time actualy displayed on a mechanical clock. Notice that here the time
235format is hh:mm:ss.
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*.
2435.1 The Clock tag
244We propose that this information should be encoded in a new header tag.
246[Clock "B/0:45:56"]
248As only one clock is running at a time only one tag is necessary.
250In the example above Blacks clock is running and is currently showing the time
251indicated by the string following the /.
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.
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.
2676. Clock Start Time.
2686.1 Introduction.
269Two optional tags are proposed to record the clock setting at the start of the
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.
276[WhiteClock "1:07:00"]
277[BlackClock "0:56:00"]
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.
2848. Example game.
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"]
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]}
303Game notes:
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.
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.
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.
3208.4. PGN generated directly from DGT boards will have a clk command like the one
321following the first move after *all* subsequent moves.
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
3278.6. Notice that commands can appear at any point inside comments and that there
328may be multiple commands in a single comment.
3308.7. The Beliavsky/Timman game is real, all the rest is pure invention.
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/
33810. Thanks
339Many thanks to Axel Fritz and Robert Ericsson
341*additional notes:
3431. Cf Steve Edwards discussion of the planned implementation of BIF format here:
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.
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.
354Note also that there is already a [Time] tag - this denotes the time of the game
355start (and not anything else).
3573. For reference the current pgn standard is here