Fork me on GitHub

Portable Piecepack Notation

Version: 0.11.0

Portable Piecepack Notation (PPN) is a human-readable plaintext file format for storing board games. The default Movetext parser is designed to be provide a fairly flexible notation system out of the box for playing a large variety of games but the structure is designed allow support for parsing alternative notation systems in the future as well. Originally intended for notating piecepack games, it also provides some support for other game systems as well. There is a prototype parser for this file format written in R that can be used to generate images, plaintext Unicode diagrams, and animations for the games saved in this file format.

Warning

The "Portable Piecepack Notation" is in alpha development and the specification is not likely to remain stable. I'd appreciate alpha testers to test things out but probably not a good idea to start storing large amount of games in the format just yet.

Examples

Checkers

---
GameType: American Checkers
...
1. d3-e4 1... e6-d5 2. e2-d3 2... a6-b5
3. b3-a4 3... d7-e6 4. c2-b3 4... g6-h5
5. b3-c4 5... d5-b3*c4 6. a2-a6*b3*b5 6... f7-g6
7. f1-e2 7... c6-d5 8. e4-c6*d5 8... b7-d5*c6
9. d3-e4 9... d5-c4 10. e4-d5 10... e6-f5
11. f3-g4 11... f5-e4 12. e2-d3 12... c4-e2*d3
13. d1-f3*e2 13... e4-d3 14. f3-e4 14... d3-e2
15. g4-f5 15... e2-d1 S@d1 16. g2-f3 16... 2d1-e2
17. h3-g4 17... 2e2-d3 18. h1-g2 18... e8-f7
19. g2-h3 19... c8-d7 20. f5-e6 20... d7-f5*e6
21. g4-e6*f5 21... 2d3-d7*e4*e6 22. b1-c2 22... 2d7-e6
23. d5-c6 23... g6-f5 24. c2-d3 24... h7-g6
25. a4-b5 25... 2e6-d5 26. c6-d7 26... g8-h7
27. d7-e8 C@e8 27... f5-e4  28. d3-f5*e4 28... g6-g2*f3*f5
29. 2e8-g6*f7 29... h7-f5*2g6 30. b5-c6 30... 2d5-b7*c6
31. a6-c8*2b7 A@c8 31... g2-f1 M@f1 32. 2c8-d7 32... h5-g4
33. 2d7-e6 33... g4-f3 34. 2e6-e2*f3*f5 34... 2f1-d3*2e2
35. h3-g4 35... 2d3-e4 36. g4-h5 36... 2e4-f5
37. h5-g6 37... 2f5-h7*g6
Animation of a checkers game

Four Field Kono

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}
Four Field Kono example

Fuji-san

A game of Fuji-san with a specific starting coin setup:

---
GameType:
  Name: Fujisan
  Coins: "44452n24n3aa\na25335325ann"
...
1. a1-b1 2. n2-k2 3. b1-e1 4. e1-j1 5. j1-j2 6. j2-l2 7. k2-m2
8. m2-m1 9. l2-l1 10. n1-k1 11. m1-i1 12. i1-d1 13. d1-d2 14. l1-i1
11. i1-i2 16. k1-k2 17. k2-e2 18. i2-c2 19. a2-f2 20. e2-h2 21. h2-g2
22. c2-h2 23. h2-h1 24. d2-h2 25. f2-b2 26. b2-b1 27. b1-g1
Animation of a Fuji-san game

Tic-Tac-Toe

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}
Animation of a tic-tac-toe game

PPN File Structure

PPN files are text files ending in .ppn containing one or more games in PPN notation.

  • Each game in the file should start with a line beginning with ---
    • This line is recommended but optional for the first game in a PPN file. If the first game in each PPN file begins with a --- then one can build larger PPN file archives by simply concatenating smaller PPN files together (i.e. with the *nix cat command).
  • Each game starts with a Metadata section and ends with a Movetext section.
  • PPN files should be assumed to use an UTF-8 character encoding (this includes ASCII) with no maximum line length.

Metadata

  • The Metadata section should be a single "Mapping" expressed in YAML.
    • It is recommended to use the subset of YAML understood by both the 1.1 and 1.2 YAML standards since not all popular parsers understand both (or just YAML 1.2).
  • It should begin with a line starting with ---
    • This is the same --- we said begins each game.
    • The --- is recommended but optional for the first game in a PPN file.
  • It should end with a line starting with ...
    • This ... is recommended but optional if the Metadata section does not have any empty lines and there is at least one empty line between the Metadata and Movetext sections.
    • If there are no lines starting with ... and no empty lines the Metadata section should be assumed to be empty.
  • All Metadata keys are optional.
    • If the Metadata section is empty PPN parsers should use the default Movetext parser described in a later section to interpret the Movetext (without doing any initial game piece setup).
    • One can specify the Movetext parser to use (possibly a diferent one for each game) via the MovetextParser key with a string indicating the parser to use. Movetext parsers are passed both the Metadata section and the Movetext section.

Movetext

  • Regardless of the Movetext parser to be used the Movetext should not have any lines starting with --- or ...
  • Should be (initially) parsed as UTF-8 text without restrictions on line length.
  • Additional restrictions based on which Movetext parser is used to parse it. The default Movetext parser and its additional restrictions are described in the Default Movetext Parser section.

Default Movetext Parser

  • The default Movetext Parser will supports automatic Setup for various piecepack games via the Metadata mapping.
  • The default Movetext Parser supports the following Movetext elements:
    1. Comments
    2. MoveNumbers
    3. Moves
  • Each element needs to be separated from other elements by whitespace
    • Whitespace is defined as tabs, newlines, form feeds, and any character in the Unicode Z Category.
    • All whitespace between elements (and in comments) will be converted to single spaces.
  • The default parser keeps track of the (x,y) coordinates of pieces and an ordering they can be placed on the board to reproduce the state of the board after that move. For convenience we will sometimes refer to pieces placed on the board later (earlier) in this ordering as being placed "above" ("beneath") those placed earlier (later) in this ordering, please note however that in real life a high stack of pieces placed earlier may physically be "above" an adjacent single piece placed later.

Setup

  • Currently the Movetext Parser uses the SetUp field in the Metadata to provide game setup, if that field is missing it will use the GameType field to provide game setup. This value should either be a string with the game's name or a mapping with the field Name with the game's name and optionally System of the game system to use (for games that can be played with multiple game systems); all other values of this mapping will be passed to the setup.

    • Although in general tags will treated case sensitive in this case we first process the string by converting to lower case, removing apostrophes and hyphens, "squishing" the whitespace, and converting spaces to underscores e.g. "Nine Men's Morris" will be treated as equivalent to "nine_mens_morris". Occasionally we will provide aliases e.g. "Baroque chess" will be treated as an alias for "Ultima".

    • A SetUp of None will explicitly do a initial board setup with no pieces at all.

    • GameType example of just string of game's name for setup:

      GameType: Four Field Kono
      
    • GameType example that allows passing more info to setup

      GameType:
        Name: Fujisan
        Seed: 11
      
  • The default movetext parser accepts the optional argument ScalingFactor which changes how many "inches" a coordinate represents i.e. with ScalingFactor: 2 then a1 corresponds to an x-coordinate of 2 inches and a y-coordinate of 2 inches.

Macros

The default Movetext Parse performs macro substition in the Movetext.

  • Macros are strings surrounded by a ` and ' e.g. `q'@b2 {The default "q" macro is for a black chess queen}.
  • Macros can be defined in three places (with any identically named macros earlier in this list replacing those later in the list):
    1. In a "Macros" field in the Metadata
    2. By a specified game setup function
    3. The parser includes some builtin macros.
  • Macro names cannot include whitespace nor the semi-colon ;.
  • Macro substitution happens after "moves" and "comments" are identified (and split) but before "brace expansion" occurs.

Comments

  • Comments are any text between braces { and }
    • All whitespace will be parsed as single spaces, in particular comments can span multiple lines
    • Braces are not allowed within comment braces
    • Must have white space before and after the braces (otherwise will be considered to be a brace expansion)

MoveNumbers

  • Ordinary MoveNumbers are one or more letters, numbers, periods, and/or underscores followed by at least one period
    • Unlike in PGN MoveNumbers must end in (at least one) period.
    • Ordinary MoveNumbers must have white space before and after.
    • One must not have any line start with ... (which could interfere in determining where the Metadata ends).
  • A single period . (surrounded by white space) is a special shortcut for writing the previous MoveNumber with an extra period added to the end of it e.g. 2. a4-b4 . b4-c4 is equivalent to 2. a4-b4 2.. b4-c4
  • The semi-colon ; is a special shortcut for writing the minimal a single period MoveNumber (adding some spaces around it if necessary) e.g. 2. a4-b4;b4-c4 is equivalent to 2. a4-b4 . b4-c4 which is equivalent to 2. a4-b4 2.. b4-c4 [1].
  • Putting MoveNumbers in one's Movetext is optional but if they exist PPN parsers will often break down and label moves by MoveNumbers (to make animations of a game or visualize the game state at a particular point in the game).
