ChessTutor^TM User Guide

Installing The ChessTutor^TM Applet

ChessTutor^TM is provided as free software to any one who would wish to use it on their web site. The software is provided as a ZIP file and must be unzipped with the -d option to ensure that the directory structure stored in the file is preserved. Note that an unzipping utility, such as WinZIP, that supports long file names is required.

ChessTutor^TM may also be run as a stand-alone application, provided a Java Interpreter is used. For this purpose you will need either a JRE (Java Runtime Environment) or the JDK (Java Development kit). Both can be downloaded from the JavaSoft Homepage.

Download the ChessTutor^TM software.
Actual version: 2.7.1m1 (24-SEP-2000): ca 461 kb

Filtering A Game Database

You may select the filter button to narrow down the number of games displayed in the games list. For instance you may wish to only display games played by a given player, and/or which contain a certain move order. Enter this information in the Filter window, enable the appropriate checkboxes, and press the 'Execute' button, and away you go.

Accessing And Replaying A Game

The ChessTutor^TM applet reads from a game catalog database. You may select one of these catalog entries which will result in a new Window containing a chess board. By selecting from the available buttons, you may play one move at a time, play all the moves in sequence, go back a move, stop a play sequence, or reset the game to the starting position. You may also set use the 'sliding bar' below the moves list to advance or reverse to any place in the game.

As each move is made, the current move is highlighted in the moves list. The moves list is clickable, so that clicking on any one move will cause the chessboard to advance (or reverse) to the position resulting from such a move.

If variations exist for a given move, then the Variations menu will be enabled. When one of the available variations is selected, a new Chess board window will be opened displaying the position at the beginning of the variation. Also, when there are variations at a given move, a blue dot will be displayed by the move. Double-clicking on the move in the moves list will open all the variations at that given move. You may then play through the remaining moves in the same manner described above.

Analysis Of Moves And Positions

As you traverse through each move, comments which have been attached to a move will appear on the right bottom panel of the Window. Hopefully, these comments will give some insight into key moves. At the end of the game, when all moves have been completed, there may also appear an Analysis window with an overview analysis of the entire line of play. Note that not all moves and/or games are annotated, so do not be alarmed when you do not see any commentary or analysis.

Running ChessTutor^TM As A Stand-Alone Application

While the ChessTutor^TM was primarily design to run on a Web browser, it is also possible to run ChessTutor^TM as a stand-alone application using one of the standard Java Interpreters. The ChessTutor^TM applet has been tested under Windows 95/NT with both jview.exe, which comes with Microsoft Internet Explorer 3.0, and with Sun's java.exe, which comes with the Java Development Kit (JDK). For instructions on how to use a Java Interpreter on your Operating System, refer to the instructions that come with the Interpreter.

Note that ChessTutor^TM was written with JDK 1.0.2. Nevertheless we recommend to use at least a JDK/JRE 1.1.6 version, or higher.

Example 1: Running ChessTutor^TM using Microsoft's jview.exe under Windows 95/NT
Change into the directory where the ChessTutor^TM software was installed, and from the command line (or in a DOS batch file) type:

set CLASSPATH=".;ct.zip"
jview ChessTutor

Example 2: Running ChessTutor^TM using Sun's java.exe under Windows 95/NT
Change into the directory where the ChessTutor^TM software was installed, and from the command line (or in a DOS batch file) type:

set CLASSPATH=.:ct.zip
java ChessTutor

Additional Features With The Stand-Alone Mode

When ChessTutor^TM is used as a stand-alone application, in addition to the default catalog of games that is loaded when the software is started, additional PGN databases may be loaded by selecting from the 'Load Catalog' and 'Load PGN DB' buttons. This allows for viewing games which you have created and/or obtained from other sources.

Note
If you wish to change the default catalog that is loaded when the software is started, edit the ct.ini file's 'catalog' parameter to point to the desired catalog or PGN database.

The stand-alone version also allows for saving the current board position as a GIF file. To use this feature, select the 'File Save As' menu option when you want to save a given position to a GIF file.

Running ChessTutor^TM From A Web Server

The files and directories included in ChessTutor.zip provide all the software and data required to setup a Web site. These files and directories may either be placed on a Web server and accessed through a URL, or on your personal computer or workstation, while pointing your Web browser to the path where the files and directories where copied.

