Check out Janggi (Korean Chess), our featured variant for December, 2024.

Chess Variants PBM Instructions

Here are instructions for using The Chess Variants PBM System.

How to Make a Move

You make a move by entering the notation for it in a form. The notation used is a simplified form of algebraic notation.

Every board has algebraic coordinates displayed along two edges. The default is for letters to indicate the files and for arabic numerals to indicate the ranks, though this can be changed for individual games. The main thing to remember is that each coordinate is in file-rank format. For example, a1 means the coordinate at file a and rank 1. In Shogi, which does not use the defaults, 1a means the coordinate at file 1 and rank a, and a1 is not a coordinate. By putting together the file, as shown at the bottom of a file, and the rank, as shown to the left of a rank, you get the coordinate for the space. The coordinate may also be seen in the ALT text that shows up if you let the mouse pointer hover over it. Coordinates should never include spaces between files and ranks. a1 is a valid coordinate, but "a 1" is not.

Each piece is represented by a single letter. Lowercase letters are normally used for Black pieces, and uppercase letters are normally used for White pieces. You can find the letter used to represent a piece by moving the mouse pointer over it or by consulting the table beneath the form.

The notation allows five basic operations. The first three are moving, adding, and removing a piece. The remaining two are adding and removing a space. All five operations are performed with a single operator, the hyphen.

To move a piece, write its starting coordinate, a hyphen, and its destination. For example, e2-e4 indicates the King Pawn opening in Chess. Any time a piece moves, its starting position is emptied, and it replaces whatever was in the space it moves to. Contrary to the more usual algebraic notation, the hyphen is used for both capturing and non-capturing moves. The letter x, along with the entire alphabet, is reserved for identifying pieces used in Chess variants.

To add a piece, write the letter for the piece, a hyphen, and the destination. For example, N-f3 places a Knight on f3. If this is your first move in Chess, it will give you a third Knight, because this notation is not used for moving a piece from one place to another. It is more analogous to a drop, as in games like Shogi or Pocket Knight Chess. Adding a piece always replaces the contents of the space you add a piece to. It will not add multiple pieces to the same space.

To add a space where there wasn't one, you can either add a piece there, which will automatically add a space too, or you can just drop an empty space on the location. You can do this by using the @ sign to represent an empty space. For example, @-a9 would add a new empty space at the location a9.

There are two ways to remove a piece. One is to drop an at-sign, @, on the space, as in @-f3, because the internal code uses an at-sign to represent an empty space. The other way is to move a piece nowhere, as in f3-, because moving a piece always removes it from its starting position.

To remove a space, move nothing to it, as in -f3, which tells the program that neither a piece nor an empty space should occupy location f3.

To handle special moves, such as castling or en passant, you are allowed to string together move primitives into a single move. Separate each move primitive by a semicolon. Here are some examples of special moves. I added spaces for legibility, but they aren't essential. Whitespace gets trimmed off of the elements in a move.

MoveNotation
King-side Castlinge1 - g1; h1 - f1
Queen-side Castlinge1 - c1; a1 - d1
Pawn promotes to Queenf7 - f8; Q - f8
En passantf4-g3; @-g4
Rook merges with Knight as Marshall, as in Fusion Chessa1-b1; M-b1
Knight moves away from Marshall at b1, leaving Rook behind, as in Fusion ChessN-c3; R-b1
2. Nf3 follows 1. e3, d6 in Magnetic Chessg1-f3; e3-a3; f7-f4
In Voidrider Chess, a Voidrider moves its space from b1 to d1V b1 - d1; -b1

There is also some primitive move checking. When you specify both the piece and the starting coordinate in a move, as in N g1-f3, it will check whether there is an N on g1. If there isn't, it will notify you that it couldn't make the move, asking you to go back and try again. Since it will not check the legality of a move for you, it will generally be good practice to write your moves in this slightly longer format, because it will help keep you from making moves you didn't mean to make. It will also make it easier for your opponent to see what your move was. For parsing purposes, this notation requires a space between the piece and its coordinate. It would not know what to do with something like Ng1-f3.

How to Play a Game by Email

You begin by inviting someone to play using the invitation feature of the PBM. From the main menu for a preset, click on the "Invite" button. Then fill out the form to send your invitation. You may invite someone to play only if both of you have Chessvariants.com userids. The server will fetch your email addresses from our database as it needs them for sending email.

