opentafl-notation-spec.txt

OpenTafl Notation

Builds in part on the work of Damian Walker at http://tafl.cyningstan.com/.

Components in [] are optional. Components in <> are required. Strings inside quotation
marks are included literally, without the quotes. Components suffixed with ... repeat
as required. Strings outside of brackets or quotation marks are explanations. In
multi-line definitions, lines preceded by # are comments, and are not part of the record
being defined.

1. Positional Records

Position records record the arrangement of pieces as part of a board state. Position
records always start at the 'a' file on the first rank, no matter how the board is
displayed. If a given board shows a1 at the bottom left, the position record for that
board will appear upside-down: the first row record in the position record will be for
the first rank, even though the first rank is displayed on the bottom of the board.
Similarly, if a board shows a1 at the top right, the position record will appear flipped
horizontally.

	<"/"><<row-record><"/">>...

	row-record: [empty-space-count][taflman-symbol]
	empty-space-count: count of empty spaces since row start or last taflman.
	taflman-symbol: one of the following strings, defenders uppercase, attackers
	lowercase.
		"g": guard (neither captures nor can be captured)
		"m": mercenary/variegated man
		"k": king
		"n": knight (berserk)
		"c": commander (berserk)
		"t": taflman

Examples:

Brandub starting position:
/3t3/3t3/3T3/ttTKTtt/3T3/3t3/3t3/

Tawlbwrdd starting position (Bell layout):
/4ttt4/4t1t4/5t5/5T5/tt2TTT2tt/t1tTTKTTt1t/tt2TTT2tt/5T5/5t5/4t1t4/4ttt4/

Copenhagen or Fetlar diamond starting position:
/3ttttt3/5t5/11/t4T4t/t3TTT3t/tt1TTKTT1tt/t3TTT3t/t4T4t/11/5t5/3ttttt3/

2. Move Records

Spaces are given in a form of algebraic notation, starting at "a" and "1" and using
as many letters and numbers as required to capture the size of the board. No letters
or numbers are skipped. Letters should be lower-case.

	# This is the standard OTN move record:
	[taflman-symbol]<starting-space><move-type><ending-space>[capture-record][info-symbol]

OR

	# This is a standard algebraic tafl notation record, and is Damian Walker's
	# creation. Never uses taflman-symbol, only uses + and ++ for info-symbol,
	# to denote that the player who moved has either threatened to win or has
	# won.
	<starting-space><"-"><ending-space>[capture-record][info-symbol]

	<resignation-symbol>

	taflman-symbol: see Positional Records definition. Use for special pieces only.
	starting-space: the space the piece originated on.
	move-type:
		"-": regular move
		"^": jump (berserk)
		"=": berserk move (berserk)
		"^=": berserk jump (berserk)
	ending-space: the space the piece ended on.
	capture-record: 
		[<"x"><capture-location>[<"/"><capture-location>]...]
	capture-location:
		[taflman-symbol]<captured-space>
		Use taflman-symbol for special pieces only.
	info-symbol:
		"+": king vulnerable to capture.
		"-": king has at least one route to escape.
		"++": king captured, game ends.
		"--": king escapes, game ends.
	resignation-symbol: "---"

Examples:

Taflman moves:
e5-e8

Taflman moves and captures:
e5-e8xe9

Attacking side commander jumps:
ce6^e8

Defending side knight jumps, capturing jumped taflman and three destination-adjacent
taflmen:
Ne6^=e8xce7/ne9/f8/d8

Defending side knight makes berserk move:
Ne8=e4xe3

King moves to a position which threatens escape:
Ke5-e1-

King escapes:
Ke1-a1--

King may be captured next turn:
a3-e3+

King captured:
e3-e4++

3. Rules Records

Rules records describe the rules of a given game. The rules record below is broken into
multiple lines; multiple lines are permitted for human readability, but machine-to-machine
uses are encouraged to be single-line. No rule entry may be split into multiple lines.
The board size entry must come first, and the starting position must come last. Ordering
of rule entries in between doesn't matter.

Explanatory notes for each rule entry are given below the definition, along with default
values. Rule entries may be left out if unnecessary.

