crafty(6)

💖 crafty(6) — the chess engine that's literally the moment 💖

okay bestie, sit down, hydrate, because we're about to talk about crafty, a chess engine in section 6 of the manual. no graphic user interface, no frills, just vibes and chess. 🦋

---

✨ SYNOPSIS ✨

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

that's it. that's the whole invocation. so clean. so minimal. we love her for it. 💅

---

🌸 DESCRIPTION 🌸

so here's the tea: Crafty is a chess "engine". meaning the program is only about playing chess and is absolutely not here to give you a graphic user interface. it's giving brains-not-beauty, and honestly? respect.

so the way you usually use her is indirectly, via XBoard — and current versions of these two programs generally work very well together. iconic duo behavior fr fr. 🫶

some noteworthy features of Crafty, since you asked:

• 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. (translation: some of it is ✨ for the girlies who read assembly at 3am ✨ and some of it will humble you. both are fine.)
• 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. so yes, this whole page is basically a paths lore dump. buckle up. 🎀
• Easy graphic user interface via xboard(6). look at that, the bestie does the pretty part for her.
• Informative log files. writes a "game.nnn" file storing the current game in PGN format, and also writes a "log.nnn" file recording what the engine was "thinking". not me reading the engine's diary 💀
• 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. she's a student of the game, lowkey.
• Uses endgame tablebases. precompiled tablebases in the appropriate format are freely downloadable from ftp://ftp.cis.uab.edu/hyatt/TB. free downloads, we stan. 💜
• 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. so like. do not rebrand her. do not catfish a tournament. that's not the move. 🚫
• Annotation. generates either PGN or HTML files, in a manner made very flexible by choosing appropriate aptions to the "annotate | annotateh" command. (yes it says "aptions", we are leaving that typo exactly where we found it, it's part of the family now, no cap 🫶)

---

👑 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 path things:

• bookpath — where Crafty seeks its opening books and writes learned knowledge.
• logpath — where Crafty normally writes a pair of files "game.nnn" and "log.nnn" for each game it plays.
• rcpath — where Crafty looks for a run control file to be read only.
• tbpath — where Crafty looks for endgame tablebase files to be read only.

the four path specifications have a number of things in common, and this is the important part so listen: 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. that's a hard no, bestie. 🛑

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". three sources of truth, pick your fighter. ⭐

---

🎀 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. so like, launch her somewhere she has write perms, okay? 🙈

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. she's keeping receipts on herself. queen behavior. 👑

🧚 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.

---

🔥 SEE ALSO 🔥

craftyrc(5), xboard(6), /usr/share/doc/crafty

---

🌸 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. a whole timeline, we love a glow-up story. ✨

---

💀 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. so like. don't hand her a cursed path. that's a crash, not a vibe. 😭

this manual page itself will probably always be flagrantly incomplete in that many essential, powerful, and interesting aspects of Crafty are not even mentioned. the page is self-aware, honestly iconic of it.

---

🫶 AUTHOR 🫶

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

---

okay that's the whole page, bestie — this was Crafty 19.8, dated December 22, 2003, straight from section 6 of the manual. go forth and let her cook. 🎀💖✨