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.

Table of Contents

• Embedding a Diagram
• Controlling the Appearance
• Defining the Pieces
• Specifying Rules
• Irregular Board Shapes
• Piece Confinement and Irregular Promotions
• Promotion on Capture and Iron Pieces
• Configuring the AI for special rules
• Shuffle Games
• Notes
• Design Wizard

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.

Embedding a Diagram in your HTML Page

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.

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)

Satellites - 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 piece summary will not be displayed as a list, but as lines of running text.

HTML elements elsewhere on the page that are associated with an Interactive Diagram are called 'satellites' of that Diagram. By default these have HTML id like 'pieceList' or 'pieceTable'. They will be recognized through these ids when the Diagram is created, and then filled with the desired information. To make sure they contain the intended information if there are multiple Interactive Diagrams on the same page, a Diagram specification can contain the line satellite=xxx. This would cause the information to be placed in HTML elements with ids that have the part 'piece' replaced by 'xxx', e.g. xxxList. So 'piece' is merely the default value of the satellite parameter. By giving each Diagram on the page its own unique value for satellite, there will never be any mixups.

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=50
whitePrefix=w
blackPrefix=b
graphicsType=gif
lightShade=#FFFFFF
darkShade=#E0E0E0
rimColor=#FFFFFF
coordColor=#000000
background=
useMarkers=0
borders=1
firstRank=

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. This is not so much of a problem when you set useMarkers=1 to highlight moves by marker symbols instead of by background color. 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 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'.

Specifying the single character # as color will result in the background of the page element containing the square will remain visible through it. Specifying borders=0 will suppress the lines separating the squares. With the parameter background= one can specify the background image for the entire board, including the coordinate margins, which can be useful for boards that need more than ordinary checkering. (E.g. an oriental-style Xiangqi board.) It is important here that the background image has exactly the same size as the board; best way to get that is first make a screenshot of the diagram when it is still colored, and overpaint that in the desired way with an image editor like MS Paint or GIMP.

By default the diagram is displayed without board 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). The color of the area in which the coordinates are displayed can be controlled through rimColor, the color of the coordinates themselves by coordColor (by default white and black).

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 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::::a2-h2                     (fills 2nd rank, moves as FIDE by default)
knight:N:::c1,f1                  (must specify ID, as otherwise K would have been taken)
king::KisO3:king:f1               (non-standard castling (isO3) requires giving move)
rook::::a1,h1                     (nothing special; uses all defaults)

A piece sandbox has been provided to allow you to try out your own pieces before including them in your own diagrams.

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). The table will open automatically when a promotion choice is to be made. It is also possible to make this table appear in a permanently visible location of your choice on the page, as a satellite, 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. To fine-tune the aestetic appearance of the diagram a parameter holeColor (black by default) can be specified.

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. The zones can be defined separately for each piece type, through a parameter morph specified immediately after the definition line of 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. (But: it won't let you promote to a piece that itself would change into another type on the promotion square if that has the same ID.)

You can offer different promotion choices for different pieces or on different squares. With promoChoice you can define multiple choice sets, separated by slashes. By default it uses the first such set, but when the square is marked by a digit 1-9 in the morph board, this would use one of the subsequent sets for offering the choice. On squares marked by a vertical bar the piece will be subject to shogi-like promotion: promote to the piece implied by promoOffset, or defer promotion.

If it contains an exclamation point ! the move will be rejected, and the piece would not be allowed to move to the square. For an equal sign = the move would only be rejected if it contained a friendly piece (in case the XBetza move description would have allowed such friendly capture). 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.

If not all moves of a piece should result in the requested effect, the moves that don't can be marked in the Betza description by writing a quote ' behind the corresponding atom in the XBetza notation. This also holds for effects specified by the captureMatrix explained in the next section. So a piece that moves as A'D'fW for which the morph board specifies last-rank promotion will only be allowed to promote with the W move, and not if it reaches last rank by a jump.

There are several shortcuts for avoiding you have to type the entire board. 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 undisturbed 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 dark squares in a similar way). If multiple piece types have the same ID, the one latest in the table will be promoted to, but never the type itself. This allows you to use the same ID for two types that morph into each other.

Promotion on Capture, forbidden and mandatory Captures

