Chess Forge File Format - czbar/ChessForge GitHub Wiki

Chess Forge stores its workbooks in files with the .pgn extension, one workbook per file. It uses the standard PGN syntax with additional headers and keywords. Therefore, any PGN reader/viewer software should be able to open Chess Forge workbooks while ignoring the Chess Forge specific extensions that it will not be able to interpret.

Where possible, Chess Forges uses the same PGN extensions as the lichess.org web site. For example, the keywords %cal and %csl are used to describe locations of arrows and circles drawn on the board.

Workbook PGN File Structure

A Chess Forge workbook file consists of multiple PGN "games". A game may represent:

  • The workbook preface.
  • A study tree.
  • A model game.
  • An exercise.
  • An Introduction.

Workbook Preface

The Workbook Header is essentially a dummy "game" with headers that identify the file as a Chess Forge workbook. It does not contain any moves but may include a comment.

[ChessForgeWorkbook "My Favourite Opening"]
[Annotator ""]
[WorkbookVersion "1.2"]
[Guid "4305aca6-ddd6-40b6-93a4-0832ca11b02d"]
[TrainingSide "White"]
[StudyBoardOrientation "White"]
[GameBoardOrientation "White"]
[ExerciseBoardOrientation "None"]
[White "CHESS FORGE"]
[Black "WORKBOOK"]
[Result "*"]
{This PGN Workbook is optimized for viewing in Chess Forge https://sourceforge.net/projects/chessforge/.
Chess Forge is a Free and Open Source Windows application.}

*
  • ChessForgeWorkbook - mandatory for the file to be recognized as a Chess Forge workbook. It will be treated as the title of the workbook and displayed in the Chess Forge interface.
  • Annotator - represents the author of the Workbook
  • WorkbookVersion - internally generated value when saving the workbook.
  • Guid - internally generated value when saving the workbook.
  • White - not required by Chess Forge however required by other PGN viewers to read the file
  • Black - not required by Chess Forge however needed by other PGN viewers to read the file
  • Result- not required by Chess Forge however needed by other PGN viewers to read the file. PGN-legal values are 1-0, 0-1, 1/2-1/2, *

Other values should be populated as explained below. However, if they are left blank, the system will prompt the user with the Workbook Options dialog box to fill them in:

  • TrainingSide could be White, Black or None. Any other value will be interpreted by Chess Forge as White
  • StudyBoardOrientation could be White or Black
  • GameBoardOrientation could be White or Black
  • ExerciseBoardOrientationcould be White, Black or None where none means that Chess forge will orient the board so the side on the move is at the bottom

Chapters

The rest of the file comprises one or more Chapters.

Each chapter contains

  • Exactly one study tree.
  • Zero, one or multiple model games.
  • Zero, one or multiple exercises.
  • Zero, one or multiple bookmarks.
  • Optional introduction

Study Tree

The Study Tree is mandatory for each chapter and it is essentially a dummy PGN "game" containing the chapter's training variation tree. It must be the first "game" in the chapter:

[ChapterTitle "Intro Chapter"]
[Guid "af11501c-d428-4082-aa38-d971fb259f8a"]
[Annotator ""]
[ContentType "Study Tree"]
[White "CHAPTER"]
[Black "Intro Chapter"]
[IndexDepth "4"]
[Result "*"]
[Preamble "Line 1"]
 ...
[Preamble "Line N"]

