The Chess Variant Pages
Custom Search



Interactive diagrams

Introduction

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.

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 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.

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 text you have to copy to your own page to insert it there.

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 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
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). A '+' indicates Shogi-style promotions; in this case the only available choices are the piece itself (i.e. defer) and the piece type obtained by adding the general parameter promoOffset to it.

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 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.

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
iron=N
antiTrade=N
counterStrike=N
protected=N
tradeThreshold=N

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 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 equalize through counter-baring. 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.)

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.



This 'user submitted' page is a collaboration between the posting user and the Chess Variant Pages. Registered contributors to the Chess Variant Pages have the ability to post their own works, subject to review and editing by the Chess Variant Pages Editorial Staff.


By H. G. Muller.
Web page created: 2015-11-06. Web page last updated: 2015-11-06