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 actors 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 JSON structure below shows the format of the resource:

{src_square}, {dst_square}, {piece_name}, {piece_hand}
Items

The following table defines the items that appear in this resource:

Item Value Required Default Description
src_square an unsigned integer false null A source square.
dst_square an unsigned integer true   A target square.
piece_name a string true   The name of the piece.
piece_hand a string false null The name of the captured piece in hand.

Source square

The “src_square” item is OPTIONAL.

The “src_square” item represents the coordinate of the source square of the action.

If the value is null, the action SHOULD be a drop.

Target square

The “dst_square” item is REQUIRED.

The “dst_square” item represents the coordinate of the target square of the action.

Piece name

The “piece_name” item is REQUIRED.

The “piece_name” item represents the name of the piece of the action.

Piece hand

The “piece_hand” item is OPTIONAL.

The “piece_hand” item represents the name of the piece that is retained in hand by the player who performed 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:

[ null, 2, "R", null ]

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", null ]

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", null], [32, 40, "p", null] ]

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", null ]

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", null ]

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", null ]

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