The Portable Piecepack Notation (PPN) is a human-readable plaintext file format for storing board games. A preliminary draft of the specification is available at:


It is currently in active development but a prototype parser is available that can be used to generate diagrams and animations for games written in it.

Warning the "portable piecepack notation" specification is in alpha and non-reverse-compatible changes will likely be made. It is a good idea to play some games in it to help test it out but probably not a good idea (yet) to mass convert games into this format for long-term storage.


A simple game of Tic-Tac-Toe with no automatic setup:

Event: Example Tic-Tac-Toe Game
Result: 1-0
setup. t@b2
1. S@b2 1... M@a2 {? (1... M@a1)}
2. S@c1 2... M@a3
3. S@a1 3... M@c3
4. S@b1 {X wins}

A game of Four Field Kono with automatic setup:

GameType: Four Field Kono

1. b1:b3 1... d3:b3 2. c1:c3 2... a3:c3 3. c2-c1 3... b4:b2 4. a1-b1 4... b3:b1
5. d1:b1 5... c3-c2 6. a2-a3 6... b2:d2 7. a3-b3 7... c4-c3 8. c1-d1 8... d4-d3
9. b1-b2 9... d2:b2 10. b3-a3 10... b2-b1 {Player 1's loss is assured with the
 separation of their two remaining pieces and they should resign in a real game}
11. a3-a2 11... b1-c1 12. d1-d2 12... c1-d1 13. a2-a3 13... a4-b4
14. a3-a4 14... b4-c4 15. a4-b4 15... c4-d4 16. b4-a4 16... d4:d2 {Player 2 wins}

Prototype Parser

There is a prototype parser that has been made available in the ppgames R package. One can read in games with read_ppn, make image diagrams of moves with plot_move, make plaintext Unicode diagrams of moves with cat_move, or make a GIF animation of a game with animate_game. plot_move and animate_game can (optionally) be passed a piecepackr "configuration list" in order to customize the appearance of the piecepack in the images. Here is an example of using a highly customized piecepack configuration for a game of Ultima:

Contents of rhe.ppn:

Event: Operation Ultima
GameType: Ultima
Round: 1
White: Davis, Trevor L
WhiteTitle: null
Black: Hale-Evans, Ron
BlackTitle: GM
1. g2-g4 1... {Ron's move goes here}

R code:

# Don't have any fonts that support upside down rook and too lazy to write custom grob
# so the Immobilizer will just be an empty "null" coin face
cfg <- pp_cfg(list(border_lex=3, border_color="grey", gridline_color.tile="grey", 
           suit_text.coin_back="\u265f", suit_text.pawn_face="\u265d", dm_text.pawn=""))
game <- read_ppn("rhe.ppn")[[1]]
animate_game(game, "rhe_ultima1.gif", cfg=cfg)
plot_move(game, "rhe_ultima1.png", cfg=cfg)

Resulting image of state of game after one move:

Resulting animation of game so far: