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". (E.g. 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 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'.

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 is a comma-separated list. 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. 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 '+' 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.

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-diagram/betza.js"></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