Interactive diagrams

It is possible to post diagrams of Chess variants in HTML pages, which are not just static images, but which react to mouse clicking in various ways. In particular you can move the pieces in it around in any way you want, and when you 'pick up' a piece, the diagram will show you where it could move to. It will not enforce rules or even turn order, though, to allow for easy setup of arbitrary positions. The diagram by default comes with a piece legend and a built-in AI, which initially are hidden, but can be opened by clicking on links displayed below the diagram.

The AI will respond to any move you make (with a move for the other color) when the AI control window is open. This control window contains buttons with which you can navigate through the game that is recorded in the area below them, from moves played in the diagram by you or the AI. You can also copy a game into that area, to use the diagram as a game viewer. (For shuffle games, be sure to also copy the number in braces before the moves, which represents the start position.)

The piece legend is a table that shows piece images, names, ids and moves; clicking on the piece name there makes the board display a move diagram for that piece. A second click (or a click on the board) brings back the original position. (Or, for a piece with Shogi-style promotion, the move diagram for the promoted piece first.) For moves that depend on context hovering the mouse pointer over a square will materialize an opponent piece there, and adapts the move diagram according to its presence. (Normally the move diagrams are for the piece centered on an otherwise empty board.) Squares that can be activated this way are usually marked both by a color and a symbol or question mark.

To insert such a diagram into your own HTML page on this (or, with only a little more work, on your own) website, all you have to do is write a small definition of it (like specifying board size, and names and moves of all participating pieces) between a HTML tag pair that has the attribute class="idiagram". At the bottom of this article you will be able to open a Design Wizard that can assist you with that. If you plan to use that, there is little need to read on; the Wizard will provide you with the HTML code for a diagram according to your specifications, which you will be able to copy-paste into your own web pages, in particular those on this website. This code will have the diagram description between <div class="idiagram" style="float: left; margin: 40px;"> and </div> tags, where the floating 'style' specification would make your text nicely wrap around the diagram, like on this page.

files=10 graphicsDir=/membergraphics/MSinteractivedia/ graphicsType=png squareSize=36 whitePrefix=White blackPrefix=Black symmetry=mirror satellite=demo firstRank=1 royal=8 Pawn::::a2-j2 Knight:N:::b1,i1 Bishop::::d1,g1 Rook::::a1,j1 Archbishop::::c1 Chancellor::::h1 Queen::::e1 King::::f1 Lion:::::2

You can also make the diagram interact with the rest of your page, by attaching functions in the JavaScript that powers the diagram directly to your HTML elements. A useful function, for instance, is 'ShowMoves(N)', which would make the diagram display the moves of the N-th piece you defined in it. E.g. with "<p onclick="ShowMoves(5)">Some text...</p>" the moves of piece number 5 would be displayed on the board when the user clicks on the text in the paragraph, like I have done below (but with <li></li> tag pairs to make, them list items rather than paragraphs):

c1,h8: Archbishop (BN)
h1,c8: Chancellor (RN)
in hand: Lion (2 King moves per turn)

It is possible to have such a list of all pieces defined in the diagram generated automatically at a location of your choice in the text. To this end you have to put an empty list <ul id="pieceList"></ul> somewhere on your page. The diagram script will then locate that, and fill it with the list of clickable items when it generates the diagram. If the type of HTML tag with this id is not ul but p, the pieces will not be displayed as a list, but as lines of running text.

The rest of this page explains how to write a text that specifies a diagram 'by hand': what parameters you can supply, and what they mean. If you don't want to bother with all that, you can also go to the bottom of this page, and press the button there to start a wizard that will guide you through the design process. In the end this will show you on this page the diagram you have specified (so you can test it out), as well as the HTML text you have to copy to your own page to insert it there. You can also use the Play-Test Applet for generating HTML for an Interactive Diagram.

Setup

The description of the diagram consists of two parts: general parameters, and piece definitions. The general parameters are set by lines of the keyword=value type; below is an (incomplete) list of recognized keywords, and their default:

files=8
ranks=8
graphicsDir=/graphics.dir/alfaerie/
squareSize=54
whitePrefix=w
blackPrefix=b
graphicsType=gif
lightShade=#FFFFFF
darkShade=#E0E0E0

The shades apply to the board squares; for non-checkered boards you can make them the same. (Bright colors are discouraged, as they interfere with the move highlighting. To make the diagram look more pretty as a static image, you can define a startShade after having defined the darkShade, which will be used instead of the latter before you start to interact with the diagram.) The square sizes needs to be 4 pixels larger than the size of the piece images. The prefixes and graphics type will be used to construct the filenames of the images it is going to use; by default it will prefix the names you give in the piece definitions by 'w' or 'b' to distingush the images for white and black pieces of the same type, and suffix them with '.gif'.

By default the diagram is displayed without coordinates. By specifying firstRank=N you can enable display of coordinates next to the board, where N indicates the number of the rank at the bottom (usually 1, although for some variants 0 is a better choice).

Pieces

The second part of diagram definition lists the piece types, one line per piece. Each line contains 5 or 6 items, separated by ':'. These items are: (1) piece name, (2) piece ID, (3) move descriptor, (4) root-name of the image file, (5) starting square(s) and (optionally) (6) number of pieces that start in the hand. The starting-squares field can contain a comma-separated list of squares. Square ranges are also understood: a2-h2 would mean all squares on 2nd rank, and d4-e5 the four central squares. A general parameter symmetry (which by default has the value 'mirror') affects how the list is interpreted. When symmetry=mirror or symmetry=rotate, only white pieces have to be listed, and the locations of the corresponding black pieces will be derived from that. With symmetry=none, an extra comma separates the white from the black pieces. (White pieces come first in that case.)

The XBetza extension

The diagram uses an extension of Betza's funny notation, to allow description of more complex moves. The most versatile enhancemet is that it allows description of moves as multiple steps belonging to the same atom. To this end a new modifier a is introduced, acting as a separator of groups of other modifiers. Each such group of modifiers then applies to a separate move of the same atom, forged into one overall ('multi-leg') move. To get a more detailed explanation of how this can be used for description of lame leapers, bent sliders or locust capture, click here.

Multi-leg moves

When the a ('again') modifier is used amongst the modifiers prefixing an atom, it sub-divides the other modifiers into groups, each group specifying a separate move of the atom, which should be performed as a series. Only when all steps of the series can be taken, the move would be legal. A simple example is mafcW, which defines a move that starts with an mW step, and then must continue with a fcW step. Directonal modifiers for a continuation leg are relative to the previous step, where f means in the same direction. If the first step is not possible (because the adjacent square is not empty, and thus cannot be reached with an m move), then entire move is not possible. So the example described a lame Dababba that can only capture.

Often the a modifier is needed to describe a change in direction. E.g. masR would indicate a Rook that can turn one 90-degree corner on an empty square. Direction changes of 45 or 135-degrees can be indicated, and would turn diagonal atoms into orthogonal ones and vice versa. E.g. mafsW would be the Xiangqi Mao, making an outward diagonal step (fs) as second leg after an initial Wazir step to an empty square. Without directional modifier a continuation leg can go in any direction except the one exactly opposite to the previous leg, and without a mode specifier a non-final leg defaults to m, i.e. must step through empty squares only. A final leg will by default both capture and move (mc), as usual.

Multi-leg moves can also be used for describing locust capture, by first capturing to the square containing the intended victim, and then continuing to the final destination with a second step. E.g. Checkers-like capture can be indicated by fcafmF: start capturing a piece diagonally in front of you (fcF), and then continue in the same direction to an empty square with fmF. If the first square is not containing an enemy piece, or the second step would not end on an empty square, the entire move is forbidden.

