Mention piece-to-char table in format description
[fairymax.git] / CVfairy.html
1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
2 <html>
3 <head><title>Fairy-Max</title>
4 <META name="Author" content="H.G.Muller">
5 <META name="keywords" content="chess, variation, variant, variants">
6 <LINK href="../g/global.css" rel="stylesheet" type="text/css">
7 </head>
8 <body bgcolor="#fffff0" vlink="#ff0000"> 
9
10 <table><tr><td width="200"></td><td>
11 <h3>Downloads</h3>
12 <p><a href="http://hgm.nubati.net/Fairy-Max.zip">Fairy-Max Windows executable and source</a> (includes ShaMax.exe and MaxQi.exe, and logo)</p>
13 <p><a href="http://hgm.nubati.net/pairomax.zip">Pair-o-Max Windows executable</a> (plus ini file and logo)</p>
14 <p><a href="http://hgm.nubati.net/Alice.zip">Looking-Glass executable for Alice Chess</a> (includes ShaMax.exe and MaxQi.exe, and logo)</p>
15 <p><a href="http://hgm.nubati.net/fairymax.tar.gz">fairymax sources as tar ball</a> for installing from source on *nix systems (includes maxqi.c)</p>
16 </td></tr></table>
17
18 <h1>Fairy-Max: an AI for playing user-defined Chess variants</h1>
19
20 <p><table width="20%" cellpadding=8 align=right>
21 <tr><td bgcolor="#eeeee0"><div class="menu">
22 <a href="#intro">Introduction</a>
23 <br><a href="#array">Setup</a>
24 <br><a href="#pieces">Pieces</a>
25
26 <br><a href="#rules">Rules</a>
27 <br><a href="#playingtips">Playing Tips</a>
28 <br><a href="#equipment">Equipment</a>
29 <br><a href="#notes">Notes</a>
30 <br><a href="#contact">Contact</a>
31 <p>Links to related pages would appear here.
32 </div>
33 </td></tr>
34 </table>
35
36 <a name=intro> </a>
37
38 <h2>Introduction</h2>
39
40 <table><tr><td width="200">
41 <img src="./fairysmall.jpg">
42 </td><td>
43 <p>
44 Fairy-Max is an AI, also called 'engine', for playing Chess variants.
45 It is free open-source software.
46 It was created for the purpose of empirically evaluating fairy pieces,
47 by allowing those to participate amongst orthodox Chess pieces
48 in Chess games aimed at checkmating an opponent royal piece.
49 It searches ahead like the FIDE-Chess engine from which it was derived
50 (the World's once smallest Chess program, <a href="max-src2.html">micro-Max</a>)
51 by generating moves and trying them out on the internal board.
52 To know how each piece type moves, micro-Max uses tables with step vectors,
53 and it knows which pieces are leapers and which are sliders.
54 In Fairy-Max, the contents of these tables is not fixed,
55 but is loaded from a configuration file 'fmax.ini' at the start of each game.
56 This allows the user to change the way pieces move
57 (or add pieces of his own design) without changing the program,
58 by altering the contents of the fmax.ini file.
59 Fmax.ini is a normal text file and thus can be modified with any text editor
60 (e.g. Notepad).
61 </p>
62 </td></tr></table>
63 <p>
64 Fairy-Max is 'only an AI'. 
65 This means it does not provide any graphics to display the position of the game it is playing,
66 but only relays the moves as text.
67 It is primarily designed to be run as an engine inside the <a href="http://hgm.nubati.net">WinBoard</a> GUI,
68 (or its Linux counterpart XBoard),
69 and it communicates with this GUI in 'WinBoard protocol'.
70 Although there are several other GUIs that support WinBoard protocol,
71 they will in general not offer as much variant support as WinBoard / XBoard.
72 Most GUIs only support normal Chess,
73 but ChessGUI by Matthias Gemuh also supports 10x8 Capablanca variants.
74 Note that there are also many other WinBoard-compatible engines for
75 playing variants that can be played under WinBoard 4.3 or higher.
76 Some even play variants that Fairy-Max could never implement
77 (e.g. Xiangqi or Crazyhouse).
78
79 </p><p>
80 There are however some dedicated versions of Fairy-Max that are adapted to variants
81 with very unique needs,
82 such as the Shatranj baring rule, or the confinement of pieces to certain board areas in Xiangqi.
83 These versions, known as ShaMax and MaxQi, respectively, are in general only useful for playing
84 a single Chess variant, and are included in the downloads listed at the top of this page.
85 There also is a derivative 'Looking Glass', which plays Alice Chess.
86 There also exists a special research derivative <a href="mating.html">'Pair-o-Max'</a>,
87 which does take into account mating potential in the late end-game.
88 </p>
89 <a name=array> </a>
90
91 <table><tr><td>
92 <h2>Setup</h2>
93
94 <p>
95 Fairy-Max can be downloaded in both Windows and Linux versions
96 through the links at the top of this page.
97 It is also included in the standard distribution of WinBoard, however,
98 where it is pre-installed as primary engine, and can be started from the Windows Start menu.
99 The Windows Fairy-Max package contains the engine executable, 
100 the fmax.ini (which contains its own format description),
101 and the engine source code, all grouped inside a folder.
102 To install it, just extract this folder to a suitable place on your hard disk.
103 Recommended is to put this folder next to the one where you installed WinBoard.
104 WinBoard has a Load Engine dialog in its Engine menu,
105 which you could use to install Fairy-Max (or any other engine) by simply pointing out the exe file in a file-browse dialog.
106 It needs no special parameters or options.
107 </p>
108 <p>
109 Fairy-Max'  hash table size can be set through WinBoard's Common Engine Options dialog,
110 and is responsible for almost its memory usage.
111 (It is rounded down to 12 times a power of two, e.g. 48MB, 96MB, 192MB)
112 If this does not comfortably fit in memory together with the
113 engine process of the opponent (if there is a computer opponent),
114 Fairy-Max will not run properly, and you would have to reduce the hash size.
115 </p><p>
116 For a detailed explanation of the variants that Fairy-Max can play,
117 see the website of <a href="http://www.chessvariants.org">chessvariants.org</a>
118 </p><p>
119 The piece descriptions in the fmax.ini file are grouped into variants,
120 so that setting the engine to a certain variant (from the User Interface),
121 will load the group of piece descriptions for that variant.
122 The Fairy-Max download comes with an fmax.ini that predefines
123 several variants 
124 (FIDE Chess, Capablanca Chess, Shatranj, Courier, Knightmate, Cylinder Chess),
125 which can serve as an example for those that want to implement their own variants.
126 In addition, the fmax.ini file contains definitions of the most common fairy pieces not participating in the predefined variants,
127 so that the user can draw on them when composing his own variants.
128 Although Fairy-Max supports merely 15 different piece types,
129 this is only a limitation to the number of different piece types that
130 can participate simultaneously in a single game.
131 In a game of another variant, all 15 pieces could move completely differently.
132 </p>
133 </td><td width="550">
134
135 <h3>Table 1: Variants pre-defined in the supplied fmax.ini</h3>
136 <table cellpadding="5" border="1" bgcolor="lightyellow"><tr><td>
137 normal
138 </td><td>
139 FIDE's good old mad-queen game
140 </td></tr><tr><td>
141 shatranj
142 </td><td>
143 Arabic precursor of Chess with Elephants in stead of Bishops (best played with ShaMax)
144 </td></tr><tr><td>
145 capablanca
146 </td><td>
147
148 10x8 variant with Archbishop and Chancellor
149 </td></tr><tr><td>
150 gothic
151 </td><td>
152 Patented variant similar to Capablanca, with a more exciting opening setup
153 </td></tr><tr><td>
154 courier
155 </td><td>
156 12x8 Medieval variant, combining Shatranj pieces with the modern Bishop
157 </td></tr><tr><td>
158 knightmate
159 </td><td>
160 King moves like Knight, and vice versa
161 </td></tr><tr><td>
162 cylinder
163 </td><td>
164 The board has no left or right edges, pieces wrap around
165
166 </td></tr><tr><td>
167 berolina
168 </td><td>
169 8x8 variant where Pawns capture straight ahead, and move diagonally
170 </td></tr><tr><td>
171 super
172 </td><td>
173 Superchess, an 8x8 shuffle variant with 4 super-pieces, including Amazon
174 </td></tr><tr><td>
175 great
176 </td><td>
177 Great Shatranj, a 10x8 variant where all sliders are replaced by corresponding short-range pieces
178 </td></tr><tr><td>
179 seirawan
180 </td><td>
181 S-Chess, where a R+N and B+N compund start in hand and can be gated onto the 8x8 board
182 </td></tr><tr><td>
183 spartan
184 </td><td>
185 Spartan Chess, where a completely unorthodox army with two kings (the Spartans) battle the regular (Persian) FIDE army
186 </td></tr><tr><td>
187 makruk
188 </td><td>
189 Thai Chess, a Shatranj-like variant where Elephants are replaced by Gold Generals, and Pawns start on 3rd rank
190 </td></tr><tr><td>
191 falcon
192 </td><td>
193 On 10x8 with two 'falcon' pieces (multi-path lame (1,3)+(2,3) leapers)
194 </td></tr><tr><td>
195 -
196 </td><td>
197 Chess with Different Amies: the FIDE army, the Colorbound Cobberers, the Nutty Knights or Remarkable Rookies battle each other
198 </td></tr><tr><td>
199 xiangqi
200 </td><td>
201 Chinese Chess (9x10 board) with Elephants, Cannons, and a King confined to a 3x3 Palace
202 (only with MaxQi)
203 </td></tr><tr><td>
204
205 fairy
206 </td><td>
207 A catch-all variant, in which by default any piece can participate.
208 Fairy-Max redefines the meaning of this variant as specified by a combobox option.
209 </td></tr></table>
210 </td></tr></table>
211
212 <p>
213 The board size for each variant is also defined in the fmax.ini file,
214 and is currently limited to 12x8.
215 (Expansion of the number of ranks is on the to-do list.)
216 The default opening position is also defined in there,
217 but can be overruled by loading a position through the User Interface.
218 </p>
219
220 <a name=pieces> </a>
221 <h2>Pieces</h2>
222
223 <table><tr><td width="420">
224 <h3>Table 2: attributes that can be combined to define a move type</h3>
225 <table border="1" bgcolor="lightgreen"><tr><td>
226 C
227 </td><td>
228 capture
229 </td><td>
230 target square is valid if occupied by enemy piece
231 </td></tr><tr><td>
232 N
233 </td><td>
234 non-capture
235 </td><td>
236 target square is valid if empty
237 </td></tr><tr><td>
238 T
239 </td><td>
240 terminate
241 </td><td>
242 move cannot continue, even if target square is empty
243 </td></tr><tr><td>
244 H
245 </td><td>
246 hopper
247 </td><td>
248 move can continue if target square was occupied
249 </td></tr><tr><td>
250 W
251 </td><td>
252 wrap
253 </td><td>
254 treat board like left edge borders right (cylinder board)
255 </td></tr><tr><td>
256 M
257 </td><td>
258 multi-path
259 </td><td>
260 special move mode for Falcon in Falcon Chess
261 </td></tr></table>
262
263 </td><td>
264
265 <p>
266 Apart from Pawns, orthodox Chess pieces only come in two different types: 
267 leapers and sliders.
268 Leapers can only do one step of a given type, 
269 while sliders can repeat their elementary step indefinitely, 
270 as long as they do not encounter an obstruction (piece or board edge).
271 If the obstruction is an enemy piece, it can be captured,
272 (both by leapers and sliders),
273 but the move cannot continue after that even for a slider.
274 </p>
275 <p>
276 As not all fairy pieces fall in the slider or leaper category,
277 Fairy-Max implements two additional move types: hoppers and alternators.
278 Hoppers are sliders that can jump over the first obstruction in their path,
279 and continue from there, with possibly a different type of move.
280 The best known examples are the Cannon (Pao) from Chinese Chess,
281 and the Grasshopper.
282 The Pao changes its move type from 'non-capture only' to 'capture only' on hopping.
283 The Grasshopper changes it from 'none' to 'both' (capture and non-capture),
284 and in addition changes from slider to leaper.
285 (It is only allowed to do one step after the hop,
286 in contrast to the Pao, which remains a slider after hopping.)
287 </p>
288 </td></tr></table>
289 <p>
290 Alternators are pieces that do not need to hop over anything to change
291 their move type, but do so spontaneously after every step they make.
292 This can be a change in step direction, to provide bend trajectories, 
293 but also in capture rights.
294 E.g. a Xiangqi Elephant makes 2 diagonal steps in the same direction,
295 on the first step it is not allowed to do anything (capture or non-capture) but continue, (if the square is empty, of course),
296 on the second step it can both capture and non-capture (but is not allowed to continue any further, even if the square was empty).
297 The Xiangqi Horse is similar, but also changes direction between the first and second step.
298 </p><p>
299 The Crooked Bishop is an example of a slider that changes direction on every step.
300 This means both its primary and secondary step allow slider-like continuation.
301 After the second step it switches back to its first, 
302 and continues alternating on every subsequent step.
303 For simplicity, Fairy-Max treats every slider that is not a hopper as an alternator.
304 In cases where this is not desired (e.g. for the Rook),
305 it simply 'alternates' between two identical steps.
306 </p><p>
307 To provide flexibility in implementation of fairy pieces,
308 the discription of the move type has to be given for each direction separately,
309 rather than for the piece as a whole.
310 This to allow mixed sliders/leapers, such as the Archbishop, 
311 which combines the Knight (leaper) and Bishop (slider) moves.
312 For implementation of hoppers and alternators,
313 the move description (direction and type) has to be given twice
314 (primary and secondary move descriptor).
315 The method used for that in the fmax.ini file is to specify
316 which bits should change to make the secondary step and move rights out of the primary.
317 This info can be used to change them in both directions (primary -> secondary and secondary -> primary),
318 which is convenient for alternators.
319 It also means that for 'normal' pieces, where nothing changes as primary and secondary step are the same,
320 the secondary rights and step are all zero, and don't have to be written.
321 Since version 4.8S a 2-bit 'delay count' can be specified with each piece
322 to delay the first toggle between primary and secondary step type by 1, 2 or 3 steps,
323 which allows implementation of limited-range sliders of ranges upto 5.
324 </p><p>
325
326 Fairy-Max makes no assumptions to the symmetry of the piece,
327 meaning that all directions in which the piece moves have to be specified explicitly.
328 E.g. for a Rook we have to list 4 moves, for a Knight 8.
329 However annoying this sometimes might be,
330 this is necessary for allowing implementation of
331 asymmetric pieces such as the Crab or the Shogi Generals.
332 Unfortunately, Fairy-Max is not smart enough yet to realize that the different
333 sides play in opposite direction.
334 Thus asymmetric pieces (such as Pawns) have to be implemented as different
335 piece types for white and black.
336 (E.g. what is a Crab for white, will be a Barc for black, and vice versa.)
337 The following pieces have predefined descriptions in fmax.ini,
338 ready for copying to your own variants.
339 </p>
340 <h3>Table 3: Pieces that are pre-defined in the fmax.ini that comes with the download</h3>
341 <table border="1" cellpadding="5">
342
343 <tr bgcolor="yellow"><td>
344 SIMPLE LEAPERS
345 </td><td>
346 COMPOUND LEAPERS
347 </td><td bgcolor="lightgreen">
348 LEAPER-SLIDER COMPOUND
349 </td><td bgcolor="lightblue">
350 SLIDERS
351 </td><td>
352 LAME LEAPERS
353 </td><td bgcolor="magenta">
354
355 CYLINDER PIECES
356 </td></tr>
357
358 <tr><td>
359 Ferz
360 </td><td>
361 King / Commoner
362 </td><td>
363 Archbishop
364 </td><td>
365 Bishop
366 </td><td>
367 Elephant (Xiangqi)
368 </td><td>
369 Cylinder Bishop
370 </td></tr>
371
372 <tr><td>
373 Wazir
374 </td><td>
375 Bison
376 </td><td>
377 Chancellor
378 </td><td>
379 Rook
380 </td><td>
381 Horse (Xiangqi)
382 </td><td>
383 Cylinder Rook
384 </td></tr>
385
386 <tr><td>
387 Knight
388 </td><td>
389
390 Wildebeest
391 </td><td>
392 Caliph
393 </td><td>
394 Nightrider
395 </td><td>
396 Falcon
397 </td><td>
398 Cylinder Knight
399 </td></tr>
400
401 <tr><td>
402 Dabbaba
403 </td><td>
404 Carpenter
405 </td><td>
406 Canvasser
407
408 </td><td>
409 Queen
410 </td><td bgcolor="red">
411 SEPARATE CAPTURE
412 </td><td>
413 Cylinder Queen
414 </td></tr>
415
416 <tr><td>
417 Elephant (Alfil)
418 </td><td>
419 Kangaroo
420 </td><td>
421 Amazon
422 </td><td>
423 Crooked Bishop
424 </td><td>
425
426 FIDE Pawn
427 </td><td>
428 Cylinder Pawn
429 </td></tr>
430
431  
432 <tr><td>
433 Camel
434 </td><td>
435 High Priestess
436 </td><td bgcolor="purple">
437 HOPPERS
438 </td><td bgcolor="lightblue">
439 LIMITED RANGE
440 </td><td>
441 Shatranj Pawn
442 </td><td>
443
444 </td></tr>
445
446 <tr><td>
447 Zebra
448 </td><td>
449 Minister
450 </td><td>
451 Grasshopper
452 </td><td>
453 Rook-3
454 </td><td>
455 Quing
456 </td><td>
457
458 </td></tr>
459
460 <tr><td>
461
462 </td><td>
463 Crab / Barc
464 </td><td>
465 Cannon (Xiangqi)
466 </td><td>
467 Bishop-4
468 </td><td>
469 Keen
470 </td></tr></table>
471
472 <a name=rules> </a>
473 <h2>Rules</h2>
474
475 <p>
476 This section gives an indication of how the Chess variants are defined
477 in the fmax.ini file.
478 After a line "Game: <NAME>" to indicate that a new variant description follows,
479 we have lines that specify the board size,
480 and the back rank of the array for white and black.
481 (Fairy-Max always assumed a close rank of Pawns directly in front of that.)
482 A name can be prefixed with "fairy/", meaning that it is not supported by WinBoard,
483 and has to be played as the catch-all vatiant "fairy".
484 An engine option (appearing in the GUI's Engine Settings dialog)
485 will in this case determine what variant is really played (identified by the part of the name after the slash).
486 </p><p>
487 The variant name can be followed by a # and extra information.
488 In such a case Fairy-Max will send a 'setup' command to the GUI to inform it of the default opening
489 position for the variant, possibly accompanied by the info behind the #,
490 which designates the one-letter piece ID with which the GUI should represent the various pieces.
491 After the three initial lines follow the descriptions of all participating pieces,
492 one line per piece.
493 </p><p>
494 For each piece, we have to give the letter by which it is represented
495 when feeding a position to the engine,
496 and the value the engine should attach to it in play.
497 (So beware, Fairy-Max is not smart enough to figure this out by itself.
498 If you tell it an immensely powerful piece like a Queen is only worth half a Pawn,
499 it will happily trade it for one!)
500 Then follows on the same line a list of move descriptors, 
501 one for each direction the piece moves in.
502 A move description consists of an elementary board step,
503 and a number that specifies the move attributes,
504 i.e. what the piece is allowed to do in this direction
505 (if it can capture and/or non-capture, if it is leaper or slider,
506 if it can hop over an obstacle or not, 
507 if it respects the board edges or wraps around.)
508 The exact way the step vectors and attributes are encoded
509 is specified in comment lines contained in the fmax.ini,
510 as it might still be subject to change in future versions.
511 </p><p>
512 The first two pieces specified are by definition the white and black Pawns.
513 That means that Fairy-Max will let them promote if they reach the last rank.
514 Fairy-Max does not think about under-promotion, 
515 but always promotes to 'Queen', i.e. the 7th piece specified, however that may move.
516 Except when piece number 7 only appears in the initial setup for white, 
517 and a piece with number 9 occurs in the initial setup for black,
518 in which case black would always promote to piece 9
519 (to allow variants with different armies).
520 </p><p>
521 Any piece with a negative value is considered royal.
522 Fairy-Max makes a difference between value -1 and other negative values, though:
523 -1 indicates absolute royalty, i.e. loss of any piece of this type means loss of the game.
524 Other values indicate only loss of the last royal piece result in loss of the game,
525 and any spare ones should be treated as if they are worth the absolute value of the given number.
526 This allows for variants with 'delocalized royalty', such as Spartan Chess.
527 </p>
528
529 <a name=notes> </a>
530 <h2>Notes</h2>
531 <p>
532 There are many things that Fairy-Max cannot do; it was never meant to be a general game-playing system like Zillions of Games.
533 Amongst the impossibilities are piece drops, (as in Crazyhouse or Shogi), 
534 pieces for which the moves are dependent on their location on the board
535 (as in Xiangqi, but MaxQi handles this particular case).
536 and pieces whose moving exerts side effects on other squares that their old and new location
537 (with the exception of castling and e.p capture).
538 For some pieces the move is simply too complicated to fit within the Fairy-Max move-type classification system (e.g. Rose, Griffon).
539 </p><p>
540 Only boards with 8 ranks are currently implemented.
541
542 <p>
543 The current version of Fairy-Max implements e.p. capture in such a way that it also correctly handles Berolina Pawns,
544 and allows castling with any corner piece.
545 </p>
546
547 <a name=playingtips> </a>
548 <h2>Playing Tips</h2>
549 <p>
550 Positional evaluation in Fairy-Max is fairly primitive:
551 a piece either is drawn towards the center, or not.
552 If you want a piece to be drawn to the center,
553 you should indicate it by a lower-case letter.
554 Pawns do get a large positional bonus when they reach 6th or 7th rank,
555 of 64 and 128 units ('centiPawn' in FIDE Chess), respectively.
556 This assumes that the piece to which the Pawns will promote is of decisive value,
557 so the opponent will have to sacrifice a piece to stop the promotion.
558 Unfortunately, this does not work very well in Shatranj and Courier Chess,
559 where Pawns promote to the worthless Ferz.
560 Recent versions of Faiy-Max divide this bonus by 8 in cases where a "Queen"
561 (the piece to which Pawns promote by default)
562 is worth less than 250 centi-Pawn, to repair this problem.
563 Nevertheless, the strategy of Fairy-Max is tailored too much to normal Chess, with normal Pawns
564 to be a really good Shatranj or Courier player.
565 </p>
566
567 <a name=equipment> </a>
568 <h2>Equipment</h2>
569 <p>
570
571 Fairy-Max runs on a PC under any Windows operating system.
572 The memory demand is determined by the size of its hash table,
573 which by default is 96M.
574 It would still run with a smaller hash table,
575 but the larger the hash table, the better its play.
576 Running with a hash table smaller than 6MB is not recommended.
577 Recently also versions that can run on other platforms, such as Linux, were released.
578 </p>
579
580 <a name=contact> </a>
581 <h2>Contact</h2>
582 Questions about Fairy-Max can be posted as comments to the Fairy-Max page
583 on the <a href="http://www.chessvariants.org">chessvariants website</a>,
584 which are checked regularly by H.G. Muller,
585 and of which this page is an adapted version.
586
587 <!--#if expr="1=0" -->
588 <p>
589 <hr>Written by H.G. Muller.
590 <hr>WWW page created: July 8, 2008. Last updated: February 28, 2013.
591 <!--#else -->
592 <!--#include virtual="/g/footerinc1.html" --> 
593 <!--#endif -->
594
595 </body>
596 </html>