Betza notation

Betza notation and XBoard

This page describes Betza's notation system for piece moves, so far as relevant for the XBoard project. XBoard uses this notation to allow engines to inform it on the moves of non-standard pieces in Chess variants, so that features like target-square highlighting, legality checking and SAN generation can work with their usual accuracy even in the presence of such pieces. The current XBoard (4.8.0) only implements a simple form of Betza notation. Future versions might have full understanding of Betza 2.0. But the latter is already of relevance now, as it is used to describe the moves of the more complex pieces on the web pages that describe the rules of the variants supported by XBoard.

The basics

Atoms - Betza notation describes Chess pieces by dividing their moves into groups with the same board step, such as all 8 moves of the Knight. By default these moves can be made as capture as well as non-capture. Such a group of symmetry-equivalent moves ('atom') is indicated by a single capital, usually the common abbreviation of the piece that has those moves, and only those moves (see table 1). The atom O is sometimes used for null move (staying in place, but consuming the turn), and U for 'universal leaper' (able to leap to every square on the board except the one it is on), but XBoard 4.8.0 does not implement those. If a piece can do several unrelated moves, it is described by a concatenation of the descriptions of each group.

Table 1: moves of atoms
G Z C H C Z G     W = Wazir     (1,0)
Z A N D N A Z     F = Ferz      (1,1)
C N F W F N C     D = Dabbaba   (2,0)
H D W * W D H     N = Knight    (2,1)
C N F W F N C     A = Alfil     (2,2)
Z A N D N A Z     C = Camel     (3,1) older notation J
G Z C H C Z G     Z = Zebra     (3,2) older notation L

Range - To describe sliders, the letter indicating the atom must be followed by a number, which then indicates the maximum number of times the step described by the atom can be repeated in absence of obstacles. By convention a 0 here means 'without limit'. (Older versions of the notation duplicated the atom name for this, but XBoard does not understand that.) Thus N0 (obsolete NN) describes the Nightrider, repeating Knight steps in the same (but arbitrary) direction. There are some shorthands for common expressions: B, R, Q and K describe the orthodox Chess pieces, which formally should have been written as F0, W0, F0W0 = BR and FW, respectively. This way an Archbishop can be written as BN. (Or NB; the order has no significance.)

Directional modifiers - If a piece does not have all the 8 moves belonging to the atom (or 4 for purely diagonal or orthogonal moves), the subset of it can be indicated by 'directional modifier' prefixes. These are lower-case letters indicating directions or sets of directions: f, b, r, l, v, s, h for forward, backward, right, left, vertical (f+b), sideway (l+r), and half, respectively. Note that the exact meaning of each of these depends on the type of atom; for orthogonal moves f, b, r and l each specify a single move, for diagonal and oblique moves they specify move pairs. To subdivide the pairs, a second directional modifier for the perpendicular direction must again be written in front of the first. So lfN corresponds to the move Ng1-f3, the left-most move of the forward pair. Combinations like 'fh' can only be used on oblique moves, and do the opposite: the 'h' extends the meaning of 'f' to all 4 moves that have a component in that general direction. Directional modifiers that do not combine to a single direction imply that moving in each of the corresponding directions is allowed. E.g. frW can move one step forward, or one step right (but not backward or left). If what was parsed upto now can combine with the next letter, it will. To avoid unwanted combining of adjacent directional modifiers to a single direction, they sometimes need to be doubled, e.g. ffrrN is a Knight with the two forwardmost and rightmost moves.

Table 2: directional modifiers
 K  N  K  N  K     Outer ring applies to 8-fold movers N and K
 N  F  W  F  K     Inner ring applies to 4-fold movers F and W
 K  W  *  W  K
 N  F  W  F  K
 K  N  K  N  K

 half-planes      right/left pairs   single directions       chiral
fh fh fh fh fh     lv lv  . rv rv     lf lf ff rf rf      . hl  . hr  .
fh  f  .  f fh     ll  .  .  . rr     fl lf  f rf fr     hr  .  .  . hl
 .  .  *  .  .      .  .  *  .  .     ll  l  *  r rr      .  .  *  .  .