The explanatory notes inside the specification are not part of the specification, and
are present only for organizational purposes.

	# The rules record starts with the board size record.
	<board-size>

	# These rules concern general rules of the game.
	[<"esc:"><escape-type>] [<"surf:"><yes-no>] [<"atkf:"><yes-no>] [<"tfr:"><threefold-rule>]

	# These rules concern piece strengths and movement types.
	[<"ka:"><yes-no>] [<"ks:"><king-mode>] [<"kj:"><jump-type>]
	[<"nj:"><jump-type>] [<"cj:"><jump-type>] [<"mj:"><jump-type>]

	# These rules concern special spaces on the board.
	[<"cor:"><space-list>] [<"cen:"><space-list>]
	[<"afor:"><space-list>] [<"dfor:"><space-list>]
	[<"corh:"><piece-type-list>] [<"cenh:"><piece-type-list>]
	[<"cenhe:"><piece-type-list>]
	[<"aforh:"><piece-type-list>] [<"dforh:"><piece-type-list>]
	[<"corp:"><piece-type-list>] [<"cenp:"><piece-type-list>]
	[<"aforp:"><piece-type-list>] [<"dforp:"><piece-type-list>]
	[<"cors:"><piece-type-list>] [<"cens:"><piece-type-list>]
	[<"afors:"><piece-type-list>] [<"dfors:"><piece-type-list>]
	[<"cenre:"><piece-type-list>] [<"corre:"><piece-type-list>]
	[<"aforre:"><piece-type-list>] [<"dforre:"><piece-type-list>]

	# These rules concern shieldwall and edge fort formations.
	[<"sw:"><shieldwall-mode>] [<"swf:"><yes-no>] [<"efe:"><yes-no>]

	# This rule concerns Linnaean capture.
	[<"linc:"><yes-no>]

	# These rules concern berserk mode.
	[<"ber:"><berserk-mode>]

	# The rules record ends with the starting position entry.
	<starting-position>
	OR
	<inverted-starting-position>

		board-size: <"dim:"><size>
			board size is the length of the side of the board.
		escape-type:
			"c": corner
			"e": edge
		threefold-rule:
			"i": ignore
			"d": draw
			"w": player who moves into the threefold repetition wins
			"l": player who forces the threefold repetition wins
		yes-no:
			"y": yes
			"n": no
		king-mode:
			"s": strong
			"c": strong on or adjacent to center, weak elsewhere
			"m": middleweight
			"w": weak everywhere
		jump-type:
			"n": no jumps
			"r": restricted jumps: only to or from center, corners, or 
			     friendly fortresses
			"j": jump over enemy pieces: no capturing
			"c": jump over enemy pieces: capturing
		space-list:
			[<space><",">]...
		piece-type-list:
			[<taflman-symbol>]...

			Ordering has no semantic meaning, but the preferred order 
			is 'tcnkmgTCNKMG'.
		shieldwall-mode:
			"n": no shieldwall capture
			"w": weak shieldwalls, corners may not close a shieldwall position
			"s": strong shieldwalls, corners may close a shieldwall position
		berserk-mode:
			"n": no berserk moves allowed
			"c": berserking piece must capture if available
			"m": berserking piece must move
		starting-position: <"start:"><position-record>
			The value of the starting position rules entry is the positional record
			corresponding to the start position.
		inverted-starting-position: <"starti:"><inverted-position-record>
			The value of the inverted starting position rules entry is the
			positional record corresponding to the start position with its rows in
			reverse order. See the explanatory note for more details.