[1]The intention for this is quickly indicating little "submoves" within a larger proper "move" that we'd like to be able to separately visualize but that we don't want to semantically mark as a completely separate "move".

Moves

  • Moves are comprised of PieceSpec, Location, PieceId, and MoveToken.

  • One can use Unix-shell-style brace expansions as a shortcut for expressing multiple moves e.g.:

    t@{b,d}{2..8..2} {Shortcut for t@b2 t@b4 t@b6 t@b8 t@d2 t@d4 t@d6 t@d8}
    *{b..f}2 {Shortcut for *b2 *c2 *d2 *e2 *f2}
    
    • Unlike Bash-style brace expansions must have a "preamble" or "postscript" otherwise will be interpreted as a comment (but the preamble or postscript can be another brace expansion)

PieceSpec

  • The default Movetext parser supports specifying pieces by their Piece, Side, Suit, Rank, Angle, and (game system) Configuration.
  • Any attribute specifications beginning with a comma , must go after the other attribute specifications, otherwise it does not matter which order the piece attributes are specified. However the following ordering may improve readability (omitting any unnecessary elements as necessary):
    1. Piece
    2. Side
    3. Suit
    4. Rank
    5. Angle
    6. Configuration
  • When necessary the default Movetext will make Assumptions about unspecified elements.

