PGN (.pgn)

Background

    • MIME Type: application/vnd.chess-pgn
    • Standard text format for storing recorded chess games, supported by every major chess platform.
    • PGN is an acronym for Portable Game Notation.
    • ASCII format.
    • Can store arbitrary game metadata.
    • Can store annotations and suggested variations for any move.
    • Standardized by Steven J. Edwards in 1994.

Import & Export

  • Import["file.pgn"] imports a PGN file, returning a list of games and their metadata.
  • Import["file.pgn",elements] imports the specified elements.
  • See the following reference pages for full general information:
  • Importimport from a file
    CloudImportimport from a cloud object
    ImportStringimport from a string
    ImportByteArrayimport from a byte array

Import Elements

  • General Import elements:
  • "Elements" list of elements and options available in this file
    "Rules"full list of rules for each element and option
    "Summary"a summary of the file
  • Game elements:
  • "FENStrings"a list of FEN strings for each game
    "Games"a list of game moves and metadata
    "DynamicGameSummary"an interactive summary of the game
    "PositionRenderingList"a dynamic rendering for each game
    "Metadata"a list of game metadata
    "MoveCount"number of moves per game
    "Moves"a list of moves per game
    "GameResult"final game result per game
  • Each move is a single move of one player, also known as a ply.
  • Import by default uses the "Games" element for the PGN format.
  • Game results could be "1-0", "0-1", "1/2-1/2" (draw) or "*" (unknown).
  • Annotation element:
  • "AnnotatedMoves"move annotations as well as suggested move variations
  • Overall file element:
  • "GameCount"number of games stored in the file

Options

  • Elements that involve rendering a chessboard take the following options:
  • "BoardOrientation"Automaticon which side of the board to place white pieces
    "Icons"Automatica set of icons to use for chess pieces
    "SquareColors"Automatica list of two colors for light and dark squares
  • Elements that return chess moves take the following options:
  • "IncludeAnnotations"Automaticwhether to include move annotations
    "IncludeVariations"Automaticwhether to include move variations

Examples

open allclose all

Basic Examples  (1)

Import a summary of a PGN file:

Import the last positions of each game:

Scope  (1)

List available Import elements:

Import Elements  (19)

GameCount  (1)

Get the number of games stored in a PGN file:

Some files may contain many games:

Games  (2)

Import all the games in the file:

Import selected games from the file:

DynamicGameSummary  (1)

Get summary of the first game in the file:

PositionRenderingList  (1)

Import last 5 positions from the first game in the file as Graphics:

Metadata  (2)

Import metadata of all the games in the file:

Import metadata of selected games from the file to a dataset:

GameResult  (3)

Get results of all games in the file:

Get the result of a specific game:

"GameResult" returns "*" for games with an unknown result:

MoveCount  (2)

Get number of moves (plies) in all games in the file:

Get move count of a specific game:

Moves  (2)

Get a list of moves per game:

Get last 10 moves of the second game in the file:

AnnotatedMoves  (2)

Get last 10 moves of the second game in the file with annotations and variations:

Get last 10 moves of the second game in the file with annotations:

FENStrings  (2)

Import all positions from a game as a list of FEN strings:

Import last position from the first 10 games in the file:

Summary  (1)

Get the summary of a PGN file:

Import Options  (14)

"BoardOrientation"  (3)

View a game summary from black's perspective:

Import first 5 positions from a game with white pieces on the left side of the board:

By default, Import displays white pieces at the bottom:

"Icons"  (2)

White pieces are specified using capital letters, black pieces using lowercase letters.

Use a custom set of icons for white pieces:

Use custom icons for the kings:

"IncludeAnnotations"  (4)

With the "AnnotatedMoves" element, annotations are included by default:

Import "AnnotatedMoves" without annotations:

With the "Moves" element, annotations are not included by default:

Import "Moves" with annotations:

"IncludeVariations"  (4)

With the "AnnotatedMoves" element, variations are included by default:

Import "AnnotatedMoves" without variations:

With the "Moves" element, variations are not included by default:

Import "Moves" with variations (recursively):

"SquareColors"  (1)

Specify custom colors for chessboard squares: