BeholderBoard Virtual Chess-set v1.52 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For playing chess with your friends over the web using a single cgi-script (plus graphics files). You need: + web server running Perl 5 + the BeholderBoard virtual chess-set + friends or equivalent ======================================================== ** for the latest information, check the FAQ at ** http://www.beholder.co.uk/chess/ ======================================================== Readme Contents: + Components + Features + Changes in Version 1.51 + Changes in Version 1.5 + Implementation + Board Title + Hidden Boards + Passwords + E-mail Notification + Special Moves + End of Game + Move Notation + Inside Data Files + Known Problems + Standard Disclaimer ======================================================== Components ^^^^^^^^^^ The BeholderBoard virtual chess-set consists of: board.pl cgi script (Perl 5) *.gif chessmen graphics index.html example this readme Features ^^^^^^^^ The BeholderBoard is a virtual chess-set. It lets friends play chess on your web server. Some of the things the BeholderBoard offers: + up to 999 boards on the go + rather lovely chess pieces + output with or without Javascript + move list output in SAN + email notification of moves + scalable, flippable boards + hide/show labels, captives, moves + password protection + hidden boards for shy games + deviant chess, whatever that is Two things the BeholderBoard doesn't do, despite what some people expect: - detect "game over" conditions - allow players to set up their own games The first deficiency may one day be resolved in a future release. Currently, you'll know when you've been checkmated because, uh, you won't be able to move out of it, but the BeholderBoard will let stalemate conditions slip past unnoticed. The second issue won't change: the BeholderBoard is just the chess-set, not the games room. However, there are already scripts out there which set up BeholderBoard games up on-line. The BeholderBoard FAQ points you in the right direction for this sort of thing. With this in mind, the BeholderBoard's underlying data format is deliberately easy to follow, to help those of you who want to write scripts for setting up and managing games. Changes in Version 1.52 ^^^^^^^^^^^^^^^^^^^^^^^ Version 1.52 is a bug-fix release. An error in the legal move detector under certain circumstances allowed a king escaping check to settle on a square adjacent to the opposing king. This is fixed in v1.52. This version is otherwise identical to version 1.5 (see below). There was, briefly, a release v1.51 which didn't quite fix the bug properly, hence v1.52. Changes in Version 1.5 ^^^^^^^^^^^^^^^^^^^^^^ Version 1.5 fixes a sneaky little bug which prevented pawn promotion on Javascript-disabled boards. It also introduces two new features: a "flip board" option for inverting the display, and the long-overdue "Resign" move. This means the control panel has been changed a little, to accommodate the extra check-box. Otherwise, things are much the same as before - importantly, the underlying data format remains unchanged, which means existing games will continue seamlessly under v1.5. The graphics files have been optimised so they are a bit smaller with no discernable difference in their appearance. Version 1.5 naturally incorporates all the changes made in previous versions, including the 1.41 "en passant bug" fix if you knew about that. If you are running an earlier version of the BeholderBoard, you should upgrade. You don't need any of the graphics files, because they haven't changed - just the replace the old script with the new one, and save a copy of this readme. *** remember to modify the local config variables *** *** at the top of the script when you install it! *** A new config variable has been introduced - $HELPURL - which allows you to specify a help page for players. By default this set to http://www.beholder.co.uk/chess/help.html - if you prefer to keep everything internal, copy it and modify or create a better one of your own and change the $HELPURL variable accordingly. Implementation ^^^^^^^^^^^^^^ Put board.pl anywhere in your cgi-bin. Rename it if you want. Remember that the script will need x permissions for the daemon to run it (and possibly the setuid bit, depending on how you manage cgi permissions). The *.gif graphics must live somewhere beneath your http server root. A /chess directory seems like a good idea. A sample index.html is provided for you to drop in there too. This is for humans; the script doesn't care. The virtual chess-set has a data file for every board it's using. By default these are called board???.txt where ??? runs 001-999. These live in the chess-set's data directory, which by default is the same directory that you've put the script in. You can change this. The simplest way to set up a board is to create an (empty) data file (e.g. board001.txt) in the data directory. The data files must have rw permissions that let the process which handles cgi fiddle with them. You can add a title, passwords and email addresses (to which to send notification of moves) to a board at any time, by editing the data file - even before the game begins. So it's possible, when setting up a board, that the data file is not empty. See the details in the rest of this readme for specific information. To remove a board, delete the data file. You cannot set up, or remove, a board over the web. This is a security feature. You have to do it on the server. **-------------------------------------------------------- ** YOU MUST edit the configuration variables at the ** top of board.pl to match your local configuration ** before the script is used **-------------------------------------------------------- Board Title ^^^^^^^^^^^ You can give a board a title. Actually this is recommended. To do this, make sure the data file somewhere includes a single line starting with "title: ". The title can include embedded html. Don't get carried away though (because this also gets displayed in the "List of Boards" table, and can look very ugly), and keep it all on one line. For example: title: The Immortal Game
Tyrell v. Sebastian You cannot set up, or change, a board's title over the web. This is a security feature. You have to do it on the server. Hidden Boards ^^^^^^^^^^^^^ All the boards the virtual chess-set has are public: anyone who can find them can look at them. If you are playing particularly badly, you may prefer to hide a board. This removes it from the displayed list of available boards that the script normally creates. It doesn't stop anyone looking at the board, but it doesn't encourage them to try. To make a board hidden, enclose the title with parenthesis, For example: title: (I'm Shy) To see (or play on) a hidden board, you have to pass the board number to the script manually with the name "bd". (e.g. "http://www.your_url/your_cgi/board.pl?bd=106" for board 106). If you want to prevent the public spectating on *all* games, you will have to restrict the access to the cgi-bin directory which contains the script (and probably data) instead. Use htaccess (or your server's equivalent) to force a resource password before the script can be accessed. Passwords ^^^^^^^^^ Moves can be password protected. This prevents onlookers fiddling with the pieces (unlike a real chess-set). Each player has their own password to stop them fiddling with each other's pieces (also unlike a real chess-set). Unless you specifically set them, a game starts without passwords. The first time a player makes a valid move accompanied by a password, it's set and fixed for the rest of the game. Thereafter any attempt to move without the right password is rejected. If you don't submit a password (and you haven't already set one), no password is expected. This is a feature, but is open to abuse if a scallywag happens across the board and sets the password themselves. For obvious reasons this may be considered too risky, especially if your area of the web is scallywag-infested. You can paste password declarations from an established data file into the empty one when you create a new board data file. In this way the passwords are set before the game begins. Passwords are encrypted, so you can't really change them, but you can edit the data files. Just delete the line containing the password setting (it's self-evident) to remove it. To set a known password, use cut-and-paste. You cannot remove, or change, a player's password over the web. This is a security feature. If you have to do it at all, you have to do it on the server. E-mail Notification ^^^^^^^^^^^^^^^^^^^ The BeholderBoard includes the optional facility of e-mail notification. To enable this, you must provide the name of your mailer in the local configuration section at the top of the script. Alternatively, you can disable the facility on ALL boards by setting this to be blank ('') [this is clearly commented in the script]. To enable e-mail notification for a player on a given board, edit the data file to include a line starting with "email:", followed by the colour of the player's pieces, followed by the player's email address. For example, adding this line anywhere in the board's data file... email: black sebastian@tyrell.com ...results in an e-mail notification being sent to sebastian@tyrell.com every time white makes a move on this board. You can abbreviate the colour to b or w. Obviously, if both players are to be notified when the other moves, you'll need to enter two such lines, one for each player. As there is a potential risk in piping to a command (such as the mailer), which is how this is implemented, the BeholderBoard does do a basic check on the components of the email address before passing it through the pipe. This will fail silently if the email address appears (from the script's point of view) to be malformed. So make sure you type email addresses in carefully. Note that the system is anonymous: the BeholderBoard never reveals one player's email address to another. The chances are that you'll arrange for players to be able to communicate with each other anyway (especially useful for resignation), but that's something for you to do, not the BeholderBoard. If you suspect the email notification is not working for you, check that you have provided the correct mailer name (and path) in the local configuration section of the script, that the board in question has a line commencing "email:" for the player to be notified, and that the email address there does not contain any spurious or curious characters. You may prefer to set the Reply-to field to the other player's email, provided they have one and your mailer supports it. As this breaks the BeholderBoard's policy of anonymity, you'll have to modify the script yourself if you want to do that. You cannot add, remove or change the notification e-mail address of a player over the web. This is a security feature. You have to do it on the server. Special Moves ^^^^^^^^^^^^^ The BeholderBoard detects and rejects attempts to make illegal moves (unlike a real chess-set). There are four times when you may make a special move: these are, specifically, castling, capturing en passant, pawn promotion, and resigning. To indicate a castling move, move the king two squares (like a real chess-set). To take en passant, move the capturing pawn onto the empty square behind the captured pawn (like a real chess-set). When a pawn qualifies for promotion, the BeholderBoard will ask you what it wants to be. To resign, enter your king's position and the opposing king's position (an impossible move of kingly proportions) - the BeholderBoard knows what you mean, and will ask you to confirm your resignation before carrying it out. End of Game ^^^^^^^^^^^ The BeholderBoard does NOT detect stalemate or checkmate conditions (just like a real chess-set). This is down to the players. By definition no move is legal from a checkmate position, so you can't play beyond it, but be aware that the BeholderBoard will, in its ignorance, allow a game to pass through a stalemate condition without comment. Move Notation ^^^^^^^^^^^^^ The data files are a non-standard but helpfully readable format which makes it easy for you to edit the board position if you need to (for setting up a puzzle, for example - see next section). The move list, however, adheres to the internationally recognised Standard Algebraic Notation (short form). Inside Data Files ^^^^^^^^^^^^^^^^^ The data files are deliberately human-readable: look at one that the script has processed and you can edit it (for example) to set up a particular board position, or remove your friend's pieces if they are doing too well. The script expects to find the data files as it left them: format error-checking is minimal so you should be wary of making brash changes. Data format for a board's square is bX black piece } X = p|r|n|b|q|k { upper case: never moved wX white piece } { lower case: has been moved -- empty -+ empty, current en passant target (don't worry about it) For example, the data description of a board position might be: black to move bR bN bB bQ bK bB bN bR bP bP bP bP -- bP bP bP -- -- -- -- -- -- -- -- -- -- -- -- bp -- -- -- -- -- -- -- wp -- -- -- -- -- -- -- -- wn -- -- wP wP wP wP -- wP wP wP wR wN wB wQ wK wB -- wR Look inside any data file *after* it has been processed by the script to see these in use. If you're just playing regular chess then you probably never need to know this anyway. The BeholderBoard never analyses the move list, it just stores it as a service to humankind. Therefore nothing you do to the move list in the data file will affect the board position. Similarly, if you modify the board position, the move list will NOT be updated and will be out of synch. The BeholderBoard has a policy of not checking its data files - now it tries to be cool about data no matter how foolish it considers it to be. This means that if you edit your data file to describe a game on a 10 x 12 board with extra queens, then that's what it will try to let you play. Given that the BeholderBoard is unsupported freeware anyway, be warned that this feature (i.e. deviant chess) is <> unsupported. If that doesn't put you off, you should know that "in check" is interpreted to mean that *any* of your kings is in check (that's intuitive), and "castling" is always understood to be an unmoved king's move through two empty squares, along a rank, with an unmoved, unobstructed rook at the edge of the board - which sometimes, therefore, might not be defined on a deviant board (that's not quite so intuitive). And wherever you place them to start with, white pawns always advance up the board, and black pawns down. The deviant board thing is a feature, not a bug. It's a side-effect of not performing harsh integrity checks on the data files and being very general in the Perl. Therefore, the warning about messing with your data files still applies: if you mess them up, it is possible that the script will crash, inelegantly. That is to say, despite its laxness, the BeholderBoard still hopes to find a rectangular board containing chess pieces and will get unpredictably upset if it's disappointed. Also, introducing lots of kings of the same colour on a massive board may result in ponderous response times, since the script has more to think about. Deviant boards more than 26 squares across will be clipped (because beyond that the labels run out of letters... and anyway, this is doubly unsupported, remember?). On large deviant boards, don't check "hide labels" if you want to see how the squares go "h8, i9, ja, kb...". For the move list, the short-form SAN notation is still unambiguous on a large deviant board provided that you remember a single letter is describing a rank not a file (i.e. Qb-a1 is the queen on rank b, not the Queen on, uh, file b (which would be reported as something like Qab-a1 (and be careful about l (the letter L) and 1 (the number))) ...but if you have more than one king then the castling notation can be ambiguous. Well what do you expect? Remember that none of this need concern you if you are just playing a sensible, normal game of chess. Which is what you should be doing. Known Problems ^^^^^^^^^^^^^^ Check http://www.beholder.co.uk/ from to time to time to see if there's anything new in the chess FAQ. Remember that the BeholderBoard won't check for stalemate or checkmate positions. This is a feature. Since v1.4, the BeholderBoard has graciously supported browsers that can't cope with Javascript. In particular, some versions of IE4 dislike the use of "document" object in the j-script: such browsers will fail with an error window; clear the error and click the "Disable Javascript" link at the bottom of the page. Better still, get a better browser. If you prefer to guide players directly to non-Javascript boards, pass dj=1 to the script (e.g. http://your_domain/cgi/board.pl?dj=1). You should NOT be running it with Perl's -w (warnings) switch, simply because, if you do, certain system errors (notably bad http headers which nobody gets anyway) will uglify the output (that's all). Remember though that the BeholderBoard does only minimal checking of the data files - if you mess them up, weird or ugly things WILL happen. See the section on deviant chess, in "Inside Data Files" above, for why this is a feature, not a bug. The smaller options window is not set to "always float" above the main window. It used to be, and it was very annoying, so it doesn't any more. If you think you have lost it, you should look under the main window first of all. If you really _do_ lose the smaller options window, you can get it back by reloading the page (ctrl-R on Netscape). If you use a large font size on your browser, text may be lost off the smaller options window. You can resize the window to fit. If you set a very small square size, you may also need to reduce your browser's font, since the empty squares' minimum height is affected by that. (Incidentally, v1.4 allows you to get away with smaller squares than you could before, but ultimately you'll hit the same problem). For a similar reason, it may also help to check "hide labels" if you are going for a really tiny board. If you set a very large square size, you may also need to buy a bigger monitor, since most browsers won't extend the board beyond the width of the main window. Generally, the height expands OK but the browser tries to squash the width to get as many squares on the screen as it can. If the BeholderBoard won't let you move because it says your password is duff and you know it isn't, suspect (a) CAPS LOCK and (b) fast-moving scallywags (see Passwords section above), in that order. The reason there are two .gif files for each piece (one on black square, one on white square), despite the use of transparency, is to avoid anti-aliasing artefacts. The chess-set was originally a graphic exercise, after all ;-) BeholderBoard v1.41 fixed a bug which prevented en passant moves, and v1.5 fixed a bug which prevented pawn-promotion on Javascript-disabled boards - currently there are no known problems with the legal move detector. Any problems or bug reports (please include the data file and which version of which browser you were using) to cartoons@beholder.co.uk Standard Disclaimer ^^^^^^^^^^^^^^^^^^^ The BeholderBoard Virtual Chess-set is freeware. You may use it and distribute it to your friends freely, but you may not charge any money for it. If you pass it on to somebody else, please include the entire package, including this readme. If you did not receive these files directly from Beholder, perhaps you should look there in case a more recent or more trustworthy version is available. You'll find it somewhere below http://www.beholder.co.uk/ Like all such software, the BeholderBoard Virtual Chess-set is distributed as-is, and no warranty of any kind is provided. Good policy on all software is to check to your own satisfaction that the software adheres to your local requirements, especially with regard to security, before making it executable over a public network. The script passes Perl's taint checking (try perl -cwT), which may make you feel more comfortable. Nonetheless, Beholder accepts no responsibility for any loss or damage (or loss of productivity) whether caused directly or indirectly as result of the use of this software. The design of the chess-set (script and graphics) remains (c) copyright Beholder 1999. (Actually it was created as an exercise to get experience with a particular 3d modeler). You're welcome to use the pieces for playing on the BeholderBoard, or perhaps as decorations on personal web pages. But you may not include them in any commercial product without permission. Be reasonable. I think I am. There's no need to register (strictly speaking, there's no support anyway) but it's interesting to hear from anyone who installs a BeholderBoard somewhere out there even if it's just to say "hello". Thanks to all of you who sent feedback on previous versions. cartoons@beholder.co.uk www.beholder.co.uk Bangkok 5th March 1999 v1.5 updated UK, 14-Nov-99 v1.52 updated UK, 02-Aug-00