bh  b  .  b bh     ll  .  .  . rr     bl lb  b rb br     hl  .  .  . hr
bh bh bh bh bh     lv lv  . rv rv     lb lb bb rb rb      . hr  . hl  .

                  forw/backw pairs  diam. pairs/quartets
lh lh  . rh rh     fs ff  . ff fs      .  v  v  v  .
lh  l  .  r rh     fs  .  .  . fs      s  .  v  .  s
lh  .  *  . rh      .  .  *  .  .      s  s  *  s  s
lh  l  .  r rh     bs  .  .  . bs      s  .  v  .  s
lh lh  . rh rh     bs bb  . bb bs      .  v  v  v  .

Modality modifiers - If a piece is 'divergent', i.e. it cannot both capture and non-capture with the same move, then a 'move modality' prefix will describe what the move can do (c = capture, m = non-capture). A Shatranj Pawn (which does not have initial double-push or e.p.) thus is fmWfcF.

Advanced modifiers

Jumping - The original Betza notation included a number of special-purpose modifiers, defined in a rather ad-hoc way to indicate certain aspects of common pieces that could not be handled by the basic system. 'Lame leapers' are pieces that can be blocked on squares they cannot move to, and are indicated by modifiers 'j' and 'n', for 'must jump' and 'non-jumping'. By default moves to non-neighboring squares can do both, as they completely ignore the state of other board squares, even those geometrically between their origin and destination. A Xiangqi Elephant would thus be nA, where a Shatranj Alfil is simply A. The weakness of these modifiers is that they are only unambiguously defined on purely diagonal or orthogonal atoms, as in other cases it is not clear what constitutes the path taken to reach the destination. In XBoard 4.8.0 'n' or 'j' are only testing a single intermediate square, exactly halfway, which should be considered broken for all atoms other than N, A, and D. As fractional steps are rounded towards zero, this happens to make nN the Xiangqi Horse. When (correctly) applied to atoms of longer stride, it can make sense to distinguish between prefixes 'j' (must jump one) and 'jj' (can jump many).

Hopping - Hoppers are pieces that must move over an occupied square (the 'platform') that they might be able to move to in other situations. Famous examples are the Xiangqi Cannon ('Pao', a Rook which must jump before it can capture), and the Grasshopper (a Queen that can only land on squares directly behind the first obstacle in its path). The modifier 'p' can prefix slider moves, and indicates that these moves can and must jump exactly one obstacle, so that the Cannon can be denoted as mRcpR. The modifier 'g' indicates a slider move that in a similar way can only continue a single step after hitting the obstacle, so that a Grasshopper is gQ. The more general case, where pieces could also change direction ('bifurcators') or stride after hopping the platform, could not be covered in the original Betza system without introducing new ad-hoc modifiers describing each case separately. XBoard 4.8.0 implements both 'g' and 'p'.

Specials - Other ad-hoc modifiers in the original Betza system are 'q' and 'z', for riders that move along curved and zig-zag trajectories. I.e. they take their consecutive steps not in the same direction, but with a fixed angle between them, rotating in the same direction on every new step for 'q', and alternating direction for 'z'. It is a bit ill-defined how exactly the direction changes; one assumes by the minimum amount, which depends on the atom. The prefix 'o' is used to indicate moves on a cylinder board, which would wrap around from the side edges. XBoard 4.8.0 does not implement the 'q' and 'z' modifiers, but it does implement 'o'.

XBoard-specific ad-hoc extensions and restrictions

En passant - Not in the original Betza system, but very much in the spirit of it, a prefix 'i' can be put on a move that is only allowed for 'virgin' pieces. Similarly, 'e' is a very useful additional move modality next to 'm' and 'c', indicating en-passant captures (which go to that empty square where the previous opponent's move could have been blocked due to an 'n' prefix, had it not been empty, and remove that moved piece as a side effect). These modifiers are implemented in XBoard 4.8.0, to allow accurate description of Pawns; a FIDE Pawn would be fmWfceFifmnD, which includes both the blockable initial double push ifmnD and the e.p. capture feF on top of the Shatranj Pawn. The actual creation of e.p. rights and removal of the victim is still done by the hard-coded logic for Pawn moves, however, irrespective of what you specify.

Castling - Unique to XBoard is a way to describe conventional castling with an O atom, where the following number indicates the number of steps the piece having this move takes in the direction of the corner. It implies that the corner piece then has to swing around it, and applies the usual restrictions on virginity of the corner piece, and not moving through check (if the described piece is royal, but currently XBoard only understands castling of Kings). Not writing a castling move on the King makes it keep its original castling for the current variant! To get a King that cannot castle in variants where it normally does, specify an initial position without castling rights.

Drops - The atom @ indicates a piece can be dropped from the hand. (Never mind how it got there!) Directional modifiers make no sense here, so the corresponding letters are reused to indicate other things. 'f' restricts the drop to board files that do not contain a piece of this type yet. Similarly 's' forbids a drop on squares the same color as where there already is such a piece, and 'b' even forbids the drop if there is already such a piece anywhere on the board. These modifiers can be duplicated to crank up the maximum to two pieces of the same type. XBoard 4.8.0 does not implement this atom, as it has its own hard-wired code for judging drops, separate from the move generator, and does not highlight possible drop squares. It aborts parsing the Betza string when it encounters it, so if it is included for future reference, it should better be the final atom.

A numeric suffix on the @, which normally would indicate a range, indicates the depth of the 'drop zone' measured in ranks, (default 1), starting at the back rank. A 'j' prefix means the back-rank itself is exempted. So in Crazyhouse Pawns would have j@7, the other pieces @8. In Shogi we have P:fWf@8, L:fR@8, N:fN@7, while other pieces would have @9.

Skipping - A 'j' modifier on a slider (Wn or Fn, as opposed to rider, which makes larger steps), indicates it skips the first square, irrespective of its occupancy. This overloading of the 'j' symbol is possible because the original meaning ('must jump') makes no sense on W or F.

Multi-leg - Newly proposed is the 'a' ('again') modifier, which indicates that the piece can do another move after its first one is completed. modifiers preceding 'a' apply to the first 'leg' of the move, whatever follows is describes the second leg. The direction and modality of the legs can thus be specified independently. (e.g. a Checker can capture on its first fF step, and then must move again in the same direction to an empty square, fcafmF). Directions for a continuation leg are indicated relative to the previous leg, where continuing in the same direction counts as 'forward'. So masR would be a Rook that can do two moves per turn ('a'), the second perpendicular to the first ('s'), where the first should be a non-capture, ('m'), and the second can both capture and non-capture, as usual. The continuation directions are specified in the (8-fold) K system even for 4-way atoms; when purely orthogonal or diagonal atoms get a direction they do not have, because it is intermediate to the directions they stand for, they are converted into each other for the remainder of that move. F interconverts with W, (and thus B with R), D with A and G with H this way. E.g. mafsR for a trajectory that starts orthogonal and then bends 45 degrees on any empty square reached that way.

For non-final steps there are more options for the modality that make sense than just mc: because the moving piece doesn't intend to stay on that square, it is not necessary to clean the latter out. We can also leave an occupant undisturbed, denoted by 'p', ('hop' or 'pass through'). Thus pasR would be a Rook that can turn a corner only at the point where it hits the first obstacle, while casR would be a Rook that can capture a foe, and then continue at 90-degrees, possibly for a second capture. Of course it is possible to combine modalities, like cpasR, which either captures the platform, or leaves it undisturbed. The 'a' can be applied multiple times; mamaK means three King steps arbitrary changing direction, traversing empty intermediate squares only, while it can capture (or just move to) the final square in the third step.

By default continuation legs go in all directions except exactly backwards. Default modality in non-final legs is 'm', i.e. the intermediate square must be empty. (So the leading 'm' in many of the preceding examples can actually be dropped, e.g. aaK.) The final leg follows the rules for single-leg moves, i.e. default modality mc, while 'p' has a slightly different meaning there. Note that a 'mp' modality on a non-final step makes it ignore the relay square completely. This can be used to glue leaper moves into longer leaps in a 'transparent' way, e.g. mpafN for a (2,4) leaper.

The modifier 'g' can be generalized to non-final legs in a similar way as 'p', the difference between the two (as always) being that the latter limits the range after the hop to a single step. Thus gQ = gafQ, just as pR = pafR. This can be generalized even further by making this work in the opposite direction as well, turning leapers into sliders when the range already was 1. This makes gafK a time-reversed Grasshopper, different from pafK = nAnD. The range is changed by interconvering FWK with BRQ after stripping off any explicitly written range, while on other atoms the written or implied range will be changed from 1 to infinite and from not-1 to 1. This makes gafsR behave differently from gafsW0: the first turns into fsW = fF and must thus land directly (diagonally) behind the platform, but the latter changes into fsR = fB with unlimited range. An extra modifier 't' can be combined with 'g' and 'p' to exclude hopping over enemy pieces.

Like 'g' is a range-changing version of 'p', both doing their thing at an occupied square, the non-standard modifier 'y' can be seen as a range-changing version of 'm', doing their thing on empty squares. So where masR is a Hook Mover that does two perpendicular Rook moves, yafsW would be a piece that makes a Bishop move after single W step. This can also be used to indicate pieces that bend their path just before or after an obstacle as 3-leg moves: gabyabsR would be a collision-type bifurcator, which moves like Rook to an obstacle and changes to W there (g), takes one step back (b), spontaneously restoring the slider range), and then continues with a sideway backward (compared to the previous leg, so forward w.r.t. the first) = B move.