Explanatory notes:
	dim: 
		(dimension) must be present.
	esc:
		(escape) defaults to "c" (corner escape)
	surf: 
		(surrounding fatal) if a side is surrounded entirely by pieces from the other
		side, should that side lose? Defaults to "y" (yes).
	atkf: 
		(attackers first) should the attacking side go first? Defaults to "y" (yes).
		If "n", the defenders move first.
	tfr:
		(threefold repetition) what should happen in the case of a threefold repetition?
		if "w", the player who moves into the threefold-repeated board state wins (that
		is, the player forcing the repetition loses). If "l", the player forcing the
		repetition wins (that is, the player who moves into the threefold-repeated board
		state loses). If "d", the game is a draw (default). If "i", threefold repetitions
		are ignored.
	ka: 
		(king armed) does the king participate in captures? Defaults to "y" (yes).
		If "a" (anvil-only), the king can be captured against, but cannot move to make a
		capture. If "h" (hammer-only), the king cannot be captured against, but can move
		to make a capture. If "n", the king never participates in captures.
	ks: 
		(king strong) does the king need to be surrounded on four sides to be captured? 
		Defaults to "s" (strong). If "w", the king need only be surrounded on two sides.
		If "c", the king is strong on or adjacent to the throne, but weak elsewhere on
		the board. If "m", the king is strong, but can be captured against the board
		edge. (More precisely, the king is captured if all spaces adjacent to him are
		hostile.)

		"y" is equivalent to "s", and "n" is equivalent to "w", for backward
		compatibility.
	kj: 
		(king jump) can the king jump? Defaults to "n" (no).
	nj: 
		(knight jump) can the knight jump? Defaults to "c" (capturing jumps).
	cj: 
		(commander jump) can the commander jump? Defaults to "j" (non-capturing jumps).
	mj:
		(mercenary jump) can the mercenary jump? Defaults to "n" (no).
	gj:
		(guard jump) can the guard jump? Defaults to "n" (no).
	spd:
		(speed limits) the speed limit for the game. Defaults to "-1", no speed limit
		for any piece. Several options are available: a single number will set the
		speed limit for all pieces. Two numbers, separated by commas, will set the
		speed limit for attackers and defenders, respectively. Finally, ten numbers,
		separated by commas, will set the speed limits for each piece type individually,
		in standard tcnkmTCNKM order.

		If the speed limits list is only eight items long, the items apply to taflmen,
		commanders, knights, and kings, ignoring mercenaries, for backwards compatibility.

		e.g.:
		spd:-1 - no speed limit
		spd:4 - all pieces move up to 4 spaces per turn
		spd:3,4 - attackers move up to 3 spaces, defenders move up to 4 spaces
		spd:1,1,1,1,1,1,1,1,1,1,1,2 - all pieces but the king move 1 space per turn,
			king moves 2. Speed arrays of length 8 and 10 are also accepted, leaving
			out entries for mercenaries and guards, for backward compatibility with
			earlier versions of OpenTafl.
	cor: 
		(corner spaces) a list of spaces to treat as corner spaces, useful for e.g. alea
		evangelii with larger corner forts. Defaults to "default": the four physical
		corner spaces.
	cen: 
		(center spaces) a list of spaces to treat as the center space. Defaults to
		"default": the physical center space.
	afor: 
		(attacker fortresses) a list of spaces to be treated as attacker fortresses.
		Defaults to "". If empty, no spaces will be treated as fortresses.
	dfor: 
		(defender fortresses) as attacker fortresses.
	corh:
		(corner hostile to...) a list of piece types to which the corner spaces are
		hostile. Defaults to "tcnkmTCNKM" (all pieces).
	cenh:
		as corh. Defaults to "tcnkm" (all attacking pieces).
	cenhe:
		(center hostile when empty) as corh. Defaults to "tcnkmTCNKM" (all pieces).
	aforh:
		as corh. Defaults to "TCNKM" (all defending pieces).
	dforh:
		as corh. Defaults to "tcnkm" (all attacking pieces).
	corp:
		(corner passable by...) a list of piece types which can move through the corner
		spaces. Defaults to "K" (king only).
	cenp:
		as corp. Defaults to "tcnkmTCNKM" (all pieces).
	aforp:
		as corp. Defaults to "tcnkmTCNKM" (all pieces).
	dforp:
		as corp. Defaults to "TCNKM" (all defending pieces).
	cors:
		(can stop on corner...) a list of piece types which can stop on the corner
		spaces. Defaults to "K" (king only).
	cens:
		as cors. Defaults to "K" (king only).
	afors:
		as cors. Defaults to "tcnkmTCNKM" (all pieces).
	dfors:
		as cors. Defaults to "TCNKM" (all defending pieces).
	corre:
		(can re-enter corner; i.e. enter corner from outside) a list of piece types
		which can enter the corner spaces when starting on a non-corner space. Defaults
		to "tcnkmTCNKM" (all pieces).
	cenre:
		as corre. Defaults to "tcnkmTCNKM" (all pieces).
	aforre:
		as corre. Defaults to "tcnkmTCNKM" (all pieces).
	dforre:
		as corre. Defaults to "tcnkmTCNKM" (all pieces).
	sw:
		(shieldwall mode) Defaults to "n" (none).
	swf:
		(shieldwall flanking required) May a shieldwall capture only be made by a piece
		moving to close one of its flanks (that is, moving to the edge?) Defaults to "y"
		(yes). If "n", any move that results in a closed shieldwall position against an
		edge will capture the surrounded pieces.
	efe:
		(edge fort escape) Does the king's side win if he is surrounded against the edge
		of the board by friendly pieces, with at least one move available, and with no
		enemy pieces inside the fort? Defaults to "n" (no).
	linc:
		(Linnaean capture) If enabled, a defender next to the king when the king is on
		the throne and surrounded on the other three sides by attackers may be captured
		against the throne.
	ber:
		(berserk mode) Defaults to "n" (none).
	starting-position:
		must be present if inverted-starting-position is not.
	inverted-starting-position:
		must be present if starting-position is not.

		Ordinary position records start counting at a1, moving from left to right
		and from rank 1 to rank N. Under the ordinary convention, where the space
		labeled a1 is at the bottom left, this means that reading the position
		record from start to finish gives the board position from bottom to top,
		which is difficult to visualize. The inverted position record is the
		regular position record with its rows in reverse order, so that the first
		row entry in the position record corresponds to the leftmost space of the
		topmost row. Reading the inverted position record from left to right
		gives the board state in left-to-right, top-to-bottom format.

		For this reason, tafl engines which display space a1 at the bottom left
		should create rules records for human consumption using the starti tag
		instead of the start tag.

