=head1 NAME

fairymax - xboard-compatible chess and chess-variant engine 'Fairy-Max'


=head1 SYNOPSIS

B<fairymax> [hashSize] [iniFile]

B<shamax> [hashSize] [iniFile]

B<maxqi> [hashSize] [iniFile]


=head1 DESCRIPTION

B<fairymax> is a program that plays chess and chess variants. 
It uses the xboard/winboard chess-engine protocol to communicate.
Apart from 'regular' chess (also known as the Mad-Queen variant),
it can play Capablanca chess, gothic chess, janus chess, knightmate, cylinder chess, 
berolina chess, superchess, makruk (Thai chess, and also some of its
variants, Cambodian chess (Ouk), asean chess and ai-wok),
courier chess, Seirawan chess, Spartan chess, falcon chess, great shatranj,
team-mate chess, charge of the light brigade, king of the hill, bifurcator chess,
Los-Alamos chess, Mexican chess, Ciccolini's chess, grande acedrex,
wildebeest chess (almost),
shuffle chess without castling and chess with different armies
(all combinations of the FIDE, Clobberers, Nutters and Rookies armies).
Fairy-Max can be easily configured by the user to play other variants as well,
by modifying the ini file.
This ini file describes the rules of movement
of the participating pieces and the initial board setup.

Fairy-Max can also play shatranj, 
but in this case is not aware of the shatranj rule that a bare king loses.
So it might play sub-optimally in the late end-game.
A version of Fairy-Max adapted to implement the baring rule
(and the rule that stalemate is a win)
is available under the name B<shamax>.
Grande Acedrex and Courier Chess might also have had a baring rule,
so you may want to play these with shamax instead of fairymax too.

Similarly, a version of Fairy-Max adapted to play Xiang Qi (Chinese Chess)
is included in the fairymax package as well, under the name B<maxqi>.

B<fairymax> is a derivative of the world's (once) smallest chess program 
(source-code wise), micro-Max.
The latter measures less that 2000 characters, (about 100 code lines),
and has a computer rating of around 2050 on the CCRL rating list.
Although this is about 1000 rating points behind the world champion,
micro-Max still makes a quite tough opponent even for club players,
but it is not unbeatable.

The main difference between micro-Max and Fairy-Max is that the latter loads
its move-generator tables, which specify how the various pieces move,
from an external file, so it can be easily adapted to incorporate un-orthodox pieces.
For ease of use of the artificial-intelligence, Fairy-Max is equipped with
I/O routines that allow it to run with the xboard graphical user interface.

See xboard(6) for instructions about how to use B<fairymax> through xboard. To
start up quickly, you just need the command: B<xboard -fcp fairymax>.
Note that to be able to play the chess variants, it is recommended to use
the latest XBoard version, as some of the recently added variants will use
features not supported by older XBoard versions.

Fairy-Max supports multi-PV mode: by specifying a non-zero multi-PV margin in the
Engine-Settings dialog of XBoard, Fairy-Max will not only print the
principal variation for the best move, but also for every move that approaches
the score of this best move to within the set margin.
(If it does not find the best move on the first try, this might lead to printing
of a few extra lines below the threshold.)
Fairy-Max now also supports analysis mode, and exclusion of moves from the analysis.

Amongst the move types supported by Fairy-Max are normal leaper and slider moves,
(e.g. knight and rook),
divergent moves (i.e. capture and non-capture moves can be different),
hoppers (which jump over other pieces, such as the Chinese cannon or the grasshopper),
lame leapers (the move of which can be blocked on squares they cannot move to,
such as the Chinese horse and elephant),
limited-range sliders (upto range 5),
and any combination thereof,
in every possible direction.
The board width is configurable upto a width of 14 files,
and cylindrical boards (where left and right edge connect) are supported as well.
The board height can be configured up to 16 ranks.

=head1 OPTIONS

=over 8

=item B<hashSize>

If the first argument to fairymax is numeric,
it is taken as an indicator for the amount of memory Fairy-Max is allowed to use
for its internal hash table.
The default value for this argument, 22, would result in a memory usage of 48MB.
Each next-higher number doubles the memory usage, each next-lower halves it.
Running with less than 6MB (i.e. argument 19) is not recommended.
When fairymax is running under xboard 4.3.15 or later the hash-table size can be set 
through the xboard menus,
making this argument superfluous.