The person who receives your invitation will be given the option of accepting or declining. If he accepts, then he may choose whether he wishes to move first or second. If he moves first, he should make a move to indicate his acceptance. Otherwise, you will be notified that he has accepted and wishes you to move first. If so, then you should begin the game.

When it is your turn to move, you will receive email from the PBM telling you your opponent's last move, and it will contain an url you can follow to view the board and make your move. You should then follow the url, view your opponent's move, enter your own move, click the "Verify" button, and view what your move. Then, if you entered the move you intended, you should confirm your move by giving your password and clicking the "Send" button. This will email the move to your opponent, who will then follow the same procedure. Whenever it is not your turn, you will be able to view the game, but you will be unable to move. The log of your game will keep track of whose turn it is, allowing each player to move only on his turn.

How to Play a Game by in Real-Time

To play a game in real-time, you begin as you would an email game. After you have used email to start the game, you don't have to rely it to know when your opponent has moved. After you make a move, click the "Continue" button to return to the game. While you wait for your opponent to move, the page will periodically refresh itself. Once your opponent does move, this will be recorded in the log. Since the page reloads the log upon each refresh, it will be able to notify you when your opponent has moved. Once it is your turn again, the PBM page will gain focus, which moves it in front of other windows, it will emit an audible beep, and it will show you your opponent's move and tell you that it is now your turn. The beeping sound will be continuous if your brower supports the EMBED tag. This is to better alert you in case you've stepped away from your computer. You can stop it by clicking on the stop button of the plug-in that will show up on the page. You then make your move, return to the game, and wait for your opponent's next move.

How to Log a Game

All games are automatically logged. You will be required to supply a logname when you start a game. The log is a list of PHP variable assignments that includes such things as board and piece set parameters, the userids of both players, a record of whose turn it is, and a list of all moves and comments made during the game. The logfile cannot be accessed directly. Instead, it is read by the PBM, which makes use of the variables to display the game and enable you to play it.

How to Play in Solitaire Mode

Besides playing against an on-line opponent, you may play a game with yourself, or you may use the PBM to play a game with someone in the same room. You would do this by playing in solitaire mode. From the main menu for a preset, click on the "Move" button. Then one move at a time. Since you don't send any moves in solitaire mode, you don't go through the extra step of verifying your move. Once you make a move, it shows you your move and lets you make your next one. If you did make the wrong move, you can correct it by using the Back button on your browser to return to the previous page.

Although this mode does not log games, it does retain a record of all your moves within each page it generates. You may, at any time, go from this mode to the Record mode, from which you can retrieve all your moves in a manner that you can include on a webpage to let others view your game.

How to Create a Preset

If you know Forsythe code, you can create a new preset. To create a preset, start with an existing preset and modify it until it is what you want. You can continually preview the changes you make until you get it just as you want it.

Forsythe Code represents a board position as a single string of text. The string begins with the top left corner of the board, continues across each rank from left to right, and continues down the ranks from top to bottom, until it reaches the lower right corner. This should be easy to remember, because it is the same direction you read English in. A string of Forsythe code contains letters, numbers, and a few symbols. Here is what they mean:

Any letter, typically [a-z] and [A-Z]
Each letter represents an individual Chess piece. Lowercase letters normally represent Black pieces, and uppercase letters normally represent White pieces.
Any number: [0-9].
A number represents a series of as many empty spaces.
The hyphen: -
A hyphen represents a place in the board definition where there is no actual space. This could be a hole in the board or extra space around a non-rectangular board.
The slash: /
A slash represents the end of a rank. When it comes at the natural end of a rank, it serves mainly as a visual cue for someone reading the code. When it comes earlier, the rest of the rank gets padded with hyphens (representing non-existing spaces).
The asterisk: *
An asterisk fills the remainder of a rank with empty spaces.

With this in mind, here are some alternate ways of representing the opening position in Chess:

rnbqkbnrpppppppp32PPPPPPPPRNBQKBNR
This is the most compact way to represent it. The number 32 represents the four ranks between the Black and White Pawns.
rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR
This way is less compact but more readable. It visually divides the code into all eight ranks.
rnbqkbnr/pppppppp/****/PPPPPPPP/RNBQKBNR
In this one, each asterisk represent an entire rank of empty spaces.
rnbqkbnr/pppppppp/*/*/*/*/PPPPPPPP/RNBQKBNR
Some might prefer this one to the one above, but I don't.

The code used is not identical to FEN, EPD, or FFEN, but like these, it uses additional parameters to specify characteristics of the board. These can be specified with the preset form.

Width
This is how many files wide the board is. This parameter tells the server when to end one rank and begin the one below it. It also tells how much padding is required when a slash or asterisk is encountered. The height of a board will be derived from its width and size. The default for width is 8.
Set
This indicates which piece set to use. This will affect which piece images are associated with the letters in the Forsythe code. There are many sets available, because there is a choice of graphic style, and there are many more fairy pieces than can fit into the 26-letter Latin alphabet. It is also possible to choose ASCII diagrams for either rectangular boards or hexagonal boards. The default is a set drawn in the abstract style.
Game
This lets you specify the name of the game. This is used to remind you what game you're playing, as well as to find a short rules file to include on the PBM webpage. If you write a rule file for a game, it should go in the minirules/ directory, and its name should match the name given in the game parameter with the following changes made: it should be in lowercase, spaces should be converted to underscores, special characters should be converted to ordinary ASCII equivalents, and it should end with the extension ".php".
Rules
This is the URL for a webpage containing the rules of the game. It is used to create a link to the rules page. As long as the page is at chessvariants.com, you don't have to include the full URL.
Colors
This should be a series of up to ten colors, specified either by six-digit hexcodes or recognized color names. A single space should separate each color.
Patterns
This is like Colors, but it specifies ASCII characters to use as background patterns in ASCII diagrams. It should be a simple string of ASCII characters with nothing separating them. The default is ": !".
Board
This specifies how a board is colored or patterned. It uses a single digit to refer to each of the colors indicated in the Colors parameter, or each of the characters indicated in the Patterns parameter, depending on whether it is a graphic or ASCII diagram. 0 is the first one, 1 the second, and so on. This pattern may be short if it repeats, but it can also be as long as the whole board if the coloring arrangement is peculiar enough to require it. Each rank of the pattern must end with a period. When the period comes before the end of the rank, it repeats for the rest of the rank. When it goes through the entire pattern, it cycles through it again. Through these two cycles of repetition, the pattern for a Chess board can be represented by something as simple as its default value, which is "10.01.". Other common patterns would by "1." for an uncheckered board, and "10.21." for a Cavalier Chess style board.
First
This indicates which player moves first in a game. Although it is normally White, it is Black in some games, such as Shogi.
Player
This is the player whose turn it is in the game. The PBM shows the board from the player's perspective, turning it upside down for the Black player. This value is also used to know when to increment the turn count, which is done whenever it is the turn of the player who moves first in the game.
Files
This lets you designate an alternate set of coordinates for your files. Separate each coordinate with a space. The null space is a valid coordinate label, useful for files on which there are no real coordinates. It will read a null space when you have two spaces with nothing in between. Reuse the same coordinate for different files only when you won't be putting any pieces on the files in the game. Typically, the null space is the only label you should ever reuse for multiple files. The default is to generate a series of lowercase letters, beginning with a and going up to z, as needed.
Ranks
This lets you designate an alternate set of ranks. Works the same as Files, described above. The default is to automatically generate a series of numbers, beginning with 1 and counting up, as needed.

How to Design a Hexagonal Board

It can handle both graphic and ASCII hexagonal boards, but the diagrams here will use ASCII boards to avoid extra revision of this page. There are two types of hexagonal boards. The horizontal type has horizontal rows and left and right slanting columns. The vertical type has vertical columns and up and down slanting rows. The Forsythe code treats a hexagonal board as though it were made only of one set of rows and one set of columns, just as it treats a rectangular board. The difference is in how the PBM displays hexagonal boards.

With boards of either type, it begins with the origin space of a1. For horizontal boards, the rows remain horizontal, but the columns start shifting toward the right. For each row above the first row, it shifts the column half a space to the right. Here is an example of how the normal Chess board looks when it is read as a horizontal hexagonal board:

                  / \ /:\ / \ /:\ / \ /:\ / \ /:\ 
8                | r |:n:| b |:q:| k |:b:| n |:r:|
                /:\ / \:/:\ / \:/:\ / \:/:\ / \:/ 
7              |:p:| p |:p:| p |:p:| p |:p:| p |  
              / \:/:\ / \:/:\ / \:/:\ / \:/:\ /   
6            |   |:::|   |:::|   |:::|   |:::|    
            /:\ / \:/:\ / \:/:\ / \:/:\ / \:/     
5          |:::|   |:::|   |:::|   |:::|   |      
          / \:/:\ / \:/:\ / \:/:\ / \:/:\ /       
4        |   |:::|   |:::|   |:::|   |:::|        
        /:\ / \:/:\ / \:/:\ / \:/:\ / \:/         
3      |:::|   |:::|   |:::|   |:::|   |          
      / \:/:\ / \:/:\ / \:/:\ / \:/:\ /           
2    | P |:P:| P |:P:| P |:P:| P |:P:|            
    /:\ / \:/:\ / \:/:\ / \:/:\ / \:/             
1  |:R:| N |:B:| Q |:K:| B |:N:| R |              
    \:/ \ / \:/ \ / \:/ \ / \:/ \ /               
     a   b   c   d   e   f   g   h

For vertical boards, the columns remain vertical, but the rows start shifting upward. For each column beyond the first, it shifts the row half a space upward. Here is an example of how the normal Chess board looks when it is read as a vertical hexagonal board:



     a   b   c   d   e   f   g  _h_  8
                            ___/:r:\  
                        ___/ n \___/ 7
                    ___/:b:\___/ p \  
                ___/ k \___/:p:\___/ 6
            ___/:q:\___/ p \___/:::\  
        ___/ b \___/:p:\___/   \___/ 5
    ___/:n:\___/ p \___/:::\___/   \  
   / r \___/:p:\___/   \___/:::\___/ 4
 8 \___/ p \___/:::\___/   \___/:::\  
   /:p:\___/   \___/:::\___/   \___/ 3
 7 \___/:::\___/   \___/:::\___/   \  
   /   \___/:::\___/   \___/:::\___/ 2
 6 \___/   \___/:::\___/   \___/:P:\  
   /:::\___/   \___/:::\___/ P \___/ 1
 5 \___/:::\___/   \___/:P:\___/ R \  
   /   \___/:::\___/ P \___/:N:\___/  
 4 \___/   \___/:P:\___/ B \___/      
   /:::\___/ P \___/:K:\___/          
 3 \___/:P:\___/ Q \___/              
   / P \___/:B:\___/                  
 2 \___/ N \___/                      
   /:R:\___/                          
 1 \___/                              
     a   b   c   d   e   f   g   h

How to Create a New Piece Set

A piece set is made from a set of images in a common folder and a PHP file that sets up an array for associating letters with piece images. If you're an editor at this site, you can upload new pieces and the PHP file. Otherwise, you can contact the graphics editor in the form above (which is me), to submit your piece images and piece definition file to the site. Even if you upload them yourself, you should contact me to update this script to use them.

Here is an example of what a piece definition file looks like:

<?
$dir = "http://www.chessvariants.com/graphics.dir/wshogi/";

$pieces = array(
	"b" => "BishopFlip.gif", "B" => "Bishop.gif",
	"d" => "RookPFlip.gif", "D" => "RookP.gif",
	"g" => "GoldFlip.gif", "G" => "Gold.gif",
	"h" => "BishopPFlip.gif", "H" => "BishopP.gif",
	"k" => "KingFlip.gif", "K" => "King.gif",
	"l" => "LanceFlip.gif", "L" => "Lance.gif",
	"m" => "LancePFlip.gif", "M" => "LanceP.gif",
	"n" => "KnightFlip.gif", "N" => "Knight.gif",
	"p" => "PawnFlip.gif", "P" => "Pawn.gif",
	"r" => "RookFlip.gif", "R" => "Rook.gif",
	"s" => "SilverFlip.gif", "S" => "Silver.gif",
	"t" => "PawnPFlip.gif", "T" => "PawnP.gif",
	"v" => "SilverPFlip.gif", "V" => "SilverP.gif",
	"y" => "KnightPFlip.gif", "Y" => "KnightP.gif"
);
$width=42;
$height=45;
$flip = true;
?>

In this example, $dir indicates the directory where all the images can be found. Lowercase letters are assigned to Black pieces, and uppercase letters are assigned to White pieces. Only individual letters may be used for this. The $width and $height variables indicate the dimensions for the spaces. These normally default to 50 and usually don't need to be set here, but the Shogi pieces were smaller than the default pieces. When the $flip variable is set to true, as it is here, it indicates that piece sets should be switched when the board is flipped. It is set to true here, because these pieces are distinguished by orientation rather than by color. The default is for it to be false, and for most piece sets, it does not need to be set in the piece set definition files.

How to Record a Game or Problem and Put it on a Webpage

In brief, you can use the PBM to record and annotate a game or to compose a fairy chess problem, then get code that you can put on a webpage to share your annotated game or chess problem with others.

First, click on the "Record" button to enter Record mode. Select whether you are recording a game or a fairy chess problem. You will see two texts boxes. In the top one, enter a brief description of your game or problem. You don't have to fill out this field if you are recording a game. But you must fill it out if you are doing a problem, because the contents of the other field will be hidden from your visitors when they visit your webpage. The important information to give about a fairy chess problem is what kind of problem it is, such as mate-in-one, figure out the last move, etc.

The second field is for entering moves and annotations. Enter the moves of the game or the solution to the fairy chess problem here. Put each move on a single line, and put all moves in order. You may place a turn number before each move. This will make it easier for another person to read, though the script will not factor this into its move calculations. Adding turn numbers will merely be for the convenience of your readers. You could enter a game without any turn numbers, and the script will be okay with that. Typically, the first two moves should be labeled "1.", the next two "2.", and so on, because each turn has one move by each player.

After any move, you may insert comments, typically annotations to your moves. The script recognizes the symbol // and anything following it on a line as a comment. This style of commenting is common to the programming languages C++ and PHP. It is appropriate to put short comments on the same line as the move. This is useful for brief annotations and for providing the reader with more descriptive notations of each move, since the script itself uses a very bare bones notational system. You may also put a comment on its own line. When you do this, put any comments about a move after the move, because the script will associate any comments immediately after a move with that move. It is alright to enter blank lines, because these will be treated the same as comments.

It is also possible to include alternate lines of play in an annotated game. This is useful when you want to examine moves that someone could have made but didn't. To introduce an alternate line of play, place a vertical bar, the | symbol, at the very beginning of the line. Include the bar at the very beginning of every line and comment in the alternate line of play. When you want to return to the previous line of play, stop adding the bar to the beginning of your line. You may include multiple alternate lines of play on the same move by nesting lines of play or by punctuating lines of play at the same level. To nest lines of play, add another bar for an alternate line of play that occurs in an alternate line of play. You may do this indefinately, adding as many nested lines of play as memory will allow. You may also separate alternate lines of play at the same level by punctuating them with a blank line or comment at a lower level.

To check your work, you can click on the "View" button to view the game you are recording. If you check nothing else, look at the last move of the game and make sure it matches the final position of pieces in the game, as originally played. If you include multiple lines of play, it is also important to test the termination of each line of play. When you are finished testing, use the Back button on your browser to go back to the game you are working on.

When you are ready to insert your game on a web page, click on the "Get Code" button to get the HTML code you should place on your webpage. By placing this code on your webpage, you will provide your readers with a record of the game that can be read from your webpage, as well as viewed move-by-move with the aid of the PBM script. As it appears on your webpage, your game will appear in one or two READONLY TEXTAREA boxes, along with a SUBMIT button that says "View". There may be a box with a brief description, and there will always be a box listing the moves in the game. When you put a fairy chess problem on your webpage, only the description box will be visible. The list of moves will be hidden. When someone views your game or problem, the script will convert the list of moves into a navigation menu, as described in the next section.

How to View a Game or Fairy Chess Problem

When someone provides a sample game or fairy chess problem, as described in the previous section, you may use the PBM to view it. Begin by clicking on the "View Game" button provided on the webpage with the game or problem. This will take you to a display of the game in its starting position, or to the problem with the solution hidden. You will be provided with a menu of all the moves. For a game, the first move will automatically be selected for you. Whenever you view a move in a game, the next move will be selected in the menu. At the opening of the game, this is the first move. This is to make it easier for you to move through the game just by clicking on the "View" button. For fairy chess problems, it will not automatically update the navigation box to the next move. This is to keep the solution hidden from you until you are ready to look at it. Until you choose to look at it, the selected option in the navigation box will say "Look Here for Solution". You can use the navigation box to look at any move in the game or solution. Just select the move you want and click "View". Whenever you select a comment instead of a move, you will be shown the move associated with that comment. When you view a game or problem, you will not be able to edit anything. All you will be able to do is navigate through it.

You can find an example of an annotated game on my page for Voidrider Chess. Here is an example of a chess problem for Cavalier Chess.


Written by Fergus Duniho
WWW Page Created: 12 July 2001.