XBetza redefines the meaning of the hopper modifiers p and g when applied to non-final 'legs' of a multiple move indicated through the a separator. In this case they mean the piece must jump on the piece it will be hopping, rather than over it, and the range change implied by g will apply to the subsequent leg, changing the slider atoms B, R, Q into the corresponding leaper atoms F, W, K for that (dropping any explicit range specifiers). So gafQ would be an alterative description of the Grasshopper. This range change also works in the opposite direction; gafK would be the Contra-Grasshopper, continuing with a Q move after the 'platform'.

As a range-changing counterpart of the m modifier the new modifier y is introduced for non-final legs, to indicate a direction and range change can take place on reaching an empty square, such as occurs with bent sliders like the Griffon FyafsF: move first to an F square (mF), and then continue as slider at 45 degrees (so as R).

The modifier i used in a continuation leg stands for 'iso', and means the corresponding slider move must have an equal number of steps as the preceding slider move. This can be used to describe pieces like the Sissa (maivsQ, the vs = (f+b)(l+r) = fl + fr + bl + br indicating all 45- and 135-degree turns), or slider rifle capture (mRcaibR, capture and move exactly back). As a quirk the diagram accepts the modifier x in a non-final leg of a multi-leg move to 'activate' the piece originally on the square this leg reached, and moves that piece to the final destination of the move, rather than the piece the move started with (which remains in place). E.g. in Knight-relay Chess the Knight would be mNxaN, acivating any piece a Knight jump away to move as a Knight.

XBetza also introduces some new atoms and modifiers to make it easier to describe some common situations. E.g. the O atom with a range is used to describe castling with the corner piece under the normal restrictions, the range specifying the King displacement. The U atom indicates a universal leaper (aka Kraken). C (Camel) and Z (Zebra) are easier-to-remember synonyms for L and J, respectively. New modifiers are e to indicate generalized e.p. capture, i.e. a move to a square the previously moved lame leaper passed through, removing that lame leaper. A leading modifier i indicates the move can only be made by virgin pieces, and in combination with an n such a move will create e.p. capture rights. The diagram allows the combination nn for indicating creation of e.p. rights on moves of non-virgin lame leapers.

The diagram supports the z and q modifiers in the usual meaning; they can even be combined with p and g to define crooked or circular hoppers. They cannot be used as part of a multi-leg move, however. The modifier j on a distant leap forces the move to jump over something, but like n, the squares jumped over are only well defined for purely orthogonal or diagonal leaps. A j on a slider atom (e.g. R, F4) means the first square of the trajectory is ignored (i.e. the first step is really a leap of double the distance), e.g. the Ski-Rook jR.

The modifier k can be used to indicate the move can only be used to capture a royal piece, e.g. for implementing the rule in Xiangqi that Kings cannot face each other (WkR). The diagram interprets an asterisk as a range needed to reach up to half the board (which thus depends on the location of the piece), but at least 1. This can be used to describe the position-dependent Pawn movement in some variants as fmW*, which defies a strict Betza description. Such a move will always create e.p. capture rights for an e move on any square it passes through.

The name is arbitrary, and will appear in the legend table. The ID has to be a single letter, and is referred to by the promoChoice string (see below). By default the first letter of the piece name would be taken for this. The move descriptor has to be in Betza notation; the XBetza extension, (which uses the 'a' ('again') operator for describing multi-leg moves) is understood. For a few standard pieces (FIDE and a few common fairies) the name will be recognized, and the default move will be the move of the orthodox piece of that name. (This prevents that you have to supply the awkward Betza description of the FIDE pawn!) The default for the image root-name is the name of the piece. Only when you are not satisfied with the default, the corresponding item has to be non-empty. A few examples are

archbishop:A:BN:cardinal:c1       (image name differs from piece name)
warrior:X:mNcK:centaur:b1,g1      (everything non-standard)
hawk:H:BN:bird::1                 (starts one in hand, uses w/bbird.gif image)
pawn:P::pawn:a2-h2                (fills 2nd rank, moves as FIDE by default)
knight:N:::c1,f1                  (must specify ID, as otherwise K is taken)
king:K:KisO3:king:f1              (non-standard castling (isO3) requires giving move)
rook::::a1,h1                     (nothing special; uses all defaults)