The required files which must be placed on the Web server are: ChessTutor.cab and ChessTutor.jar (or ct.zip - see below). The required directories that must be placed on the Web server are the 'res' and 'img' directories and all the files that they contain. Both of these directories must be located in the same directory (the codebase directory - see below) where the ChessTutor.cab and ChessTutor.jar files reside.

Note that Microsoft Internet Explorer 3.0 has problems accessing the images required to run ChessTutor^TM when the software is not accessed through the Web, so in the case of using the software on your local PC or workstation, Netscape 3.0 or higher is strongly recommended.

A sample ChessTutor.html file is included which contains a link to the ChessTutor^TM applet. This is done in an APPLET section as shown below:

<APPLET
   codebase="."
   archive="ChessTutor.jar"
   code="ChessTutor.class"
   id="ChessTutor"
   width="540"
   height="300">
<PARAM name="cabbase" value="ChessTutor.cab">
<PARAM name="select" value="*** Select a sample game or select another PGN URL ***">
<PARAM name="catalog" value="22hastin.pgz;>
<PARAM name="pgn_count" value="2">
<PARAM name="pgn_url1" value="http://www.marochess.de/ChessTutor/22hastin.pgz">
<PARAM name="pgn_url2" value="http://www.marochess.de/ChessTutor/lina1999.pgn">
<PARAM name="background" value="ffffff">
<PARAM name="foreground" value="000080">
<PARAM name="light_square" value="fefffe">
<PARAM name="dark_square" value="008000">
<PARAM name="scale_square" value="80">
<PARAM name="hide_moves" value="0">
<PARAM name="hide_comment" value="0">
<PARAM name="classic" value="1">
<PARAM name="help_file" value="http://www.marochess.de/ChessTutor/ctreadme.html#user_guide">

<B>This page requires a Java enabled browser.</B>

</APPLET>

The various settings for the ChessTutor^TM applet are explained as follows:

• The codebase parameter is used to point to the directory on the web server where the ChessTutor^TM Java files and the associated 'res' and 'img' directories reside. A value of '.' indicates that the ChessTutor^TM files (ChessTutor.cab, ChessTutor.jar, etc) and all associated directories are located in the same directory where the calling HTML resides. You may change the value of codebase to be either an absolute (highly recommended) or relative path where the software resides.
  Example: Your HTML code is in a directory called my_html and ChessTutor^TM files are located in my_java, and both of these directories are located under the main directory of your web server. Then the codebase could be:

      codebase="../my_java"
  

  or

      codebase="http://www.my_website.com/my_java"
  

• The archive parameter points to ChessTutor.jar, a file that is used by the Netscape browser to expedite the loading of the ChessTutor Java software. Note that .jar files are only supported by Netscape 4.0x and later. If your users have Netscape 3.x, then substitute ct.zip for ChessTutor.jar both in the web server and in the HTML.
• The cabbase parameter points to ChessTutor.cab, a file that is used by the Internet Explorer browser to expedite the loading of the ChessTutor^TM Java software.
• The select parameter may be modified to include some other text prompting a user selection.
• The catalog parameter points to a games catalog file, which is used as explained below.
• The pgn_count and pgn_url parameters indicate how many additional PGN databases may be accessed from the software. These entries will enable a PGN URL selection list at the bottom of the main ChessTutor^TM panel. If these parameters are not specified, then the PGN URL selection list will not appear.
• The background and foreground parameters specify the background and text colors used to display the main ChessTutor^TM panel. Use these settings to coordinate your page's color scheme.
• The light_square and dark_square parameters specify the ligth and dark square colors used to display the chess board.
• The scale_square parameter allows for resizing of the board squares and chess pieces. Normally, at 100%, each square is 36x36 pixels. By setting the scale_square to a value other than 100 (in the above example, this parameter is set to 80 or 80%), one can control the overall size of the chess board. If this parameter is not specified at all, the default is 100.
• The hide_moves parameter indicates whether all moves should be shown in the move list when the board window is first displayed. If this parameter is on (value of 1), then moves are only displayed in the move list only after the move is played. This is useful when a problem or puzzle is being shown, so that users can guess the move without the benefit of looking at the move list. If this parameter is not specified, the setting defaults to the off (value of 0) state.
• The hide_comment parameter indicates whether the comment text panel is displayed or not in the board window. To hide the comment panel, specify a value of 1 for this parameter. If this parameter is not specified, the setting defaults to the off (value of 0) state.
• The classic parameter indicates, whether to use a more classic (value=1) or a more modern piece set (value=0). The modern piece set is the default.
• The help_file parameter indicates the name and location of the help file to show (usually this file).

The games catalog file

This file contains a listing of all the available games. A catalog file can either be a standard PGN database, or a compressed PGN database (PGZ). Starting with version 2.1, the old ChessTutor^TM native format is no longer supported. If you have databases in this old format, contact us, and we will provide you with a conversion utility which will convert these databases to standard PGN format.

Important
Note that in order to include a PGN game file, either the title must contain the '(PGN)' tag, or the individual PGN file must end have the '.pgn' file extension.

The ChessTutor^TM applet provides support for the PGN file format. ChessTutor^TM also supports compressed '.pgz' PGN files for multi-game databases. Compressed PGN files have the dual advantage of taking less (about one half) the space on your web site, while also speeding up transmission times over the Web. To generate '.pgz' database files, use the JavaSQZ utility provided at:

The following game shows a sample of the support offered by the ChessTutor^TM applet:

    [Event "?"]
    [Site "Pick of the best Chess Problems, Paperfronts."]
    [Date "1994.??.??"]
    [Round "?"]
    [White "Chess Puzzle #192"]
    [Black "?"]
    [Result "1-0"]
    [SetUp "1"]
    [FEN "6b1/B1bR4/B1Q5/p7/2n1p3/2k5/1R6/K7 w - - 0 29"]
    
    29. Qb5
    {Threatening 30.Qb3#} 
    29... Ne5 
    {29... Nb6 30. Qxa5# 
    or 29... Nd6 30. Qe5#
    or 29... Nxb2 30. Qxb2#}
    30. Bd4# 1-0

ChessTutor^TM supports the following PGN features:

• Multiple games in a single file: ChessTutor^TM supports this feature when the catalog file is set to be a PGN database. Note that for very large PGN databases the memory and transmission speed (in the case of Web sites) with which the software is used will greatly impact performance.
• Header tags: Event, Site, Date, Round, White, Black, Result, and ECO.
• Initial game position: The header FEN and SetUp tags are also supported.
• Move list in standard algebraic notation.
• NAG tags: Only some known '$' tag are decoded by ChessTutor^TM as follows:
  $1=!, $2=?, $3=!!, $4=??, $5=!?, $6=?!
  All other NAG codes are disregarded by the software.
• Sub-variations: the '(' and ')' tags are now supported. The ChessTutor^TM PGN parser will detect variations and sub-variations, making them available during play-back of a game.

ChessTutor^TM PGN Live Update Support

ChessTutor^TM supports automatic updates of a given PGN database.
This feature can be used to show live games as follows:

1. A 'live_check' parameter must be added to the HTML specifying the delay, in seconds between checks of the PGN database. This parameter is specified as an APPLET tag in the HTML file as shown below:
   • <PARAM name="live_check" value="60">
   In the example shown above, a delay of 60 seconds is specified.
    
   
2. The 'catalog' tag points to the PGN database by listing its absolute URL path.
    
   
3. The PGN database to be used for live updates must remain the same in two respects:
   • The number of games in the database must never change.
   • The order of games in the database must never change.
   So if you are featuring the tournament games for a given day, setup a PGN database with all the appropriate header fields and no moves. Then, as the games progress, update each entry in the database by adding moves to each of the games.
    
   
4. Once a database has been updated and uploaded to the Web site, ChessTutor^TM will automatically refresh the database and any open board windows with the latest game information. Note that the ChessTutor^TM checks the date of the database file before refreshing (re-downloading) the database in memory. So that if the date of the file does not change, then ChessTutor^TM does not refresh the information. The user may also press the new 'Refresh' button to force an update at any time.
    
   
5. One thing to note is that when the Live Update feature is enabled, the last move is automatically shown when the board window for a given game is first opened. The user can of course go backwards or to the beginning of the game to review the progress of the game prior to the current move.