Ubuntu Manpage: crafty - chess engine

NAME

       crafty - chess engine

SYNOPSIS

       crafty [bookpath=<directory>] [logpath=<directory>]
       [tbpath=<directory-list>]

DESCRIPTION

Crafty is a chess "engine". That is, the program concerns itself with playing chess and
not with providing a graphic user interface. Thus Crafty is commonly invoked indirectly
via XBoard, and current versions of these programs generally work very well together.
Some noteworthy features of Crafty are:

* Source code, provided, is unusually deserving of study. The author has sought to
provide a starting point for others writing chess-playing programs, leading to clean
and portable code. Another objective has been to maintain a state-of-the-art chess
engine, with the result that some parts of the source code may be challenging to
understand.

* Flexible and powerful command-line interface. About the only thing that can not be
done within the CLI is changing various paths determining where Crafty reads and writes
various files. This manual page focuses on explaining these paths.

* Easy graphic user interface via xboard(6).

* Informative log files. Writes "game.nnn" file storing current game in PGN format, and
also writes "log.nnn" file recording what the engine was "thinking".

* Intelligent opening play. Crafty learns from experience, and makes appropriate
modifications to its opening book. The "book" command allows generation of an opening
book (from PGN data), and customization of how it is used. The learning facilities
synthesize several different approaches, and allow various ways for the user to
customize and follow what is being learned. Additional commands allow easy creation of
files to customize how Crafty plays the opening against humans and against other
computer programs.

* Uses endgame tablebases. Precompiled tablebases in the appropriate format are freely
downloadable from ftp://ftp.cis.uab.edu/hyatt/TB.

* Polished and powerful facilities for Internet play (for which the program continues to
be extensively used). Note that the licencing forbids concealing Crafty under another
name, or unauthorized entry of it in a tournament in which other computer programs have
been invited to compete.

* Annotation. Generates either PGN or HTML files, in a manner made very flexible by
choosing appropriate aptions to the "annotate | annotateh" command.

OPTIONS

       In the command line  arguments,  <directory-spec>  is  a  path  to  a  directory,  whereas
       <directory-list>  is  a  non-empty  sequence  of  paths  to directories.  For portability,
       several different characters are taken as path separators: the colon  (:),  the  semicolon
       (;), and the comma (,).

       There  are  actually  four  of these: bookpath is where Crafty seeks its opening books and
       writes learned knowledge; logpath  is  where  Crafty  normally  writes  a  pair  of  files
       "game.nnn"  and  "log.nnn"  for each game it plays; rcpath is where Crafty looks for a run
       control file to be read only; and tbpath is where Crafty looks for endgame tablebase files
       to be read only.

       The  four path specifications have a number of things in common:  each has a default value
       set when Crafty is compiled, which can then be modified  by  the  appropriate  environment
       variable,  and  can  then  again  be  modified  by  an invocation argument, but can not be
       modified after the engine has been initialized (thus, in particular, it is not possible to
       modify  the paths by editing a run control file).  Possibly the best procedure is to avoid
       the invocation options, experiment  with  the  environment  variables,  and  then  perhaps
       recompile  the program with different defaults.  Note that if the program is compiled "out
       of the box" then all four values default to "./" (the directory in which Crafty  has  been
       launched).

       Crafty  can  be  invoked with other arguments (such as "xboard" to indicate that Crafty is
       being invoked through xboard(6)) which would not usually be used directly.

COMMANDS

       Crafty's  extensive  command-line  interface  is  defined  in  "option.c",  discussed   in
       "crafty.doc", and briefly described by the command "help".

FILES

Run control
Crafty tries to read a run control file rcpath/.craftyrc. (On a non-Unix system,
".craftyrc" changes to "crafty.rc".) Such a file should contain a sequence of valid
Crafty commands, terminated by the command "exit" to restore standard input to the
keyboard. See craftyrc(5) for a skeletal example.

Logging
When a game is played, Crafty normally writes "logpath/game.<nnn>" and
"logpath/log.<nnn>". Details of what is written are modifiable by the `log' command.
Because $CRAFTY_LOG_DIR defaults to "./" (the directory in which Crafty is launched),
trouble can occur if the program is launched in a directory to which it is unable to
write. Note that the "log.<nnn>" file normally contains all output that would be visible
if Crafty were run from the command line but is usually hidden when it is run from a GUI.

Opening books
Crafty is designed to maintain its chess opening knowledge in a file "book.bin", and to
modify this file as it learns from its mistakes. Refer to the documentation for the
"book" command for information on generating and customizing usage of "book.bin".

Further, files "books.bin" and "bookc.bin" allow easy customization of Crafty's opening
play (against humans and computer, respectively). See the documentation for the "books"
command.

Finally, there are several files "*.lrn" for synopses of what Crafty has been learning.
See the documentation for the "learn" command.

Endgame tablebases
When normally configured, Crafty reads late endgame knowledge from "*.emd" files, which
are distance-to-mate tablebases. See the documentation for the "egtb" command.

ENVIRONMENT VARIABLES

   CRAFTY_BOOK_PATH
       If  $CRAFTY_BOOK_PATH  is  set,  it  overrides the compiled value of bookpath, the path to
       directory containing "book.bin" and friends.  Unless learning has  been  disabled,  Crafty
       will be writing in this directory.

   CRAFTY_LOG_PATH
       If  $CRAFTY_LOG_PATH  is  set,  it  overrides  the  compiled value of logpath, the path to
       directory for writing, but not reading, the log files.

   CRAFTY_RC_PATH
       If $CRAFTY_RC_PATH is set, it  overrides  the  compiled  value  of  rcpath,  the  path  to
       directory for reading, but not writing, a run control file (".craftyrc" or "crafty.rc").

   CRAFTY_TB_PATH
       If  $CRAFTY_TB_PATH  is  set,  it  overrides the compiled value of tbpath, the sequence of
       paths to directories for reading, but not writing, endgame tablebase files.

HISTORY

       Crafty is the son of Cray Blitz, also written by Bob Hyatt.   The  subsequent  history  of
       Crafty  is  detailed  in the source file "main.c".  Opening books appeared in version 1.9.
       log files in 1.11, endgame tablebases in 8.24, run control files in 9.22, and  environment
       variables in 16.5.

BUGS

       In  the  interests of portability, Crafty deals with files in a simple manner, at the cost
       of robustness.  Very long or incorrect paths may result in a "segmentation fault"  when  a
       file writing operation fails.

       This  manual  page  itself  will  probably  always  be  flagrantly incomplete in that many
       essential, powerful, and interesting aspects of Crafty are not even mentioned.

AUTHOR

       Robert Hyatt (hyatt@cis.uab.edu).