Like the morph parameter can be used to define events (such as promotion, rejection) when a move reaches a certain square, the captureMatrix parameter can be used to define events when a move of a piece of a given type captures a victim of a specific type, or goes to an empty square. It defines a table, where the rows (separated by slashes / ) correspond to the moving pieces (in order of their definition lines), while the characters in each row correspond to the various piece types in the destination square (starting with the empty square). Also here a period . means nothing special happens, (and is the default for unmentioned victim types). A double quote " can be used as a shortcut for repeating a row, while a digit indicates the previous symbol should be repeated that many times (and assumes this to be the . if it is the first character on the row). A double quote followed by a number means the previous row should be repeated that many times.

An exclamation point ! or question mark ? indicate it is illegal for pieces of the given types to capture each other. This can be used to define iron pieces (capturable by no other type), or relatively iron (only capturable by some, often only excluding their own type as an anti-trade measure). It can also be used to define an arbitrary 'pecking order', like in Stratego. A percent sign % would make the capture illegal if recapture on the destination would be possible (a more precise definition of the protected anti-trading parameter).

A piece ID indicates the capture would lead to forced promotion to the mentioned type. This can be used to define promotion on capture, contageon, or pieces that morph into others on every move or capture (such as in Kyoto Shogi or micro-Shogi). A vertical bar makes the capture result in an (optional) shogi promotion, as defined by promoOffset. A lower-case version of the ID would promote to a piece of the opponent! It is possible to also define such promotions (or illegality) for friendly captures, in variants that allow such moves. The friendly victims would come directly after the piece types for normal captures, on the same row. An = anywhere in the row would skip to the friendly-captures part, and set those to a copy of the normal captures. You could still continue after it the row for overruling that copy, though.

A kamikaze capture is indicated by a 0 (zero); this will make both the capturer and captured piece disappear. When the matrix contains an @ sign it can also destroy pieces on adjacent squares. The effect can be tuned with the parameter atomicCapture=N. With N=0 (the default) this would capture all enemy pieces in the 3x3 area centered on the destination. For larger values of N it would destroy all adjacent pieces of either color, except the first N in the piece table, while the capturing piece would always disappear. What 'adjacent' means here can be configured through the parameter blastZone, which can get the values K (the default), W, F or N.

It is also possible to grant some captures a higher priority than other moves, by putting a tilde (~) in the corresponding capture-matrix element. In a position where any such prioritized move would be legal it is then mandatory to play one of those. The remaining moves can only be played when no legal prioritized move exists.

The capture matrix can also be used to exclude hopping of one specific piece type over another. This would be caused by a ^ or $ in the corresponding element of the capture matrix, where the latter would forbid both hopping and capturing. Also here the exclusion distinguishes friendly hopping from hopping over enemies.

A colon (:) indicates a move that freezes the opponent army for one turn, allowing the player who makes it to play two moves in a row, as in Shock Chess.

Pieces with Influence

Some variants have pieces that affect the capabilities of adjacent pieces just by being there. The Diagram supports this through the parameters trackPieces=N, trackedTypes=M, spell and spellZone. The N here indicates which the first piece type that should cast such a spell on its surroundings, and M (which by default is 1) how many subsequent piece types (all in piece-table order). (Note the maximum number of pieces of the same type that can be tracked is two, and the possibility to track more than one type was mainly added to provide a work-around for if you need more, by diversifying the type into identical sub-types.)

The spellZone parameter can be given the values K (the default), W, F or N, and determines which squares are affected by the presence of a piece of the tracked type. There are various flavors of spells, selected by the spell parameter. Currently supported are:

• burn - an enemy piece landing in the spell zone disappears instantly.
• freeze - an enemy piece standing in the spell zone cannot move at all.
• charm - an enemy piece standing in the spell zone cannot capture.
• hide - sliders can hop over friendly pieces in the spell zone.
• protect - a friendly piece in the spell zone cannot be captured by the opponent.
• brake - enemy pieces cannot move through or out of the spell zone.

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.

Rotating pieces

Changing the orientation of a piece with an asymmetric move can be done by defining a separate piece type for each orientation, and allowing the piece to promote to any of those after its move. To allow 'stationary promotion', i.e. without moving the piece, you must specify a parameter handSwap=1, and put the alternative orientations in the holdings at the start of the game. This allows you or the AI to swap the piece in the holdings with pieces that have the same ID on the board, by dragging the former on top of the latter.

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>

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 to which diagram the piece list or table belong 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 HTML 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.

Last revised by H. G. Muller.