=item B<iniFile>

A second or non-numeric first argument is taken as a filename.
Fairy-Max will use the mentioned file in stead of its default fmax.ini file
to define the movement of pieces and initial setup of the variants.
This makes it easier to define your own variants.

=item B<INTERACTIVE OPTIONS>

Fairy-Max also supports some options that can only be set interactively,
though XBoard's engine settings menu dialog.
These are listed below:

=item B<Resign Threshold>

=item B<Resign>

If the Resign option is on, Fairy-Max will resign when its score
in centiPawns drops below the negated value of Resign Threshold.

=item B<Claim draw after>

The value of this option determines how many full moves must elapse
after a capture or pawn push before Fairy-Max will claim a draw.

=item B<Multi-PV Margin>

Moves that ly closer in score to the best move than the value
of this option (interpreted as centi-Pawn) will be emitted as
alternative variations in Fairy-Max' thinking output.

=item B<Ini File>

This option sets the name of the file Fairy-Max uses to retrieve
the game definition from, each time you start a new game.

=item B<Variant fairy selects>

Combobox to select what variant Fairy-Max will actually play
when variant 'fairy' is selected.
Variants defined with names fairy/... in the ini file
will appear as choices.
The introduction of engine-defined variants in XBoard protocol
has made this option obsolete,
but Fairy-Max still uses it for selecting the different flavors
of chess with different armies.
This setting takes effect when a new game in variant fairy is started.

=item B<Makruk rules>

Obsolete option, which selects whether makruk will be played
with Cambodian rules (allowing extra initial moves of King and Met),
or with the Ai-Wok super piece replacing the Met.
With recent XBoard version these games would be directly available
from XBoard's New Variant menu as engine-defined variant.

=item B<Clear Hash>

Pressing this button will clear Fairy-Max' hash table,
so that it does not have any memory of what it calculated earlier.

=item B<Info>

Pressing this button pops up a short description of the current
variant.

=item B<Save in hash file>

Pressing this button when Fairy-Max is in analysis mode
adds the current position to the persistent-hash
file for the current variant, with the latest score reported by the engine.
Positions in this file are loaded before any game in Fairy-Max' hash table,
protected from overwrite during the game, to define the score Fairy-Max
should give to the position at any search depth.

=item B<Automatic persistent-hash dialog>

Switching on this option will cause a dialog to pop up in any new position
you reach during analysis mode,
asking you whether the position should be saved in the persistent-hash file
for the current variant.
Pressing OK will save the position with the latest score from the analysis,
while typing a number will assign that number of centi-Pawn to the position
instead.

=head1 FILES

=item B<fmax.ini>

The fmax.ini file from which Fairy-Max by default takes the piece and
game definitions is a self-documenting text file,
which contains instructions for how to define new pieces and chess variants.
Next to the definitions of all variants Fairy-Max can play,
it contains an extensive list of pre-defined pieces,
incuding many not occurring in any of the pre-defined variants.
The user can draw on these to define his own variants.

=item B<Persistent hash>

Some of the interactive options can be used to store the current position
in a file bearing the name of the variant being played,
with the extension .hash added to it, during analysis.
Positions in that file will be loaded into Fairy-Max' hash table before
every game, protected from overwrite.
This can be used to create an opening or end-game book for the variant.
This can for instance be used to discourage opening lines the engine overrates.
The file will be created in the current directory,
but at the start of a game both this file
and a similar one in Fairy-Max' private data files will be loaded.
The install does contain such a persistent hash file for makruk,
to help Fairy-Max find the checkmate in the difficult corners of the
KMMMK and KNMMK (with like M) end-games.

=back

=head1 AVAILABILITY

At http://hgm.nubati.net/cgi-bin/gitweb.cgi the source code can be obtained.

=head1 SEE ALSO

xboard(6)

explanations: http://www.chessvariants.org/index/msdisplay.php?itemid=MSfairy-max

micro-Max: http://home.hccnet.nl/h.g.muller/max-src2.html

XBoard: http://hgm.nubati.net

=head1 STANDARDS

WinBoard, B<xboard>(6) interface ("Chess Engine Communication Protocol")

=head1 AUTHOR

H.G.Muller <h.g.muller@hccnet.nl>.

This manual page was generated with pod2man(1).