Beware: once a path bends, 'l' and 'r' are no longer symmetry equivalent, and using 's' after that would describe two essentially different paths. Oblique atoms already bend in the first step. To make it easier to specify a unique path for their continuation, the 'hr' and 'hl' direction-set specifiers are added to indicate the set of right-handed an left-handed moves of those. (In XBoard 4.8.0 these cannot be combined with other direction specifications!) Thus a 'Chiral Knight' hrN on e4 attacks only to f6, g3, d2 and c5, and writing the 'hr' and 'hl' moves separately allows you to write the symmetry-equivalent path on the 'hl' moves with 'r' and 'l' interchanged. Which you already could (and had to) do for chiral moves starting as orthogonal or diagonal atoms, such as afraflWaflafrW for a lame C that can be blocked at W or N squares.

Tame pieces -

XBoard interprets a modifier 't' on a final (or only) leg of a move as a prohibition to capture Kings. This is intended as a work-around, to allow approximate description of pieces that are too complex for the current implemetation to handle. Such an approximate description will either lack some legal moves, (which is fatal, because XBoard will reject them), or have some extra imagined moves. This would also be fatal, because checking with such an imagined move will make XBoard reject most opponent moves, as it will insist the opponent evades the check first. By labeling all imagined moves as non-checking, XBoard will never reject anything that is legal, while allowing something that was imagined can always be rejected by the engine.

XBoard limitations - In Betza notation the modifiers can usually be permuted in many ways without altering the meaning, but the XBoard implementation is more demanding; the modifiers must come in the order i, directional, m, c, d, e, t, p, g, o, y, n, j. Sinning against this directive will make it ignore many of the modifiers. Ranges can be at most two digits and must not start with a redundant zero. Parsing will terminate without error message when an unknown atom is encountered. XBoard's internal move logic is limited to a single side-effect capture. There is no limit on the number of 'non-destructive' legs, however. Moves with a non-final-leg capture must be specified after other moves to that capture square. Castling is reserved for Kings, (but any corner piece will do), and e.p. capture to Pawns.

Betza 2.0

