This manual documents version 4.6.0 of XBoard. +
This manual documents version 4.7.0 of XBoard.
In Analysis mode you can also make a move by grabbing the piece +with a double-click of the left mouse button +(or while keeping the Ctrl key pressed). +In this case the move you enter will not be played, +but will be excluded from the analysis of the current position. +(Or included if it was already excluded; it is a toggle.) +This only works for engines that support this feature. +
When connected to an ICS, it is possible to call up a graphical
representation of players seeking a game in stead of the chess board,
when the latter is not in use
@@ -319,8 +327,19 @@ FEN (Forsythe-Edwards notation) format unless the oldSaveStyle
option is true, in which case they are saved in an older,
human-readable format that is specific to XBoard. Both formats
can be read back by the ‘Load Position’ command.
-
-variations command-line option is switched on,
@@ -457,11 +478,11 @@ the variation you are now abandoning will be added as a comment
(in PGN variation syntax, i.e. between parentheses)
to the original move where you deviated, for later recalling.
The Home key is a keyboard equivalent to ‘Revert’.
-In most modes, Back to Start only lets you look back at old
@@ -509,7 +530,7 @@ is off, ‘Back to Start’ issue
command, which backs up everyone's view of the game to the start and
allows you to make different moves. If Pause mode is on, ‘Back
to Start’ only backs up your local view.
-
If you are examining an ICS game, the behavior of ‘Forward to
@@ -532,12 +553,12 @@ Up: Menus
The analysis function can also be used when observing games on an ICS
+ You can also tell the engine to exclude some moves from analysis.
+(Engines that do not support the exclude-moves feature will
+ignore this, however.)
+The general way to do this is to play the move you want to exclude
+starting with a double click on the piece.
+When you use drag-drop moving, the piece you grab with a double click
+will also remain on its square, to show you that you are not really
+making the move, but just forbid it from the current position.
+Playing a thus excluded move a second time will include it again.
+Excluded moves will be listed as text in a header line in the
+Engine Output window, and you can also re-include them by
+right-clicking them there.
+This header line will also contain the words 'best' and 'tail';
+right-clicking those will exclude the currently best move,
+or all moves not explicitly listed in the header line.
+Once you leave the current position all memory of excluded
+moves will be lost when you return there.
+
+ Selecting this menu item while already in ‘Analysis Mode’ will
+toggle the participation of the second engine in the analysis.
+The output of this engine will then be shown in the lower pane
+of the Engine Output window.
+The analysis function can also be used when observing games on an ICS
with an engine loaded (zippy mode); the engine then will analyse
-the positions as they occur in the observed game.
- Normally the analysis would stop after reaching the end of the game.
+But when a game is loaded from a multi-game file
+while ‘Analyze Game’ was already switched on,
+the analysis will continue with the next game in the file
+until the end of the file is reached (or you switch to another mode).
+
+ The time the engine spends on analyzing each move can be controlled
+through the command-line option ‘-timeDelay’,
+which can also be set from the ‘Load Game Options’ menu dialog.
Note: Some chess engines do not support Analysis mode.
You can also enter premoves for the first white and black moves
of the game.
- Note that XBoard no longer pays attention to options values specified
+in the .Xresources file.
+(Specifying key bindings there will still work, though.)
+To alter the default of volatile options, you can use the following method:
+Rename your ~/.xboardrc settings file (to ~/.yboardrc, say), and create
+a new file ~/.xboardrc, which only contains the options
+
+ This will cause your settings to be saved on ~/.yboardrc in the future,
+so that ~/.xboardrc is no longer overwritten.
+You can then safely specify volatile options in ~/.xboardrc, either
+before or after the settingsFile options.
+Note that when you specify persistent options after the settingsFile options
+in ~/.xboardrc, you will essentially turn them into volatile options
+with the specified value as default, because that value will overrule
+the value loaded from the settings file (being read later).
+
This section documents the command-line options to XBoard. You can
set these options in two ways: by typing them on the shell command
line you use to start XBoard, or by editing the settings file
@@ -1460,36 +1568,36 @@ Up: Options
Setting this option from the command line is tricky, because you must
type in real newline characters, including one at the very end.
In most shells you can do this by
-entering a ‘\’ character followed by a newline. It is easier to set
-the option from your .Xresources file; in that case you can
-include the character sequence ‘\n’ in the string, and it will
-be converted to a newline.
+entering a ‘\’ character followed by a newline.
+Using the character sequence ‘\n’ in the string should work too, though.
If you change this option, don't remove the ‘new’
command; it is required by all chess engines to
@@ -1588,11 +1701,11 @@ and always (or never) randomize.
You can also try adding other commands to the initString; see the
documentation of the chess engine you are using for details.
- Here is an example of how to set the colors in your .Xresources file.
-The colors shown here are the default values; you will get
-them if you turn Here is an example of how to set the sounds in your .Xresources file:
-
- If XBoard is configured and compiled on a system that includes libXpm,
-the X pixmap library, the xpm pixmap pieces are compiled in as the
-default. A different xpm piece set can be selected at runtime with
-the If XBoard is configured and compiled on a system that does not include
-libXpm (or the Files in the If the bitmapDirectory option is given,
-it is also possible to replace xboard's icons and menu checkmark,
-by supplying files named icon_white.bm, icon_black.bm, and
-checkmark.bm.
-
- For more information about pixmap pieces and how to get additional
-sets, see zic2xpm below.
- The PieceColor options only work properly if the image files
+defining the pieces were pure black & white
+(possibly anti-aliased to produce gray scales
+and semi-transparancy),
+like the pieces images that come with the install.
+Their effect on colored pieces is undefined.
+The SquareColor option only have an effect
+when no board textures are used.
+ An Internet Chess Server, or ICS, is a place on the
+ An Internet Chess Server, or ICS, is a place on the
Internet where people can get together to play chess, watch other
people's games, or just chat. You can use either Some useful ICS commands
include
For example help register tells you how to become a registered
ICS player.
- Some special XBoard features are activated when you are
@@ -2752,11 +2854,6 @@ command-line options as follows:
Or in your .Xresources file:
-
- Then when you run XBoard in ICS mode, you will be prompted
to log in to the firewall host. This works because port 23 is the
standard telnet login service. Do so, then telnet to ICS, using a
@@ -2785,12 +2882,7 @@ command-line options as follows:
Or in your .Xresources file:
-
- Then when you run XBoard in ICS mode, it will connect to
+ Then when you run XBoard in ICS mode, it will connect to
the ICS by using rsh to run the command
‘telnet chessclub.com 5000’ on host ‘rsh.example.com’.
@@ -2803,11 +2895,6 @@ In this case set command line options as follows:
Or in your .Xresources file:
-
- Then when you run XBoard in ICS mode, it will issue the
command ‘ptelnet chessclub.com 5000’ to connect to the ICS.
@@ -2815,8 +2902,7 @@ command ‘ptelnet chessclub.com 5000
that is, your ptelnet program doesn't let you connect to
alternative ports. As noted above, your chess server may allow you to
connect on port 23 instead. In that case, just add the option
-‘-icsport ""’ to the above command, or add
-‘XBoard*internetChessServerPort:’ to your .Xresources file.
+‘-icsport ""’ to the above command.
But if your chess server doesn't let you connect on port 23, you will have
to find some other host outside the firewall and hop through it. For
instance, suppose you have a shell account at ‘foo.edu’. Set
@@ -2824,13 +2910,6 @@ command line options as follows:
Or in your .Xresources file:
-
- Then when you run XBoard in ICS mode, it will issue the
command ‘ptelnet foo.edu’ to connect to your account at
‘foo.edu’. Log in there, then type ‘telnet chessclub.com 5000’.
@@ -2867,7 +2946,7 @@ Up: Top
Game and position files are found in a directory named by the
+ Game and position files are found in a directory named by the
There is no way for two people running copies of XBoard to play
+ There is no way for two people running copies of XBoard to play
each other without going through an Internet Chess Server.
Under some circumstances, your ICS password may be echoed when you log on.
@@ -2946,7 +3025,7 @@ Up: Top
You can report bugs and problems with XBoard using
the bug tracker at
Chris Sears and Dan Sears wrote the original XBoard. They were
responsible for versions 1.0 through 1.2. The color scheme was taken
from Wayne Christopher's The cmail program can help you play chess by email with opponents of
+ The cmail program can help you play chess by email with opponents of
your choice using XBoard as an interface.
You will usually run cmail without giving any options.
@@ -3246,7 +3325,7 @@ Up: Top
Here are some other programs you can use with XBoard
Alternatively, you can add this line to your .Xresources file:
-
- (*) ZIICS is a separate copyrighted work of Andy McFarland.
@@ -3419,7 +3494,7 @@ arising out of or in connection with the use or performance of this
software.
Enhancements copyright © 1992-2003, 2004, 2005, 2006, 2007,
-2008, 2009, 2010, 2011, 2012 Free Software Foundation, Inc.
+2008, 2009, 2010, 2011, 2012, 2013 Free Software Foundation, Inc.
3.3 View Menu
-
-
pixmapDirectory and bitmapDirectory options),
-an external pixmap to be used for the board squares
+(see pieceImageDirectory option),
+external images to be used for the board squares
(liteBackTextureFile and darkBackTextureFile options),
-and square and piece colors for the built-ins.
-3.4 Mode Menu
-
-
3.5 Action Menu
-
-
3.6 Engine Menu
-
-
3.7 Options Menu
-
-
flipView command line option;
if it is false (the default), White's pawns move from bottom to top
at the start of each game; if it is true, Black's pawns move from
bottom to top. See User interface options.
-evalZoom option,
+evalZoom option,
indicating the factor by which the score interval (-1,1) should be
blown up on the vertical axis of the Evaluation Graph.
-gnotify
+gnotify
list on ICS, XBoard will automatically observe all of that
player's games, unless you are doing something else (such as
observing or playing a game of your own) when one starts.
@@ -1069,24 +1152,24 @@ your ICS
variable is set to 0, or if the ICS you are using does not
properly support observing from Black's point of view,
you will see the game from White's point of view.
-saveGameFile command-line
option is set, as in that case all games are saved to the specified file.
See Load and Save options.
-defaultTourneyName option.
-pairingEngine option.
Each Swiss round will be considered a tourney cycle in that case.
Default:0
-defaultMatchGames option.
--firstHasOwnBookUCI true),
it will be made to use the GUI book.
-autoDisplayComment and
+ autoDisplayComment and
autoDisplayTags options, (which control popups when viewing loaded games),
and specify the rate at which loaded games are auto-played,
in seconds per move (which can be a fractional number, like 1.6).
You can also set search criteria for determining which games
will be displayed in the Game List for a multi-game file,
and thus be eligible for loading:
-saveGameFile option),
or the final position of such games (the savePositionfile option).
You can also select 'auto-save' without a file name,
in which case XBoard will prompt the user for a file name after each game.
+In ICS mode you can limit the auto-saving to your own games
+(i.e. suppress saving of observed games).
You can also set the default value for the PGN Event tag that will
be used for each new game you start.
Various options for the format of the game can be specified as well,
@@ -1279,10 +1368,10 @@ and if a tag with info about the score with which the engine came out of book
should be included.
For Chess, always set the format to PGN, rather than "old save stye"!
- -settingsFile ~/.yboardrc
+ -saveSettingsFile ~/.yboardrc
+
+ 3.8 Help Menu
-
-
3.9 Other Shortcut Keys
-
-
@@ -1421,7 +1529,7 @@ Up: Top
4 Options
-4.1 Chess Engine Options
-
-
timeControl period.
+timeControl period.
Default: 5 minutes.
The additional options movesPerSession and timeIncrement
are mutually exclusive.
-movesPerSession moves, a
+movesPerSession moves, a
new timeControl period is added to both clocks. Default: 40 moves.
-movesPerSession is ignored.
+movesPerSession is ignored.
Instead, after each player's move, timeIncrement seconds are
added to his clock.
Use ‘-inc 0’ if you want to require the entire
game to be played in one timeControl period, with no increment.
Default: -1, which specifies movesPerSession mode.
-searchTime
is set, the chess engine still keeps track of the clock time and uses it to
determine how fast to make its moves.
-showThinking must be on for this option to work. Default: -1 (off).
Not many engines might support this yet!
-loadGameFile or loadPositionFile option is set,
XBoard
@@ -1533,35 +1641,42 @@ match is appended to the specified file. If the savePositionFile
option is set, the final position reached in each game of the match is appended
to the specified file. When the match is over, XBoard
displays the match score and exits. Default: 0 (do not run a match).
-matchMode to true is equivalent to setting
+matchMode to true is equivalent to setting
matchGames to 1.
-fcp option for specifying the first engine,
+for engines that were already configured (using the ‘Load Engine’ dialog)
+in XBoard's settings file.
+It will not only retrieve the real name of the engine,
+but also all options configured with it.
+(E.g. if it is UCI, whether it should use book.)
+fe, but for the second engine.
+remoteShell
option described below.)
- new
@@ -1570,10 +1685,8 @@ Default:
4.2 UCI + WB Engine Settings
-
-
adapterCommand.
-fUCI and sUCI, except that they
+fUCI and sUCI, except that they
use the indicated engine with the protocol adapter specified in
the ‘uxiAdapter’ option.
This can then be configured for running an UCCI or USI adapter,
as the need arises.
-fUCI option.
Any identifier following a percent sign in the command (e.g. %fcp)
will be considered the name of an XBoard option, and be replaced
@@ -1667,45 +1780,58 @@ For starting the second engine, any leading "f" or "first" in
the option name will first be replaced by "s" or "second",
before finding its value.
Default: 'polyglot -noini -ec "%fcp" -ed "%fd"'
-adapterCommand, but used for engines accompanied
+adapterCommand, but used for engines accompanied
by the fUCCI or fUSI option, so you can configure
XBoard to be ready to handle more than one flavor of non-native protocols.
Default: ""
-usePolyglotBook option is set to true,
and the option firstHasOwnBookUCI or secondHasOwnBookUCI
applying to the engine is set to false.
The engine will be kept in force mode as long as the current position is in book,
and XBoard will select the book moves for it. Default: "".
-discourageOwnBooks.
-firstXBook).
Default: false.
-4.3 Tournament options
-
-
firstChesProgramNames list
in the settings file by their (implied or explicitly given) nicknames,
one engine per line.
The mentioned engines will play in the tourney.
Volatile option, but stored in tourney file.
-4.4 ICS options
-
-
+sound).
+chessclub.com.
Another popular chess server to try is freechess.org.
If your site doesn't have a working Internet name server, try
@@ -1825,15 +1951,15 @@ specifying the host address in numeric form.
You may also need
to specify the numeric address when using the icshelper option
with timestamp or timeseal (see below).
--useTelnet -telnetProgram program.
-gateway and useTelnet options. The default is
telnet. The telnet program is invoked with the value of
internetChessServerHost as its first argument and the value
of internetChessServerPort as its second argument.
See Firewalls.
-telnetProgram on the given host,
instead of using its own internal implementation
of the telnet protocol. You can substitute a different remote shell
program for rsh using the remoteShell option described below.
See Firewalls.
--icslogon option, inserting some delay between characters
of the logon script may help. This option adds delay
milliseconds of delay between characters. Good values to try
are 100 and 250.
-showThinking must be switched on for
this option to work.
Also diverts similar kibitz information of an opponent engine that is playing you
through the ICS to the engine-output window, as if the engine was playing locally.
--colorize on without specifying your own colors.
-CShout is synonymous with SShout.
-
- xboard*colorizeMessages: true
- xboard*colorShout: green
- xboard*colorSShout: green, black, 1
- xboard*colorChannel1: cyan
- xboard*colorChannel: cyan, black, 1
- xboard*colorKibitz: magenta, black, 1
- xboard*colorTell: yellow, black, 1
- xboard*colorChallenge: red, black, 1
- xboard*colorRequest: red
- xboard*colorSeek: blue
- xboard*colorNormal: default
-
- xboard*soundShout: shout.wav
- xboard*soundSShout: sshout.wav
- xboard*soundChannel1: channel1.wav
- xboard*soundChannel: channel.wav
- xboard*soundKibitz: kibitz.wav
- xboard*soundTell: tell.wav
- xboard*soundChallenge: challenge.wav
- xboard*soundRequest: request.wav
- xboard*soundSeek: seek.wav
- xboard*soundMove: move.wav
- xboard*soundIcsWin: win.wav
- xboard*soundIcsLoss: lose.wav
- xboard*soundIcsDraw: draw.wav
- xboard*soundIcsUnfinished: unfinished.wav
- xboard*soundIcsAlarm: alarm.wav
-
- 4.5 Load and Save options
-
-
@@ -2157,14 +2248,24 @@ Up: Options
loadGameFile option is set, XBoard loads the specified
+loadGameFile option is set, XBoard loads the specified
game file at startup. The file name - specifies the standard
input. If there is more than one game in the file, XBoard
pops up a menu of the available games, with entries based on their PGN
@@ -2081,16 +2171,17 @@ first game of the file when it has reached a specified value.
positions or games in auto-increment matchMode.
See loadPositionIndex and loadGameIndex.
default: 0 (no rewind).
-saveGameFile is set.
-loadPositionFile option is set, XBoard loads the
+loadPositionFile option is set, XBoard loads the
specified position file at startup. The file name - specifies the
standard input. If the loadPositionIndex option is set to N,
the Nth position found in the file is loaded; otherwise the
@@ -2103,27 +2194,27 @@ causes the index to be incremented every two games, so that each position
in the file is used twice (with the engines playing opposite colors).
The rewindIndex option causes the index to be reset to the
first position of the file when it has reached a specified value.
-4.6 User interface options
-
-
@@ -2434,35 +2514,35 @@ Up: Options
logoSize
+is non-zero, next to the white and black clocks, respectively.
+autoLogo is set, XBoard will search for a PNG image file
+with the name of the engine or ICS in the directory specified
+by logoDir.
+recentEngineList, by their nicknames,
@@ -2174,37 +2275,34 @@ the last one is discarded.
Changes in the list will only become visible the next session,
provided you saved the settings.
Default: 6.
-titleInWindow is true,
the window layout is rearranged to make more room for the title.
If tinyLayout is 1, the labels on the menu bar are abbreviated
to one character each and the buttons in the button bar are made narrower.
-coordFont option specifies what font to use.
-monoMode; XBoard will determine if it is necessary.
-flashCount
tells XBoard how many times to flash a piece after it
@@ -2277,33 +2375,33 @@ sets flashCount to 3.
xflash
sets flashCount to 0.
Defaults: flashCount=0 (no flashing), flashRate=5.
-showCoords
+showCoords
is true. If the option value is a pattern that does not specify
the font size, XBoard tries to choose an appropriate font for
the board size being used.
Default: -*-helvetica-bold-r-normal–*-*-*-*-*-*-*-*.
-tol pixels
or less from the desired size. A value of -1 will force
@@ -2311,50 +2409,17 @@ a scalable font to always be used if available; a value of 0 will
use a nonscalable font only if it is exactly the right size;
a large value (say 1000) will force a nonscalable font to always be
used if available. Default: 4.
-pixmapDirectory option, or a bitmap piece set can be selected
-with the bitmapDirectory option.
-
- --disable-xpm option is given to the configure
-program), the bitmap pieces are compiled in as the default. It is not
-possible to use xpm pieces in this case, but pixmap pieces in another
-format called "xim" can be used by giving the pixmapDirectory option.
-Or again, a different bitmap piece set can be selected with the
-bitmapDirectory option.
-
- bitmapDirectory must be named as follows:
-The first character of a piece bitmap name gives the piece it
-represents (‘p’, ‘n’, ‘b’, ‘r’, ‘q’, or ‘k’),
-the next characters give the size in pixels, the
-following character indicates whether the piece is
-solid or outline (‘s’ or ‘o’),
-and the extension is ‘.bm’.
-For example, a solid 80x80 knight would be named n80s.bm.
-The outline bitmaps are used only in monochrome mode.
-If bitmap pieces are compiled in and the bitmapDirectory is missing
-some files, the compiled in pieces are used instead.
-
- -whitePieceColor #FFFFCC
@@ -2375,33 +2440,44 @@ Defaults:
-premoveHighlightColor gray70
-lowTimeWarningColor gray70
- 4.7 Adjudication Options
-
-
-firstScoreAbs and -secondScoreAbs if needed.
Default: 0 (no adjudication)
-4.8 Other options
-
-
@@ -2646,7 +2748,7 @@ Up: Top
viewer on the command line
+will cause the value of the persistent option viewerOptions
+as stored in the settings file to be appended to the command line.
+The view option will be used by desktop associations with
+game or position file types, so that viewerOptions can be
+used to configure the exact mode XBoard will start in when it
+should act on such a file (e.g. in -ncp mode, or analyzing
+with your favorite engine). The options are also automatically
+appended when Board is invoked with a single argument not being
+an option name, which is then assumed to be the name of a
+loadGameFile or (when the name ends in .fen) a
+loadPositionFile.
+Default: "-ncp -engineOutputUp false -saveSettingsOnExit false".
+tourneyFile option,
+and apped the value of the persistent option tourneyOptions
+as stored in the settings file to the command line.
+Thus the value of tourneyOptions can be
+used to configure XBoard to automatically start running a
+tournament when it should act on such a file.
+Default: "-ncp -mm -saveSettingsOnExit false".
+pieceToCharTable option. But on input, piece-ID letters are
first looked up in the nicknames, and only if not defined there,
in the normal pieceToCharTable. This allows you to have two letters
designate the same piece, (e.g. N as an alternative to H for Horse
in Xiangqi), to make reading of non-compliant notations easier.
Default: ""
-remoteShell. The default is your local user name.
-5 Chess Servers
-telnet or a
client program like XBoard to connect to the server. There are
@@ -2679,25 +2781,25 @@ unique guest name for you.
-
xboard -ics -icshost firewall.example.com -icsport 23
- XBoard*internetChessServerHost: firewall.example.com
- XBoard*internetChessServerPort: 23
-
xboard -ics -gateway rsh.example.com -icshost chessclub.com
- XBoard*gateway: rsh.example.com
- XBoard*internetChessServerHost: chessclub.com
-
- xboard -ics -telnet -telnetProgram ptelnet
- XBoard*useTelnet: true
- XBoard*telnetProgram: ptelnet
-
xboard -ics -telnet -telnetProgram ptelnet -icshost foo.edu -icsport ""
- XBoard*useTelnet: true
- XBoard*telnetProgram: ptelnet
- XBoard*internetChessServerHost: foo.edu
- XBoard*internetChessServerPort:
-
7 Environment variables
-CHESSDIR environment variable. If this variable is not set, the
current working directory is used. If CHESSDIR is set,
XBoard actually changes its working directory to
@@ -2885,7 +2964,7 @@ Up: Top
8 Limitations and known bugs
-9 Reporting problems
-https://savannah.gnu.org/projects/xboard/
or by sending mail to <bug-xboard@gnu.org>. It can also
@@ -2975,7 +3054,7 @@ Up: Top
10 Authors and contributors
-XChess program.
@@ -3036,7 +3115,7 @@ Up: Top
11 CMail
-12 Other programs you can use with XBoard
-
@@ -3375,10 +3454,6 @@ FRITZ4 set. These files are named “fritz4.*” in the ZIICS distributi
xboard -pixmap ~/fritz4
- xboard*pixmapDirectory: ~/fritz4
-
Published by the Free Software Foundation
59 Temple Place - Suite 330
@@ -4161,580 +4236,599 @@ Up: Top
Index
-
Table of Contents