General Actor Notation

A general purpose ASCII-based format for storing actors from abstract strategy games.

Created
Updated
Status
beta

Abstract

With chess variants, it is not always relevant to identify pieces with a single ASCII character. The purpose of this article is to avoid naming ambiguities and collisions between actors on two-player abstract strategy games, keeping ASCII character set.

Status of this document

This document is a beta of the GAN specification.

Copyright notice

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License.


Introduction

GAN (General Actor Notation) is a lightweight, ASCII-based format that gives a consistent and easy way to represent actors from abstract strategy games.

Easy for humans to read and write, and easy for machines to import and export, it is compatible with actors of most abstract strategy board games such as Draughts, Go and the main chess variants, including 장기Janggi, หมากรุกMakruk, 将棋Shogi, Western, 象棋Xiangqi. These properties make GAN an ideal data-interchange format for storing actors of most abstract strategy board games.

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.

Notation for actors

The actor term is used for pawns, pieces (e.g., queen, rook, bishop, elephant, knight, lance, cannon), kings, stones, etc.

Keys are composed of two substrings: one for the name of the game and another for the abbreviation of the actor, joined by the “:” character; e.g., “go:stone” for a Go stone.

The structure of move instances can be unambiguously described with a pattern.

Resource representation

The BNF structure below shows the format of the resource:

<Actor>             ::= <Style> ':' <Piece>
<Style>             ::= <Abbr>
<Piece>             ::= [ "+" ] <PieceAbbr>
<PieceAbbr>         ::= [ "-" ] <Abbr>
<Abbr>              ::= <any-text>

Style

To distinguish the game an actor come from, a first substring is used. This substring begins with by a letter, and can then contains letters and/or numbers and/or underscores.

For the main chess variants, a single letter abbreviations can be used (e.g., “j” for Janggi, “m” for Makruk, “s” for Shogi, “c” for Western, “x” for Xiangqi).

For more exotic chess variants, we may use the full name to avoid possible naming collisions (e.g., “shatar” for Shatar, “dai_dai_shogi” for Dai dai Shogi).

So style is about the user interface of the game. Examples: “chess”, “shogi”, “xiangqi”.

But variant indicates the played variant. Could be used by engines to load rules, especially if the game is in progress. Examples: “Chess”, “ChuShogi”, “EuroShogi”, “Janggi”, “Makruk”, “Shogi”, “Xiangqi”.

Piece

To identify actors inside a given game, a second substring is used.

It should contain a letter, which could be followed by letters and/or numbers and/or underscores. If the actor is a King-like actor, the “-” prefix should be used; e.g., “c:-k” for a Western King.

For the main chess variants, the following letter abbreviations may be used:

Janggi actors
  • "-k" (General, called for Green and for Red)
  • "s" (Guard, called )
  • "e" (Elephant, called )
  • "r" (Chariot, called )
  • "p" (Cannon, called )
  • "m" (Horse, called )
  • "j" (Soldier, called for Green and for Red)
Makruk actors
  • "-k" (King, called ขุน)
  • "q" (Queen, called เม็ด)
  • "r" (Rook, called เรือ)
  • "b" (Bishop, called โคน)
  • "n" (Knight, called ม้า)
  • "p" (Pawn, called เบี้ย)
Shogi actors
  • "-k" (King, called for Sente and for Gote)
  • "g" (Gold, called )
  • "s" (Silver, called )
  • "r" (Rook, called )
  • "b" (Bishop, called )
  • "n" (Knight, called )
  • "l" (Lance, called )
  • "p" (Pawn, called )
Western actors
  • "-k" (King)
  • "q" (Queen)
  • "r" (Rook)
  • "b" (Bishop)
  • "n" (Knight)
  • "p" (Pawn)
Xiangqi actors
  • "-k" (General, called for Black and for Red)
  • "a" (Advisor, called for Black and for Red)
  • "e" (Elephant, called for Black and for Red)
  • "r" (Chariot, called for Black and for Red)
  • "c" (Cannon, called for Black and for Red)
  • "h" (Horse, called for Black and for Red)
  • "s" (Soldier, called for Black and for Red)

Through a promotion, the transformation of a promoted actor must be expressed by a different name; e.g., “c:r” (Western Rook) for a promoted “c:p” (Western Pawn). If the promoted actor remains the same, the “+” char must be used; e.g., “s:+b” (Shogi promoted Bishop) for a promoted “s:b” (Shogi Bishop).

King-like actors: Even if this is uncommon, it would be also possible to promote King-like actors; e.g., “FOO:+-K” for the promoted King of the Foo variant.

Naming the sides

The side of actors should be identified thanks to the case sensitivity; that is, based on differing use of uppercase for the bottom actors and lowercase for the top actors letters.

Due to history and culture, there are some differences in the naming of player’s side between chess variants. For example, in Western chess the player who start the game is called White and his opponent is called Black, while in Xiangqi chess the player who start the game is called Red and his opponent is called Black.

For the main chess variants, the following names are used:

  Player who moves first Player who moves second
Janggi Green Red
Makruk White Black
Shogi 先手Sente (or Black) 後手Gote (or White)
Western White Black
Xiangqi Red Black

To avoid confusion between sides and players, the player who moves first is referred to as bottom and the player who moves second is referred to as top. Similarly, the actors that each conducts are called, respectively, the bottom actors and the top actors.

Cross-variant compatibility:

Unlike other main chess variants, at Janggi the Green side which moves first is traditionally played from the north of the board. However, in order to keep things consistent and compatible, the sides of Janggi are flipped.

Example

Actor Side Recommended key
Western Pawn, White bottom C:P
Xiangqi Cannon, Black top x:c
Taikyoku Shogi Great Dragon, Gote top taikyoku_shogi:gd
Makruk Bishop, Black top m:b
Western King, White bottom C:-K
Shogi Rook, Sente bottom S:R
Shogi promoted Rook, Sente bottom S:+R
Xiangqi General, Red bottom X:-K
Janggi General, Red top j:-k
Dai Dai Shogi Phoenix, Sente bottom DAI_DAI_SHOGI:PH

Implementation
Informative References

This work is influenced by several documents.