The proposed Betza 2.0 extension of Betza notation is based on the concept of 'chaining': a move can in general consist out of multiple legs, which could have arbitrarily different properties. (This is a generalization of the 'a' modifier, which has the limitation that both steps must belong to the same atom.) So each leg is described using the full power of the basic Betza notation system, and that they are part of the same move is indicated by chaining them with a dash ('-'). This method makes many of the ad-hoc modifiers of the original Betza system redundant; a Xiangqi Elephant, for instance, can be described as mF-F, the first leg moving to an empty neighboring square, the second leg continuing to the final destination without restriction. The chain must thus be traversed as a whole, there can be no stopping half-way, and by default later legs go in the same direction as the previous one. A Checker can be described as fmF(fcF-mF), where the first leg now is capture-only, allowed only when it can complete the chain by continuing to an empty square. (Parentheses are allowed in Betza 2.0 to enhance readability.)

To reap the full power of the chaining concept, some extra move modalities are needed on the legs, which would make no sense on a complete move (i.e. on the final leg). Unfortunately the original Betza system had more or less used up the alphabet completely. But as it is always evident whether an atom is a complete move, or just a leg of a chain, the same letters can be reused with (slightly) different meaning. E.g. 'p' indicated a move that hopped, but on a leg it indicates the hop itself, i.e. it has become a modality modifier that specifies moving into an occupied square without removing the occupant. So the Cannon capture move becomes pR-cR: move to the platform as Rook, and continue to capture as Rook. A Grasshopper becomes pQ-K: move to platform as Queen, and then continue (in the same direction) as King. The 'g' prefix thus has become entirely superfluous, although gQ is of course more compact than pQ-K. The latter is much more flexible, though, as it allows general 'identity change' after the hop, such as for a 'bifurcator' pR-B, which moves to an obstacle like Rook, and then continues as Bishop.

Chaining allows detailed specification of the path taken to the destination square, so that lame leapers can be described unambiguously even if they have oblique moves. The Xiangqi Horse is mW-F, explicitly indicating it can be blocked only on the W squares. To minimize writing, the default modality on non-final legs is taken as 'm' rather than 'mc', as this is the far-more-common case, so that W-F will do for the Horse. Bent trajectories can be indicated by slamming directional modifiers of the continuation legs. Unlike general directional modifiers on complete moves, which are sets of directions, continuation legs must specify a single direction to keep the path unique. The convention here is that the directions are described relative to the previous leg, where 'f' then indicates the direction that deflects least, and thus is the default in continuation legs. (Where for complete moves the default is of course the set of all directions.)

Other useful move modalities on non-final legs are 'd' ('destroy', i.e. capture own piece), 't' ('test', i.e. hop over own piece only), 'o' (stray off board, to either re-enter it with a further leg or wrap around, to describe bouncing and cylinder pieces), and 'u' (to unload something that was captured or destroyed on an earlier leg, to implement magnetic pieces and catapults, which displace other pieces as side effect of their move). General side effects can then be implemented by specifying a path that makes the piece visit all squares on which these side-effects should take place, to remove pieces, carry them around and put them down elsewhere. It would even be possible to describe castling by having the King carry the Rook to its destination, e.g. irdiW03-buD-bW on the white King for O-O, where the extra convention is used that 'di' indicates you can destroy virgin pieces only.

Quirky stuff

Betza 2.0 allows the use of parentheses for readability, but also to turn a complex path into an atom, on which a range can be specified to indicate how many times that entire path can be repeated. E.g. (W-F)0 is the Mao-rider, which repeats the (blockable) steps of the Xiangqi Horse. The advantage over original Betza's nN0 is that it can specify more precisely where the moves can be blocked.

The default left-leg modality and right-leg direction implied by a range count can be overruled by putting modifiers on the range count itself. Thus, where N0 means Nightrider, Nrf0 indicates a 'Rose', with a curved trajectory. The advantage over original Betza's qN is the possibility to precisely indicate the curvature. This can also be used to get non-standard modality for intermediate steps: Rc0 describes a Rook that captures all enemies in its path! (But it would be blocked by an own piece. To also hop over these would require Rct0, and to destroy friend and foe alike Rcd0.) A modality prefix on the entire chain would only affect the final step.