Piece (type)

  • t for "tile"
  • c for "coin" if piecepack suit and "checkers2" "bit" if colored suit
  • d for "die"
  • p for "pawn"
  • m for "matchstick" if piecepack suit and "meeples" "bit" if colored suit
  • s for "saucer" if piecepack suit and "go" stone "bit" if colored suit
  • ● or () for "bit"
  • ▲ or /\ for "pyramid"
  • 🂠 or [] for "card"
  • ■ or [X] for "board"
    • Defaults to a "checkers2" board
  • ⚀, ⚁, ⚂, ⚃, ⚄, ⚅ sets the Configuration to "dice", Piece to "die", and sets the appropriate Rank (from 1 to 6).
  • The Unicode chess glyphs sets the Configuration to "chess2", Piece to "bit", and sets the appropriate Rank (and possibly Suit)
  • The Unicode playing card glyphs sets the Configuration to "playing_cards_tarot", Piece to "card", and sets the appropriate Rank and possibly Suit.
  • The Unicode dominoes glyphs sets the Configuration to an appropriate "dominoes" configuration, Piece to "tile", and sets the appropriate Rank and Suit.
  • ○ indicates a "go" "bit", ▦ or [#] indicates a "go" "board", and ⛂ and ⛀ indicates a "checkers2" "bit".

Side Up

  • f for "face"
  • b for "back"
  • l for "left"
  • r for "right"
  • x for "top"

Suit and Configuration

  • S, M, C, A for "Suns", "Moons", "Crowns", and "Arms" Suit and "piecepack" Configuration
    • If a μ or u is present will assume component comes from a (piecepack stackpack) "subpack" Configuration aka "mini piecepack" instead of a normal sized piecepack
    • If a ⬢ (U+2B22) is present will assume component comes from a "hexpack" Configuration (a hexagonal piecepack)
  • ♥, ♠, ♣, ♦ for "Hearts", "Spades", "Clubs", and "Diamonds" Suit and "playing_cards_expansion" Configuration
  • ♡, ♤, ♧, ♢ for (inverted 4-colored) "Hearts", "Spades", "Clubs", and "Diamonds" Suit and "dual_piecepacks_expansion" Configuration
  • R, K, G, B, Y, W for "Red", "Black", "Green", "Blue", "Yellow", or "White" Suit
    • If a "bit" indicated by ●, ○, or s or a "board" indicated by ▦ or [#] then "go"
    • If a "bit" indicated by c, ⛂, or ⛀ or a "board" indicated by ■ or [X] then "checkers2"
    • If a dominoes "tile" Piece then an appropriate colored dominoes [2]
    • If a "pyramid" Piece then an "icehouse_pieces" Configuration (invented by Andy Looney aka Looney Labs' "Looney pyramids")
    • If a μ or u is present will assume component comes from a smaller sized set:
      • "checkers1" instead of a "checkers2" set
      • "chess1" instead of a "chess2" set
  • ,sN manually sets the internal "suit" to the positive integer N and ,C' manually sets the internal "configuration" to the string C.
  • ⚀, ⚁, ⚂, ⚃, ⚄, ⚅ sets the Configuration to "dice", Piece to "die", and sets the appropriate Rank (from 1 to 6).
  • The Unicode chess glyphs sets the Configuration to "chess2", Piece to "bit", and sets the appropriate Rank (and possibly Suit)
  • The Unicode playing card glyphs sets the Configuration to "playing_cards_tarot", Piece to "card", and sets the appropriate Rank and possibly Suit.
  • The Unicode dominoes glyphs sets the Configuration to an appropriate "dominoes" configuration, Piece to "tile", and sets the appropriate Rank and Suit.
  • ○ indicates a "go" "bit", ▦ or [#] indicates a "go" "board", and ⛂ and ⛀ indicates a "checkers2" "bit".

Rank

  • 0 or n, 1 or a, 2, 3, 4, 5, 6, 7, 8, 9
    • 0 and 1 are aliases for the "null" n and the "ace" a especially useful with brace expansions e.g. {5..0}@b5 {Place six coins face up at b5 with a null on top and 5 on bottom}
    • 6, 7, 8, 9 don't exist in a standard piecepack but could exist in piecepack expansions or in components from other game systems.
  • By default the rank in most game systems are indexed starting with zero, the following game systems are indexed starting with one:
    • Icehouse pieces go from 1-pip to 3-pip pieces indicated by 1, 2, and 3 respectively.
  • ,rN manually sets the internal "rank" to the integer N.
  • ⚀, ⚁, ⚂, ⚃, ⚄, ⚅ sets the Configuration to "dice", Piece to "die", and sets the appropriate Rank (from 1 to 6).
  • The Unicode chess glyphs sets the Configuration to "chess2", Piece to "bit", and sets the appropriate Rank (and possibly Suit)
  • The Unicode playing card glyphs sets the Configuration to "playing_cards_tarot", Piece to "card", and sets the appropriate Rank and Suit.
  • The Unicode dominoes glyphs sets the Configuration to an appropriate "dominoes" configuration, Piece to "tile", and sets the appropriate Rank and Suit.

Angle

  • ^ is 0 degree rotation aka oriented "up"
  • < is a 90 degree rotation aka oriented "left"
  • v is a 180 degree rotation aka oriented "down"
  • > is a 270 degree rotation aka oriented "right"
  • ,aN manually sets an N (numeric double) degree rotation.

Assumptions

  • If missing Piece:
    • If Side is l, r, or x then assumed to be a "pyramid"
    • If both Suit and Rank are missing or neither Suit and Rank are missing assumed to be a "tile"
    • Else assumed to be a "coin"
  • If missing Side:
    • Pyramids are assumed to be "top" up.
    • Tiles and cards are assumed to be "back" up if missing suit and/or rank (else "face").
    • Coins and saucers are assumed to be "face" up if missing suit (else "back").
    • Bits are assumed to be "back" up unless a "chess2" or "chess1" piece
    • Else assumed to be "face" up.
  • If missing Suit:
    • Assumed to be "Suns" for "piecepack", "hexpack", and "subpack" pieces
    • "Hearts" for "playing_cards_expansion" and "dual_piecepacks_expansion" pieces
    • "White" for "dice" pieces
    • "Red" for "icehouse_pieces" pieces
  • If missing Rank assumed to be "null" for piecepack pieces [3] while "icehouse_pieces" and "dice" are assumed to be 1-pip.
  • If missing Angle should be assumed to be oriented straight "up" (i.e. 0 degrees)

Examples

  • t tile back
  • Aa> ace of Arms tile (face) oriented "right"
  • μAa> "subpack" ace of Arms tile (face) oriented "right"
  • C Crowns coin back (oriented "up")
  • cC3b^ (3 of) Crowns coin back (explicitly) oriented "up"
  • nv null coin face oriented "down"
  • <dM4 4 of Moons die oriented "left"
  • d (null of Suns) dice
  • pM Moons pawn
  • p♥ Hearts pawn
  • p (Suns) pawn
  • K3▲ 3-pipped black icehouse pyramid top
[2]"dominoes_black", "dominoes_blue", "dominoes_green", "dominoes_red", "dominoes_white", and "dominoes_yellow"
[3]Internally even piecepack pawns and saucers are assigned a rank even though they normally don't have a rank. Dice are assigned the rank of the face oriented upwards even though technically the dice themselves actually have six ranks.

Location

  • The default Movetext parser supports locations by Cartesian coordinates, chess-algebraic-style coordinates, or by preceding a PieceId with an &.

Examples:

  • (2.5,3.5)
  • (3,2)
  • c2

Cartesian coordinates

  • Cartesian coordinates are a left parenthesis followed by a digits (including up to one period) followed by a comma followed by digits (including up to one period) ending in a right parenthesis.
    • The digits will be considered to be a "floating-point" number.
    • The number left of the comma will be the x-coordinate and the number right of the comma the y-coordinate.

Chess-algebraic-style coordinates

  • Chess-algebraic-style coordinates begin with lowercase letters followed by digits.
  • The lowercase letters are considered to be the x-coordinate encoded as a base-26 number using the Roman letters as numerals.
    • For the purposes of this there is no "zero". a is considered equal to 1, z is considered equal to 26, and aa is considered equal to 27.
  • The digits are considered to the y-coordinate encoded as a (base-10) integer.

Get location from PieceId

  • A PieceId string preceded by a & indicates the x,y coordinates of that piece.
    • For the PieceId form N Location it returns the x,y coordinates of that Location.
    • Otherwise if PieceId identifies several pieces (e.g. "greedy" search) then it returns the x,y, coordinates of the "last" piece (according to internal ordering of pieces).

PieceId

A PieceId is used to identify specific pieces on the board. Currently PPN supports the following types of PieceId:

  • A Location is used to identify the top piece at that Location
  • N Location is used to identify the top N pieces at that Location
    • An example would be 2b4-b3*2a2 {Move top two pieces at b4 to b3 and remove top two pieces at a2}
    • If there are less than N pieces at that exact Location it will identify the N nearest pieces to the Location (according to 2D Euclidean distance)
  • Location[Slice] is used to identify a "slice" of pieces at that Location
    • Pieces at a location are indexed starting with 1 with pieces "later" in the internal ordering (i.e. "above") having a lower index
    • An example would be b4[1]_%b3[2] {Move the top piece at b4 directly under the secord piece at b3}
    • Another example would be b4[3:6]-b3 {Move the third, fourth, fifth, and sixth pieces (from the top) at b4 to b3}
    • Another example would be *(2,4)[1,3,5] {Remove the first, third, and fifth pieces (from the top) located at (2,4)}
  • ?PieceSpec is used to identify a single piece with a "non-greedy" search based on their PieceSpec
    • First, the PieceSpec is parsed and only the explicitly listed features are searched against. If there is a unique match it is identified e.g. ?dS identifies the "Suns" dice in a game with a single piecepack.
    • Second, if no match the PieceSpec is parsed and all assumptions listed in PieceSpec are made including angle, if there are any matches the one last in the internal play order is returned.
    • Third, if no match the PieceSpec is parsed and all assumptions listed in PieceSpec are made except angle, if there are any matches the one last in the internal play order is returned e.g. ?S5 identifies the "5 of Suns" tile in a game with a single piecepack.
  • /PieceSpec is used to identify piece(s) with a "greedy" search based on their PieceSpec
    • The PieceSpec is parsed and only the explicitly listed features are searched against e.g. /M identifies all the "Moons" pieces, /cf identifies all the coins face up, etc.
  • A PieceId preceded by a ^ identifies the piece from the game state at the beginning of the move
    • An example would be a1-a2 a2-a3 {equivalent to a1-a3} versus a1-a2 ^a2-a3 {equivalent to a2-a3 a1-a2}.

MoveToken

The default movetext parser supports the following MoveTokens:

Adding new pieces

  • @ and \ are used to "drop" new pieces onto the board.
    • PieceSpec@Location means drop PieceSpec on top of Location, it will be placed after all other pieces in the internal ordering.
    • PieceSpec\Location means drop PieceSpec at Location, it will be placed before all the other pieces in the internal ordering (i.e. the bottom).
    • PieceSpec@Location%PieceId means drop PieceSpec on top of Location, it will be placed after PieceId in the internal ordering.
    • PieceSpec\Location%PieceId means drop PieceSpec at Location, it will be placed before PieceId in the internal ordering.
    • PieceSpec@%PieceId is a shortcut for PieceSpec@&PieceId%PieceId i.e. drop PieceSpec directly above PieceId.
    • PieceSpec\%PieceId is a shortcut for PieceSpec\&PieceId%PieceId i.e. drop PieceSpec directly under PieceId.

Removing pieces

  • * is used to remove pieces from the board. *PieceId means remove the piece identified by PieceId.
    • Unlike other MoveTokens it can be added at the end of other Moves e.g. b5-c5*b4*b3 {Move top piece at b5 to c5 and remove top pieces at b4 and b3}.

Moving pieces

  • - and _ (or ‿) used to move existing pieces elsewhere on the board.
    • PieceId-Location means moving the piece(s) identified by PieceId to Location, it will be placed after all the other pieces in the internal ordering.
    • PieceId_Location means moving the piece(s) identified by PieceId to Location, it will be placed before all the other pieces in the internal ordering.
    • PieceId1-Location%PieceId2 means moving the piece(s) identified by PieceId1 to Location, it will be placed after the piece identified by PieceId2 in the internal ordering.
    • PieceId1_Location%PieceId2 means moving the piece(s) identified by PieceId1 to Location, it will be placed before the piece identified by PieceId2 in the internal ordering.
    • PieceId-%PieceId2 is a shortcut for PieceId1-&PieceId2%PieceId2 i.e. move PieceId1 directly above PieceId2.
    • PieceId_%PieceId2 is a shortcut for PieceId1_&PieceId2%PieceId2 i.e. move PieceId1 directly underneath PieceId2.
    • ‿ (U+203F) can be used instead of _. _ is easier to type and found in more fonts but ‿ is harder to confuse with - (especially in handwritten notes).
  • # is used to represent a "piece swap". Let Location1 and Location2 represent the Location of PieceId1 and PieceId2 respectively, then PieceId1:PieceId2 is equivalent to ^PieceId1-Location2 ^PieceId2-Location1.
  • : is used to represent a "displacement capture". PieceId1:PieceId2 means find the Location of the piece(s) identified by PieceId2, remove the PieceId2 piece(s), and move the PieceId1 piece(s) to that Location.
    • The PieceId1 piece(s) that are moved will be placed after all the other pieces in the internal ordering.
    • Let Location be the location of the piece(s) represented by PieceId2, then PieceId1:PieceId2 is equivalent to *PieceId2 PieceId1-Location.
  • @> is used to rotate a piece clockwise. PieceId@>Degrees rotates the piece(s) represented by PieceId clockwise Degrees degrees.

Updating/replacing pieces

  • = is used "replace" pieces on the board with new pieces. PieceId=PieceSpec means replace the piece identified PieceId to PieceSpec (with all assumptions) e.g. b5=S> {replace top piece at b5 with Suns coin back oriented right}.
  • ~ is used "update" pieces on the board with new characteristics. PieceId~PieceSpec means update the piece identified PieceId according to only the explicitly listed elements in PieceSpec e.g. ?dS~3 means have the "Suns" die now show the 3 rank on top without updating orientation.

Appendix

Default Macros

The default movetext parser has the following built-in macros (these can be over-ridden by the Setup function or by the user in the Metadata):

Default parser's built-in macros
macro replacement hexadecimal
H ♥ U+02665
S ♠ U+02660
C ♣ U+02663
D ♦ U+02666
WH ♤ U+02664
WS ♡ U+02661
WD ♢ U+02662
WC ♧ U+02667
RJ 🂿 U+1f0bf
BJ 🃏 U+1f0cf
WJ 🃟 U+1f0df
TF 🃠 U+1f0e0
p ♟ U+0265f
n ♞ U+0265e
b ♝ U+0265d
r ♜ U+0265c
q ♛ U+0265b
k ♚ U+0265a
P ♙ U+02659
N ♘ U+02658
B ♗ U+02657
R ♖ U+02656
Q ♕ U+02655
K ♔ U+02654
SA 🂡 U+1f0a1
S2 🂢 U+1f0a2
S3 🂣 U+1f0a3
S4 🂤 U+1f0a4
S5 🂥 U+1f0a5
S6 🂦 U+1f0a6
S7 🂧 U+1f0a7
S8 🂨 U+1f0a8
S9 🂩 U+1f0a9
ST 🂪 U+1f0aa
SJ 🂫 U+1f0ab
SC 🂬 U+1f0ac
SQ 🂭 U+1f0ad
SK 🂮 U+1f0ae
HA 🂱 U+1f0b1
H2 🂲 U+1f0b2
H3 🂳 U+1f0b3
H4 🂴 U+1f0b4
H5 🂵 U+1f0b5
H6 🂶 U+1f0b6
H7 🂷 U+1f0b7
H8 🂸 U+1f0b8
H9 🂹 U+1f0b9
HT 🂺 U+1f0ba
HJ 🂻 U+1f0bb
HC 🂼 U+1f0bc
HQ 🂽 U+1f0bd
HK 🂾 U+1f0be
DA 🃁 U+1f0c1
D2 🃂 U+1f0c2
D3 🃃 U+1f0c3
D4 🃄 U+1f0c4
D5 🃅 U+1f0c5
D6 🃆 U+1f0c6
D7 🃇 U+1f0c7
D8 🃈 U+1f0c8
D9 🃉 U+1f0c9
DT 🃊 U+1f0ca
DJ 🃋 U+1f0cb
DC 🃌 U+1f0cc
DQ 🃍 U+1f0cd
DK 🃎 U+1f0ce
CA 🃑 U+1f0d1
C2 🃒 U+1f0d2
C3 🃓 U+1f0d3
C4 🃔 U+1f0d4
C5 🃕 U+1f0d5
C6 🃖 U+1f0d6
C7 🃗 U+1f0d7
C8 🃘 U+1f0d8
C9 🃙 U+1f0d9
CT 🃚 U+1f0da
CJ 🃛 U+1f0db
CC 🃜 U+1f0dc
CQ 🃝 U+1f0dd
CK 🃞 U+1f0de
T1 🃡 U+1f0e1
T2 🃢 U+1f0e2
T3 🃣 U+1f0e3
T4 🃤 U+1f0e4
T5 🃥 U+1f0e5
T6 🃦 U+1f0e6
T7 🃧 U+1f0e7
T8 🃨 U+1f0e8
T9 🃩 U+1f0e9
T10 🃪 U+1f0ea
T11 🃫 U+1f0eb
T12 🃬 U+1f0ec
T13 🃭 U+1f0ed
T14 🃮 U+1f0ee
T15 🃯 U+1f0ef
T16 🃰 U+1f0f0
T17 🃱 U+1f0f1
T18 🃲 U+1f0f2
T19 🃳 U+1f0f3
T20 🃴 U+1f0f4
T21 🃵 U+1f0f5
0-0 🁣 U+1f063
0-1 🁤 U+1f064
0-2 🁥 U+1f065
0-3 🁦 U+1f066
0-4 🁧 U+1f067
0-5 🁨 U+1f068
0-6 🁩 U+1f069
1-0 🁪 U+1f06a
1-1 🁫 U+1f06b
1-2 🁬 U+1f06c
1-3 🁭 U+1f06d
1-4 🁮 U+1f06e
1-5 🁯 U+1f06f
1-6 🁰 U+1f070
2-0 🁱 U+1f071
2-1 🁲 U+1f072
2-2 🁳 U+1f073
2-3 🁴 U+1f074
2-4 🁵 U+1f075
2-5 🁶 U+1f076
2-6 🁷 U+1f077
3-0 🁸 U+1f078
3-1 🁹 U+1f079
3-2 🁺 U+1f07a
3-3 🁻 U+1f07b
3-4 🁼 U+1f07c
3-5 🁽 U+1f07d
3-6 🁾 U+1f07e
4-0 🁿 U+1f07f
4-1 🂀 U+1f080
4-2 🂁 U+1f081
4-3 🂂 U+1f082
4-4 🂃 U+1f083
4-5 🂄 U+1f084
4-6 🂅 U+1f085
5-0 🂆 U+1f086
5-1 🂇 U+1f087
5-2 🂈 U+1f088
5-3 🂉 U+1f089
5-4 🂊 U+1f08a
5-5 🂋 U+1f08b
5-6 🂌 U+1f08c
6-0 🂍 U+1f08d
6-1 🂎 U+1f08e
6-2 🂏 U+1f08f
6-3 🂐 U+1f090
6-4 🂑 U+1f091
6-5 🂒 U+1f092
6-6 🂓 U+1f093

Comments


There are no comments yet.

Add a Comment

You can use Markdown or restructuredText to format your comment.

links

social