Clone wiki

Arimaa game viewer / doc_flexible_format

FAN - Flexible Arimaa Notation

FAN is a new format for Arimaa game (and its possible variations). The specification is not frozen yet, so don't rely on it.


  • As much as human readable as possible (with whitespace formatting)
  • Variations of unlimited depth
  • Comments
    • for board positions (before move)
    • for moves
    • for single steps, i.e. concrete movement of a piece
  • Marking of board positions
    • supports future markings
      • which means that implementations need to be updated if new markings should be included
      • also version of the notation is needed

Informal description


  • Magic string that identifies the notation from other file/notation formats, e.g. FAN31415926.
  • Version of notation
  • Game variant [if not mentioned, default=Arimaa]

At the beginning, there is header with optional info. The following should be supported by implementations (but not required) and other additional name-value pairs can be added for extra info.

  • name of the players
  • game id in server
  • time settings
  • list of people who have created the variations and made comments

Basic content

The actual moves with decoration of comments and moves. If there is no comments and moves, and variations haven't been made, the notation should be similar to basic notation.

5g Hc3e Ea1e as an example, 5 is move number and g means gold.


Alternative moves, i.e. variations, are added after the move which they want to alter. Special symbols are used to start and end a variation. Variation can also have variations inside itself.

Variation's first move is with id, e.g. 3g (3rd move by gold) even though it could be inferred. For humans that would be unfortunate if the text is linearly formed. It could be later changed to be optional. The following have some senseless steps that might even be illegal but show how the syntax works.

Here's an example for one move variation:

  • 3g rd6s rd5w rc5s rc4w [ 3g m5n hb7 rc5s rc4w ]

A different example that has two variations for one main move:

  • 5g rd6s rd5w Md6s ca1e [ 5g hb7 m5n hb7 rc5s ] [ 5g dh9s m5n hb7 rc5s ]

From here on, I break the notation visually in many lines. The previous would be:

  • 5g rd6s rd5w Md6s ca1e
    • [ 5g hb7 m5n hb7 rc5s ]
    • [ 5g dh9s m5n hb7 rc5s ]
  • 5s (... here main move continues)

Here's a move with variation that has continuation move (turn changes).

  • 5g rd6s rd5w Md6s ca1e
    • [ 5g hb7 m5n hb7 rc5s
    • 5s dh9s m5n hb7 rc5s ]
  • 5s (... here main move continues)

Here's an example that has a variation for a variation. Notice that the turn changes.

  • 5g Rd6s Rd5w Md6s Ca1e
    • [ 5g Hb7 Dh9s Cb4n Ca4w
    • 5s ca1e rd6s rd5w Md6s
      • [ 5s hb7 m5n hb7 rc5s ] ]