The modifier 'x' indicates the atom will not move the piece according to the step(s) it specifies, but causes the piece to stay in place and emit a 'blast wave' that makes the move specified by the atom, (including side effects like capture), and then disappears. This blast wave goes in all directions (specified or implied on the atom) simultaneously. This 'explosion' is considered possible if it can complete the specified move in at least one direction. Otherwise it will block the entire move of which it is a leg.

With 'x' one can conveniently indicate side effects that would otherwise be very cumbesome to specify. E.g. an -xamctK suffix on a move would would specify that move would 'burn' (c) all neighboring (aK-wise) enemy pieces, but leave your own pieces undesturbed, and is a guaranteed success even if there were no neighbors (m) or only friends (t). Without the mt the entire move could only be made if there was indeed at least one neighboring foe to capture. Without the 'a' an 'f' would be implied, and the explosion would only go in the direction of the move, capturing what was approached ('Advancer capture'). Note that an -xdO suffix to a move would destroy the piece itself on its final square, for kamikaze moves. Pure rifle captures could be written as O-xcR, the O leaving the piece in place, provided the unidirectional (continuation leg!) blast wave manages to capture a foe Rook-wise. The convention here is that O as first 'step' of a path does by default have the same direction set as the atom that follows it, and starts the move by selecting one direction at the time out of this set (as usual), which the next atom then will consider 'forward'. Explosions can also be used as non-final leg, e.g. O-xmtocK-bmQ would first make the K-wise rifle capture, even considered a success when it goes off-board (o), after which the piece moves Q-wise in the opposite direction ('Withdrawer capture'). Note the leg following the explosion moves the piece, rather than propagating the blast wave, and inherits its idea of 'forward' from the leg before the explosion. Explosions can also be used as a 'probe': an xtN- prefix to a move would only allow that move if the piece has at least one friendly piece a Knight jump away.


The modality modifiers are rather 'course', only selecting by piece color. To make them more precise, they can be followed by the set of piece types they are valid for. E.g. a c{K}R would be a Rook move that can only capture a King (c already implies it must be an enemy), which can be used to implement the Xiangqi King-facing rule. Similarly O-xat{N}N-N would be an N move that can only be made when an N-like omni-directional (a) blast wave hits at least one Knight (Knight-relay Chess).

Some common idiom

Fully symmetric pieces are just simple concatenations of atoms, e.g. BN for Archbishop and NAD for Squirrel. Ranges for which the Betza system does not provide a letter can be written as two-leg moves with an 'all-purpose' first leg with 'mp' modality, which non-destructively passes through empty or occupied squares alike. E.g. mpafN would be a (2,4) leaper. For oblique lame leapers can be good to spell out the path as King steps. The Falcon (a multi-path lame CZ) can be written as maflmafrKmafrmaflKmafmafsKmafsmafK. This might seem awful, but that is mainly the Falcon's fault for being such a complex piece: it can reach each target square through three different paths, each bent or crooked, and of appreciable range. A shortcoming of the current system is that the first two paths, which are each other's mirror image, cannot be combined by using 's' in stead of separate 'l' and 'r', because then there is no way to force the two inflections in the path to go in opposite direction.

Asymmetric pieces, as often encountered in Shogi, require directional modifiers on some or all of their atoms. E.g. WfF and fWF for Gold and Silver General, fN for Knight, fR for Lance. Divergent pieces are described by giving their captures and other moves separately, even if they would belong to the same atom. E.g. fmWscW for a sideway-capturing Pawn. Hook-movers making 90-degree turns can be written with the 'again' modifier, followed by a perpendicular ('s') step: masR. Bent sliders making 45-degree steps can be simalrly written with a 'y' first leg, in stead of 'm', and an 'fs' direction: FyafsF is the Gryphon, WyafsW the Ancaa, because the 'y' converts the original range-1 move to infinite range. (Note that the F or W moves themselves have to be written separately, as in two-leg moves both legs are mandatory.) For a more distant point of inflection, one can specify that as a range: yafsF2 makes two F steps before upgrading to Q, and selecting the outward R moves from it. Moves to the F2 squares would have to be added separately. If we would have written yafsB2 the 'y' range conversion would be to K, and the result would be a lame (Moa-like) Zebra.