Mahjong game notation
This is a sketch of a file format that can be used to record a game of mahjong. I developed it for use for my own variant, but it is general enough to be used for most variants of mahjong.
The goals of this file format is:
- To be easy to read and write, both by humans and by machines, but with humans coming first;
- To be forgiving in terms of white-space and similar; and
- To be intelligible to most players the game with minimal training.
General language highlights
The file format is generally paragraph-oriented. That means that two newlines are used to separate semantically different objects, and single newlines are the same as a single space.
One should constrain the length of any line to a reasonable length. 80 columns is the convention, but one may choose any number from that to 100.
Comments must span entire lines and begin with :. Example follows.
: This is a comment. :This is also a comment. : Comments are the only line-oriented item.
The next type of content is the metadata line. They are identified by any of the regexp `[A-Za-z_-]+:'. Example follows:
Item: 1
Thing: This is a metadata line.
This is the continuation of the previous metadata line.
It is combined together because the line starts with at least one space.
I aligned this to the first word in the line,
but only the one space at the start of the line is necessary.
Another: This is a new piece of metadata.
Item-with-spaces: This is yet another piece.
This is not part of "Item-with-spaces"
because two newlines separate that from itself.
The use of this type of line is to, for instance, record hands, score, player names and other game information that is not part of the actual gameplay.
Finally, we have the game block. This is a single paragraph identified by a number followed by a full stop, at the start of the line, and continues until the end of the paragraph. For example:
1.-,4m 2.-,ft 3.-,N 4.-,7s This is a comment inside the game. 5.9as,E 6.E,5m 7.-,1t 8.-,1t
Game block
The game block consists of words, which may either be the actions of a player, or a comment. A word is any combination of non-space or -newline characters. Multiple space or newline characters are treated as if it was one.
A word is a player move if it starts with:-
- a number and a full stop;
- three dots, or the ellipsis character "…";
- a number, then either three dots, or the ellipsis character "…".
"Number" means any combination of digits, including items that don't look like numbers like "00".
All other words are comments. Multiple comment words in a row are combined into a single comment, with the words being combined with one space separating them.
A player move that uses the three dots or the ellipsis character is considered to be a continuation of the previous game action. For example:
10.- A mistake; should not have drawn here. 10...4m 11.-,9m
is the same as this, except for the position of the comment:
10.-,4m A mistake; should not have drawn here. 11.-,9m
About the game action
The game action itself consists of a number of other components. In EBNF:
player move = game number, ("." | "..." | "…"), [player], action, {",", action} ;
player = "E" | "S" | "W" | "N" ;
action = move | move, tile | tile ;
move = "-" | "d" | "c" | "P" | "K" | "W" ;
tile = ? any tile notation representing 1 or 2 tiles ?
Due to the nature of the game, every player move is composed of at least two actions, with the exception of the first one consisting of just the discarded tile, and the possible exception of the last one which may consist of just the player and "W".
Action components
Here are the description of the game actions, and what they require.
Action number
This is the number that appears before the full stop. It is immaterial, but by default it starts from 1 and increases by 1 for each passing of the turn. It is allowed to simply number them all 0, for example.
The player
The player that performs the play action is noted as his seat. For instance, the game usually starts like this:
1.Ed4m for example
Action: -
The action - means "draw a tile from the wall". If the metadata block "Starting-wall:" is given, then no tile is specified; otherwise, it consists of the tile drawn. Examples:
- "10.W-" means "at turn 10, player West draws from the wall"
- "10.W-5m" for "at turn 10, player West draws a 5m from the wall".
It may appear only as the first action.
Action: d
The action d means "discard this tile into the waste". One tile must be specified with this action. For example:
- "9...Sd4m" means "at turn 9, player South discards a 4m"
- "1.EdE" means "at the first turn, player East discards an East tile".
It may appear only as the last action.
Action: r
The action "r" means "discard this tile into the waste and declare riichi". It is only used for Japanese mahjong. The semantics is the same as "d".
Action: c
The action c means "combine the previous discarded tile with the two tile specified to create a sequence". For example:
- "24.Ec34m" means "at turn 24, player East calls the previous discarded tile to form a run with 3m, 4m already in his hand".
- "24.NcZas" means "at turn 24, player North calls the previous discarded tile to form a run with Z, as already in his hand".
It may appear only as the first action.
Action: P
The action "P" means "combine the previous discarded tile to create a trip". It may appear only as the first action.
Action: K
The action "K" means "make a quad". It comes in two forms.
If it is the first action, it means "the player takes the previous discarded tile to form an open quad". If it is not the first action, it means "the player takes the drawn tile and adds to either an exposed trip to form an 'added quad', or all four tiles are taken from the closed part to form a 'hidden quad'; in either case an additional tile is drawn from the back". This can be repeated multiple times.
For example:
- "0.EK" means "the East player takes the previous discarded tile to form an open quad".
- "0.EK,K5m,K2m" means "the East player takes the previous discarded tile to form an open quad, draws from the back, forms another quad using the four copies of 5m, draws again, and then forms a third quad with the four copies of 2m."
Action: W
The action "W" means to declare a win. It also comes in two forms.
If it is the first action, then the winning tile is the last discarded tile, a "ron". If it is the last action, then the winning tile is the last drawn tile, a "tsumo". There can only be 1 W in the entire game, but there may also be 0. If there is one, that W is the last action in the game.
For example:
- "56.NW" means "on move 56, the North player has taken the last tile for the win".
- "44.S-,W" means "on move 44, the South player has won by self-draw".
- "70.E-,K3m,W" means "on move 70, the East player drew a tile, made a quad using the 3m tile, drew, and won on that drawn tile".
Abbreviation of game action
Player omission
The game always starts with East, so one does not need to indicate the player unless there is a call for a trip, a quad or a win. If the game fragment does not start at East, then retain the player.
- "1.EdE" can be written "1.dE"
- "4.S-,d4m 5.W-,dS" can be written "4.S-,d4m 5.-,dS"
- "9.N-,dxs 10.WP,dbm" cannot be abbreviated using this rule.
"d" omission
If the final action is "d", that can be omitted.
- "1.dE" can be written "1.E".
- "4.S-,d4m 5.-,dS" can be written "4.S-,4m 5.-,S"
"c" omission
If the first action is "c", that can be omitted.
- "55.Ec49m" can be written as "55.49m".
"-" omission
If the first action is "-", then it can be omitted if the tile drawn is specified.
- "7.-4m" can be written as "7.4m".
There is in principle an ambiguity between a single move consisting of a discard and a the first part of a move that involves drawing a tile. This is not a problem in real notation because only the first move can consist only of a discard.