Portable Action Notation

A general purpose UTF-8 and JSON-based format for recording moves in most chess variants.

Created
Updated
Version
1.0.0

Introduction

PAN (Portable Action Notation) is a lightweight, JSON-based format that gives a consistent and easy way to represent actions inside moves in the context of chess games.

Compatible with multidimensional boards, easy for humans to read and write, and easy for machines to import and export, it is completely laws of game independent and compatible with most abstract strategy board games such as Draughts, Go and the main chess variants, including 장기Janggi, หมากรุกMakruk, 将棋Shogi, Western, 象棋Xiangqi. These properties make PAN an ideal data-interchange format for storing changes between actions of most pieces from abstract strategy board games such as pawns, pieces, kings, stones.

Notational conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Naming the board squares

Squares MUST be identified by a coordinate from an array that is a one-dimensional flattening of the board. E.g., on the starting position of a traditional Western chessboard, the square of the White Queen is 59 and the square of the White King is 60.

Notation for Actions

Resource representation

The BNF structure below shows the format of the resource:

<actions>         ::= <action> | <action> ";" <actions>
<action>          ::= <source_square> "," <target_square> "," <moved_piece> "," <captured_piece>
<source_square>   ::= <square> | "*"
<target_square>   ::= <square>
<square>          ::= "0" | [1-9] [0-9]*
<moved_piece>     ::= <piece>
<captured_piece>  ::= <piece>
<piece>           ::= any string composed of one or more characters except ",", ";" and "."

Source square

The source square item represents the coordinate of the source square of the action.

If the action is a drop, the value MUST be “*” as there isn’t any coordinate.

Target square

The target square item represents the coordinate of the target square of the action.

Moved piece

The moved piece item represents the name of the piece which performs the action.

Captured piece

The captured piece item represents the name of the piece that is retained in hand by the player who performs the action.

Examples

Drop

Captured pieces can be truly captured, such as in Shogi. Thus, they are retained in hand, and can be brought back into play under the capturing player’s control. On any turn, instead of moving a piece on the board, a player MAY take a piece that had been previously captured and place it. The piece is then part of the forces controlled by that player. This is termed dropping the piece, or just a drop.

Given the following position:

[
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null
]

When this action is played:

*,2,R

Then the position becomes:

[
  null, null, "R", null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null
]

Capture

En passant

In Western chess, a special pawn capture can occur immediately after a pawn makes a action of two squares from its starting square, and it could have been captured by an enemy pawn had it advanced only one square.

Given the following position:

[
  null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null,
  null, "p", null, null, null, null, null, null,
  null, null, null, null, null, null, null, null,
  "P", null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null
]

After this action from bottom-side player:

48,32,P

Given this new position:

[
  null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null,
  "P", "p", null, null, null, null, null, null,
  null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null
]

Top-side player can capture en passant with 2 actions:

33,32,p;32,40,p

Then the position becomes:

[
  null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null,
  "p", null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null
]

Piece in hand

Given the following position:

[
  "r", "P", null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null
]

When this action is played:

0,1,r,p

Then the position becomes:

[
  null, "r", null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null
]

The 4th parameter indicates that the captured “P” piece becomes “p” and is retained in hand by the player who played.

Shift

Let’s transfer a friendly piece (Xiangqi Chariot, Black) from its square to an empty square of the board.

Given the following position:

[
  "r", null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null
]

When this action is played:

0,8,r

Then the position becomes:

[
  null, null, null, null, null, null, null, null, "r",
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null
]

Promotion

Western Pawn to a Queen

Given the following position:

[
  null, null, null, null, null, null, null, null,
  "P", null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null
]

When this action is played:

6,0,Q

Then the position becomes:

[
  "Q", null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null
]

Shogi Pawn to a promoted Shogi Pawn

Given the following position:

[
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  "P", null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null
]

When this action is played:

27,18,+P

Then the position becomes:

[
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  "+P", null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null,
  null, null, null, null, null, null, null, null, null
]

See also
Implementation