Examples:

Fetlar:
11x11, defenders go first, all others as default.

dim:11 atkf:n start:/3ttttt3/5t5/11/t4T4t/t3TTT3t/tt1TTKTT1tt/t3TTT3t/t4T4t/11/5t5/3ttttt3/

Copenhagen:
11x11, defenders go first, shieldwalls on and may be formed against corners, edge
escapes on.

dim:11 atkf:n sw:s efe:y start:/3ttttt3/5t5/11/t4T4t/t3TTT3t/tt1TTKTT1tt/t3TTT3t/t4T4t/11/5t5/3ttttt3/

Berserk:
11x11, defenders go first, surrounding not fatal, king can jump into throne and 
corners, berserk mode on for capturing moves only. Note 'c'ommanders and k'N'ight 
in the starting position.

dim:11 surf:n atkf:n kj:r ber:c start:/3ttttt3/5c5/11/t4T4t/t3NTT3t/tc1TTKTT1ct/t3TTT3t/t4T4t/11/5c5/3ttttt3/

Brandub:
7x7, weak king, attackers go first, center doesn't become hostile and isn't hostile to
anyone, all pieces may pass through the center.

dim:7 ks:n cenhe: cenh: start:/3t3/3t3/3T3/ttTKTtt/3T3/3t3/3t3/

Sea Battle 9x9:
9x9, escape to the edges, king unarmed, center and corners not hostile, all pieces may
move through and stop on the center and corners.

dim:9 esc:e ka:n cen: cenhe: cor: start:/3ttt3/4t4/4T4/t3T3t/ttTTKTTtt/t3T3t/4T4/4t4/3ttt3/