1. d4 Nf6 2. c4 g6 3. Nc3 (3. Bg5 Bg7 4. Nc3 d6 (4... d5 5. Bxf6 Bxf6 6. Nxd5 
(6. cxd5 c5 7. dxc5 Nd7 (7... Na6)) 8. e3 *
  • ChapterTitle will be displayed in the Chess Forge interface.
  • Guid - internally generated value when saving the workbook.
  • Annotator - represents the author of the Chapter.
  • ContentType - must be set to Study Tree.
  • Index Depth - stores the level of the Variation Index used by the Study Tree the last time it was viewed (See Self Indexing View for more details).
  • White - not required by Chess Forge however required by other PGN viewers to read the file
  • Black - not required by Chess Forge however needed by other PGN viewers to read the file
  • Result- not required by Chess Forge however needed by other PGN viewers to read the file. PGN-legal values are 1-0, 0-1, 1/2-1/2, *
  • Preamble "Line N" - multiple preamble lines will be combined into a single text and shown in the GUI below the Chapter Title and Self Indexing section.

Model Games

A chapter may or may not include Model Games. These are regular PGN games with some additional headers.

[ContentType "Model Game"]
[Event "Some Place"]
[Round "6"]
[ECO "B21"]
[Guid "Rf0dbb400136447fab4896d823d73377f"]
[Date "2012.06.10"]
[White "Player 1"]
[Black "Player 2"]
[WhiteElo ""]
[BlackElo ""]
[Annotator "John Smith"]
[Result "1-0"]
[Preamble "Line 1"]`
 ...
[Preamble "Line N"]

1. d4 Nf6 2. c4 g6 3. Nc3 (3. Bg5 Bg7 4. Nc3 d6 (4... d5 5. Bxf6 Bxf6 6. Nxd5 
(6. cxd5 c5 7. dxc5 Nd7 (7... Na6)) 8. e3 1-0
  • Content - must be set to Model Game.
  • Event - name of the tournament.
  • Round - round number in which the game was played.
  • ECO - Encyclopaedia of Chess Openings code, consisting of a letter (A–E) followed by a two-digit number (00–99).
  • Guid - internally generated value when saving the workbook.
  • Date - the date the game was played.
  • White - name of the player with the white pieces.
  • Black - name of the player with the black pieces.
  • WhiteElo - Elo rating of the white player.
  • BlackElo - Elo rating of the black player.
  • Annotator - represents the author of the Chapter.
  • Result- result of the game. Allowed values are 1-0, 0-1, 1/2-1/2, *
  • Preamble "Line N" - multiple preamble lines will be combined into a single text and shown after the game header and before the game moves.

Exercises

A chapter may or may not include Exercises. An exercise uses the same format as a regular PGN game except that it may start from any position.

[ContentType "Exercise"]
[Event "Tournament"]
[Round "2"]
[ECO ""]
[Guid "R7b89fce83ce44303a561050da6a8476f"]
[Date "2025.04.01"]
[White "Player 1"]
[Black "Player 2"]
[WhiteElo "2450"]
[BlackElo "2375"]
[Annotator "Adam Smith"]
[Result "0-1"]
[FEN "r1b1kb1r/ppqp1ppp/2n1p3/8/2B1P1n1/2N2N1P/PP2QPP1/R1B2RK1 b kq - 0 1"]
[Preamble "Line 1"]
 ...
[Preamble "Line N"]

1. ... Qh4# 0-1
  • Content - must be set to Exercise.
  • Event - name of the tournament.
  • Round - round number in which the game was played.
  • ECO - Encyclopaedia of Chess Openings code, consisting of a letter (A–E) followed by a two-digit number (00–99).
  • Guid - internally generated value when saving the workbook.
  • Date - the date the game was played.
  • White - name of the player with the white pieces.
  • Black - name of the player with the black pieces.
  • WhiteElo - Elo rating of the white player.
  • BlackElo - Elo rating of the black player.
  • Annotator - represents the author of the Chapter.
  • Result- result of the game. Allowed values are 1-0, 0-1, 1/2-1/2, *
  • FEN - defines the starting position of the exercise.
  • Preamble "Line N" - multiple preamble lines will be combined into a single text and shown after the exercise solution.

Intro

A chapter may or may not include Intro, a descriptive introduction into the chapter.

[Guid "af11501c-d428-4082-aa38-d971fb259f8a"]
[ContentType "Intro"]
[White "Chapter"]
[Black "Introduction"]
  • Content - must be set to Intro.
  • Guid - internally generated value when saving the workbook.
  • White - not required by Chess Forge however required by other PGN viewers to read the file
  • Black - not required by Chess Forge however needed by other PGN viewers to read the file

PGN Format Extensions

Chess Forge uses the standard PGN as much as possible to maintain compatibility with other PGN viewers/editors. Some PGN extensions needed in Chess Forge have already been implemented elsewhere in which case the program used them in the same manner as they were implemented in lichess.org. That feels appropriate as lichess.org is also an Open Source project.

Headers

See the sections above for discussion of the extension headers. There are a number of new ones that serve Chess Forge's unique needs.

Keywords

Chess Forge uses some special keywords/commands that follow the general guidance of enclosing them with square brackets and prefixing with the % character.

  • %cal as used by lichess.org, indicates an arrow on the board e.g. [%cal Gd8d1,Re1d1].
  • %csl as used by lichess.org, indicates a circle over a square on the board e.g. [%csl Rf2].
  • %eval as used by lichess.org, indicates engine evaluation e.g. [%eval 0.23].
  • %bkm Chess Forge specific, indicates a bookmarked position.