Rules

Amongst the general parameters there are also a few to specify game rules. These are:

holdingsType=0
promoZone=1
maxPromote=1
promoChoice=NBRQ
promoOffset=0
conversion=0
symmetry=mirror

If you want promotions to be faithfully performed when pieces are moved in the diagram, you would have to set correct values for the depth of the promotion zone (in ranks), the number of pieces that should promote when they get there (if maxPromote=N the first N piece types you define will promote), and the IDs of the pieces that can be promoted to (promoChoice. In the latter, a * prefixed to an ID indicates that choice will only be valid if pieces of that type are available in the 'hand' (where they presumably got by getting captured). A numeric suffix M on a piece (smaller than the promoZone depth) will restrict promotion to that piece to the last M ranks only. A ! prefix means the choice is not available on last rank, and is typically used on a Pawn amongst the choices (to allow deferral on earlier ranks of a deep zone). The piece IDs can be comma separated, or simply concatenated. Shogi-style promotions can be specified by defining a numerical parameter promoOffset; in this case the only available choices are the piece itself (i.e. defer) and the piece type promoOffset places below it in the piece list. In this case the promoChoice is largely ignored, except that a piece ID in it that is prefixed with ! will not be allowed to defer, and promote automatically.

The parameter holdingsType specifies whether pieces can be held 'in hand', and how they get there. By default captured pieces are just discarded, but by setting holdingsType=1 they would get back into the hand of their owner (so they become available as promotion choice, like in Grand Chess). With holdingsType=-1 captured pieces would color-flip, and end up in the hand of their capturer, presumably for being dropped back onto the board, like in Crazyhouse.

The parameter conversion can be set to the number of the piece type to which the Bishop Conversion Rule should be applied. Pieces of the specified type must then make their first moves to different square shades.

The diagram will include a (normally collapsed) legend, tabulating all piece types. This is also used as holdings, and contains columns for how many piece of each type the players have in hand. If there are pieces in hand, they can be dragged to the board. Pieces captured on the board will transfer to the hand according to the holdingsType parameter. Note that promotion choices for moves performed in the diagram will have to be made from this table, (the allowed choices will be highlighted in pale blue), and that when the table is closed, promotion will be automatically to the 'default' piece. It is also possible to make this table appear instead in a permanently visible location of your choice on the page, by putting an empty HTML table <table id="pieceTable"></table> in the desired location.

Irregular boards

When you define a piece with the name 'hole', the Diagram will treat it as special. It will not add it to the piece table, and will ignore any ID, move or image you specify for it. Instead it will make the squares you list for it 'inaccessible'; i.e. it will black them out, and refrain from highlighting moves that otherwise would end on such squares. This can be used to make boards with irregular shapes, by specifying these as the smallest rectangle that contains them, and covering the unwanted squares with holes.

Since the Diagram allows you to do illegal moves, you can actually move pieces to the holes, or even specify pieces to be put on squares that you earlier defined as holes, in the start position. In that case the square will revert to a hole, rather than an empty square, when that piece moves away again. I.e. it acts like a brouhaha square.

Making use of Board Zones

The board can be divided into zones of arbitrary size and shapes. Such zones can be used to change how pieces move (by changing their type, i.e. promoting them), deny access, or terminate the game when they are reached. Such zones can be defined separately for each piece type, through a parameter morph specified immediately after defining the piece to which it applies.

The value of this parameter is essentially an image of the board, the ranks separated by slashes, starting with the highest rank (white's promotion zone). Each character on a rank corresponds to a square, and specifies what would happen when a piece of the given type lands on that square. When that character is a piece ID, the piece would instantly promote to the type the ID stands for. If it is an asterisk *, it invokes the promotion procedure as specified through promoChoice, to let the user choose a piece to promote to. If it contains an exclamation point ! the move is rejected, and the piece would not be allowed to move to the square. If it contains a + or #, the game would be won when the piece reaches the square; for the # immediately (like capturing a King), for the + as a delayed winning condition, which could still be trumped by King capture in the next half-move (like Shatranj baring).

A period . means the square is not special. Ranks that are not mentioned, or contain no characters at all, will be assumed to contain all non-special squares. If fewer characters are present for a rank than the board width, the characters that are given will be repeated to fill in the missing spots. If a rank just contains a double quote " , it indicates a repetition of the previous rank.

So specifying morph=Q would mean the piece promotes to Q everywhere on last rank, but moves freely on the rest of the board. For a diagonal variant where white would play from a1 to h8, an L-shaped promotion zone consisting of 8th rank and the h-file could be defined through morph=*/.......*/"/"/"/"/"/" . To promote to the piece that started on the square in an orthodox setup, with choice at e1/e8, you would write (after the Pawn definition) morph=RNBQ*BNR . For Xiangqi-like 'promotion' the Pawns would get morph=Q/Q/Q/Q/Q, where Q is the across-the-river Pawn. The King and Advisors would get morph=//////!/!!!.../"/" to confine them to the Palace. For King of the Hill the King would get morph=///...++/" to define the four central 'win squares'. To implement a piece X that moves as C on all white squares of an 8x8 board you would write morp=C./.C/C./.C/C./.C/C./.C for it (and presumably you would have the C morph back to X on all the black squares in a similar way).

Artificial Intelligence

Since June 2020 the Diagram also comes with a built-in generic AI, which makes it into a live demo that you can play against, at a human-friendly level. This is still somewhat experimental, and might not work flawlessly for every variant. To play sensibly the AI will have to know rule details that a diagram for just showing pseudo-legal moves doesn't care about. It has a built-in algorithm for estimating piece values based on the moves, but the resulting values will probably not be very good. A number of new parameters were added to specify game rules:

extinction=1
royal=N
baring=N
stalemate=draw
counterbare=draw
iron=N
antiTrade=N
counterStrike=N
protected=N
tradeThreshold=N
contageous=

Here N represents the number of the piece type that gets the mentioned property. So these parameters can occur multiple times with different values, to indicate more than one piece type has the property. Loss of a royal piece is the primary termination condition, and decides the game instantly, without having to worry about any retaliation. The parameter extinction determines if capture of a single royal decides the game, or that all royals have to be captured. (The latter is the default, but when there is only a single royal it doesn't matter). The baring condition is somewhat similar to extinction royalty, in that it terminates a game when all pieces with this property have been eliminated. But it is a delayed winning condition, which grants the opponent an 'after-move', with which he might trump it by capturing a royal, or achieve 'counter-baring'. In the latter case the result is determined by the parameter counterbare, which (similar to the stalemate result) can be a draw (the default) or a loss for the player that is stalemated or bared first. When you specify baring=0 all non-royal pieces will get this property.

The property iron means that the piece cannot be captured at all, by any other piece type. In a sense this is the opposite of royalty: you would lose rather than win by capturing an iron piece, which is a way of saying you can never do it. A weaker form of this is antiTrade, which forbids pieces that both have the property to capture each other, but they can still be captured by other pieces. The weakest property of this kind is counterStrike, which endows pieces with temporary ironhood when a piece of the same type was captured in the preceding half-move.

The protected property grants temporary royalty, and applies on the turn after a piece with this property captures one that also has it. In practice this means pieces with this property are not allowed to capture each other when the victim is protected. This property can be weakened by a threshold, which would allow the capture when it would gain an amount of material equivalent to the value of the piece specified by tradeThreshold. (Which is useful when the protected property is applied to a piece capable of multi-capture.)

It is also possible to make one or more pieces contageous, i.e. make any piece that captures them instantly change to that type (but keep their color). The string parameter contageous can be set to the (concatenated or comma-separated) IDs of the pieces that have this property. When an ID in this string is prefixed by a ! it will not be contageous itself, but be immune to the contageon effect, and always keep its own type.

The AI can be disabled by specifying enableAI=0, and it would be good to do that when it is known the AI would not be able to handle the variant properly (such as variants with piece drops). To make that the user still has a way to switch on the AI when the diagram is used with a permanent piece table elsewhere on the page as satellite, (see below), one should specify enableAI=2, as the collapsable piece table that normally also contains the AI switch would not be added under the diagram in that case.

Shuffle games

It is also possible to specify the Diagram should shuffle pieces at the start of a new game. It will not do that in the initial display, though, but only when you use the 'Restart' button in the AI control bar. You can specify how it must shuffle by a shuffle=... parameter, where the value can be a comma-separated list of piece sets, which will then be permuted over the locations where the diagram originally specified them. E.g. specifying shuffle=BN,KQ with the FIDE setup would randomly permute the four minors, and might swap King with Queen. While shuffle=KQ,QBN might first swap K and Q, and then randomly permute Queen and minors.

The permutation has some restrictions, and can be specified to have more: If a piece has a castling move, it will be kept between the corner pieces. A piece ID prefixed with ! (exclamation point) will be assigned new locations before others, as equally distributed over square shades as possible. So Chess960-type shuffling can be obtained through shuffle=N!BRQK. Finally, a prefix : (colon) will cause the piece type to be symmetrically placed. (Only use for even numbers of pieces, when the set of squares the pieces-to-be-permuted are standing on is indeed symmetric!) This can be used to make swaps in the wings while keeping the setup symmetric; e.g. shuffle=:NR might swap N and R either on both wings or not at all.

Notes

Although the diagram knows the rules, and highlights the legal moves, it will not enforce those. So you can play illegal moves, if you insist. This was done intentionally, to make it easy to setup positions to experiment with. And to be still usable for variants with rules that are so exotic they could not be completely handled. The diagram does not even enforce turn order. (This comes in handy for non-standard castlings, where you can then simply move King and Rook separately.)

When you drop a piece from the holdings on top of your own piece, the diagram will treat it as a substitution, where the replaced piece goes back into your own hand.

For the diagram to work the HTML page has to link to the underlying JavaScript program. This requires an element

<script type="text/javascript" src="/membergraphics/MSinteractive-diagrams/betza.js?nocache=true"></script>

to be on the page (which is included in the HTML text provided by the design wizard).

If you want to use such diagrams on your own website, you would have to copy that JavaScript file there too, and adapt the link to it accordingly.

Multiple diagrams on a page are not recommended, but are supported in a limited way. This was mainly done for convenience in the CVP Comments listing, where comments on different articles can be displayed together, and should not wreck each other. If the text in the comment contains external elements, such as a pieceList or a pieceTable, the script cannot know which piece list or table you want there if there are multiple diagrams. In CVP Comments you should therefore always associate them with the diagram to which they belong, even if your Comment contains only a single diagram (as it might be grouped with Comments of others). This is done through a parameter satellite=xxx in the diagram definition, where 'xxx' is a name unique to the diagram, and then using xxxList and xxxTable as ID for the external elements of that diagram. (Default value of 'xxx' is 'piece'.)

A wizard is available to help you design the diagram description, so you can directly copy-paste it into your own web page on this website.

Interactive diagrams

Setup

Pieces

The XBetza extension

Multi-leg moves

Rules

Irregular boards

Making use of Board Zones

Artificial Intelligence

Shuffle games

Notes

Step 1: specify the parameters of your variant below:

Step 2: When satisfied with the settings above, press the button below.

Diagram design wizard

Make your own interactive diagram!

Step 4: Drag the pieces from the table to the board

Step 3. Define the pieces one by one:

Step 3a: Provide information on the next piece type to add.

5. This is the HTML code describing the diagram:

Revisions of MSinteractive-diagrams