I decided that a variation to a variation without a continuation move is not allowed, since it is superfluous (it's the same case as two alternatives for a single parent). I mean this is prohibited:

  • 5g Rd6s Rd5w Md6s Ca1e
    • [ 5g Hb7 Dh9s Cb4n Ca4w
      • [ 5g hb7 m5n hb7 rc5s ] ]

Notice that all moves are for turn 5 of gold.


Comments can be made for moves, positions or single steps.

Commenting a position should be thought as commenting the position before move after it, including variations.

Commenting a move means to comment move to be made, so if you are at last position after all moves, you cannot comment moves but position. Each alternative move (variation) can be commented.

The symbol " is used to start and end a comment. The first example is how to comment a position.

  • 5g "Gold is in trouble" rd6s rd5w Md6s ca1e

The next show how to comment a move

  • 5g rd6s rd5w Md6s ca1e "Camel should be instead sacrificed" 5s...

So the comment for position goes immediately after the move id and the comment to the move after all the steps.

Commenting can be done also for variation steps and positions:

  • 5g rd6s rd5w Md6s ca1e [ 5g "This show's how top player calmly avoids trouble" hb7 dh9s "Superb idea!" Md6s ca1e ]

You are not allowed to use " inside a comment (no escaping rules).

Marking a position

One can mark a position (also for steps) by adding @ symbol with postfix of the marking. At the moment only one class of marking is possible but the notation supports arbitrary length so long as you but it all in a character sequence with no whitespace. Here's an example:

  • 5g @x4d=red rd6s rd5w Md6s ca1e

This example shows how we can encode arbitrary information (yes, comments could be done with this, but syntactic convenience for humans overrides elegancy).

We can define for different versions how to interpret a value like xd4=A. In our case, this simply means that it's a coordinate (x) d4 and the square should be marked with A. The actual viewer could show it as an A or with colorized A, or whatever. Depends what is needed. The notation in this case is mostly meant to offer extensibility so that even if older viewer's read the new version, it could be shown without the marks if it does not know how to interpret it.

Formal notation

INCOMPLETE: setup_variation does not currently support normal move continuations.

The following definition of FAN uses:

  • ? for optional, * for 0 to unlimited amount of occurence and + for 1 to unlimited amount of occurrences, # for comment, | for alternative
  • comma (,) is for concatenation of values, so that A,B would be AB
  • LIT(foo) means that foo is a literal, and it generalizes for LIT(a_1|a_2...|a_n) where a_k, k > 1 is literal
  • ( and ) for grouping, e.g. (FOO bar)* for FOO bar, from 0 to n occurrences, e.g. FOO bar FOO bar
# if header_req is missing, implementations of course could try out whether the notation matches but it is not recommended
  VERSION := integer
  VARIANT := string # default is literal 'arimaa' (case insensitive)
  GAMEID := integer    # game id in server
  PLAYERS := string LIT(-) string    # name of the players
  TIME-SETTINGS := ??????????  # this is not decided yet
  AUTHORS := string
  SETUP_STEP := PIECE_ID,COORDINATE  # should we allow comment here?
  POSITION := TURN_ID COMMENT? MARKING* MOVE_CONTENT VARIATION*  # comment is about the position
  TURN_ID := integer,(LIT(g)|LIT(s))  # move number with turn
  MOVE_CONTENT := STEP_EXT* COMMENT?  # comment about move
  VARIATION := [ MOVE NORMAL_BODY ]   # note the recursion and disallowing a variation for first move in a variation
  # although MOVE could be replaced with MOVE_CONTENT since TURN_ID can be inferred, it's useful for human readability

  MARKING := LIT(@),string
  COMMENT := LIT("),string,LIT(")
  PIECE_ID := LIT(e|m|h|d|c|r|E|M|H|D|C|R)
  COORDINATE := LIT([a-h]),LIT([1-8])   # from a to h, from 1 to 8
  DIRECTION := LIT(e|w|n|s)

There is a bit ugly corner case in the generated possibilities which we deal as a special case. The problem comes from the fact that we use small amount of literals to differentiate different types of values, and since we use positional inference to deduce where each comment belongs to. Specifically, the possibility of commenting a last step in a move but not commenting the move, or vice versa, must be dealt with special rule. Also a bit awkward is when both the step and move are commented, since there will be two comments side by side. However, it won't cause any ambiguity or special resolution rules.

Here's an example for comment that cannot be inferred to be of step or of move without extra knowledge:

  • 5g Rd6s Rd5w Md6s Ca1e "cat is now well positioned"

Here's simple way to know where the comment belongs to:

  • If there is no comment after step, there is nothing to be resolved
  • If there is only one comment after last step, it belongs to the move *The special case*
  • If there is two comments, first belongs to step, the other to the move

With this special rule, the above example would have the comment tied to the whole move.

If you want to comment the last step but not the last move, you should put a dummy, empty "" after the step comment. e.g.

  • 5g Rd6s Rd5w Md6s Ca1e "last step bad" ""

* alternative possibility * Comments for steps could be put into ' or two " . This would be nicer for humans.

Implementations won't have this kind of problem with markings, since they are not made at move but position. Luckily that, since otherwise we would need another symbol since there could be multiple markers for one step/move.