4. Game Records
	[tags]
	<rules-tag>
	
	# This pattern should be separated from the header by newlines.
	# This pattern repeats for the whole game. The final element may omit
	# one move record, if the game ends. The host engine should display
	# commentary, if provided, alongside a loaded game.
	<<turn-number> <move-record> <move-record> [move-record]...>
	[<first-half-commentary>[<"|"><more-commentary>]...]

	tags: 
		none, some, or all tags may be included, at the compiler's choice.
		Tags may not contain newlines. Each tag should be placed on its own
		line. The rules tag must always be the final tag.
		[<"["><tag-type><":"><tag-value><"]">]
		
	tag-type:
		"event": 
			tournament or match event name
		"site": 
			location of game, in city, country format, or as a URL, for online
			games
		"date": 
			date of game: YYYY.MM.DD
		"round": 
			round in tournament or match
		"attackers": 
			player of the attackers, in customary format
		"defenders": 
			player of the defenders, in customary format
		"result": 
			"1" (attackers win), "0" (draw), "-1" (defenders win), or "?" (other)
		"annotator": 
			person providing game notes, in customary format
		"compiler": 
			person assembling this file, in customary format
		"time-control": 
			<main-time-seconds> [<overtime-periods><"/"><overtime-length] [<increment-length><"i">]
			e.g. "3600 30/3 3i": 1 hour, 3 30-second overtimes, 3-second increment
			the time allotted per player for this game.
		"time-remaining":
		    <<main-time-seconds> [<overtime-periods><"/"><overtime-length]><", "><<main-time-seconds> [<overtime-periods><"/"><overtime-length]>
		    the time remaining at the end of this game record; attackers first,
			then defenders.
		"termination": 
			human-readable statement on how the game ended, possibly containing
			more information than the result tag; e.g. 'Black resigned'
		"variant":
			name of the tafl variant being played
		"start-comment":
		    a comment to be displayed at the start of the game, or whenever the player navigates
		    back to the start of the game
		"puzzle-mode":
		    <"none"|"loose"|"strict">

		    (optional) whether this game record defines a puzzle. If it does define a puzzle,
		    OpenTafl will prompt the user, when this game record is loaded, to choose whether
		    to load it as a replay or a puzzle.

		    A puzzle is a game record which contains, minimally, some number of moves,
		    potentially including attached commentary.

		    "none" means that the replay will be loaded as a standard replay. "loose" means
		    that the player may make any move. OpenTafl will alert the player if he makes a
		    move which is not contained in the game record. "strict" means that OpenTafl
		    will only accept moves contained in the game record.
        "puzzle-prestart":
            <move-address>

            (optional) where the replay should begin displaying this puzzle. Need not be
            present.

            Between puzzle-prestart and puzzle-start (see below), OpenTafl will only allow
            the 'next' and 'previous' commands. You can use puzzle-prestart to define a
            region of introductory commentary before the puzzle begins in earnest.
        "puzzle-start":
            <move-address>

            (optional) where the puzzle begins. From puzzle-start, OpenTafl will only
            allow the 'variation' and 'previous' commands to navigate the game, according
            to the puzzle mode defined in the puzzle-mode tag.

	rules-tag:
		<"[rules:"><rules-string><"]">

		rules-string is an OTN rules string.
	
	position-tag:
		<"[position:"><position-string><"]">

		optionally, a starting position for the game. If a position tag is provided,
		the game starts at that position, instead of the starting position in the
		rules string.

	turn-number:
		for moves in the principal line of play, the number of times both players have
		moved, followed by a period, starting at '1.'

        For moves in a variation, the turn number is the variation address, which
        follows this pattern: first, the address of the move, followed by a variation
        number, followed by 1a, repeating as necessary to uniquely identify a given
        line of play. If a variation starts on the second or later move in a given
        turn, substitute '.....' for the moves which match the moves in the
        variation's parent. Consider these examples:

            1a.1.1a. h5-h3 h1-h2
            From right to left, this is the first move in the first variation off of
            the first move in the first turn.

            3. h2-a2 b1-b2
            3b.3.1a ..... a4-a3xa2
            From right to left, this is the first move in the third variation off of
            the second move in the first turn. Note that the address of the first move
            in this variation is, in actuality, 3b.3.1b: the first move in the
            variation is the second move in the turn. In both cases, h2-a2 is the first
            move of the turn. The variation begins with the response.

            Considering variations as turns, as the OpenTafl Game Notation format does,
            makes for greater readability and easier compilation by hand, so this
            format addresses the turn, at 3b.3.1a, instead of the initial move.

            4a.5.4c.2.2a
            This is a complicated example, and is best read right to left, as is
            ordinarily the case with variation addresses. This is the first move in
            the second turn (2a) of the second variation (2) off of the third move
            of the fourth turn (4c; this must be a game allowing berserker moves)
            in the fifth variation (5) off of the first move in the fourth turn
            of the principal line (4a).

        Note that this distinction is critical: the principal line of play must
        not have move index letters, but variations must include them.
	
	move-record:
		an OTN move record. For variations which start on the second or later
		move of a turn, may be '.....'.

	first-half-commentary:
		comment on the first move of this turn. By convention, if the commentary
		text begins with a clock specification string in the same syntax as used
		for the time-control tag, OpenTafl will omit the clock specification from
		the displayed commentary, and display the time given by the clock
		specification in the clock display. By additional convention, if the game
		has been loaded as a puzzle, OpenTafl will hide any text surrounded by
		"(hint:" and ")" (e.g. "(hint:This is an example hint.)"), displaying it
		only if the user asks for a hint.

		The comment attached to a move will be displayed after the move has been
		played. To display a comment at the start of the replay, use the
		start-comment tag described above.

	more-commentary:
		comment on the second move of this turn (or on any additional moves this
		turn, for variants including the berserk rule). The same clock display
		convention applies.