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:

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:-

"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:

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:

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:

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:

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:

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.

"d" omission

If the final action is "d", that can be omitted.

"c" omission

If the first action is "c", that can be omitted.

"-" omission

If the first action is "-", then it can be omitted if the tile drawn is specified.

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.

🗼 gemini://