updated polyglot protocol
[xboard.git] / winboard / install / files / root / WinBoard / doc / manual.html
1 <!DOCTYPE HTML>\r
2 <html>\r
3 \r
4 <head>\r
5 <title>WinBoard 4.4.0</title>\r
6 </head>\r
7 \r
8 <body>\r
9 <table><tr><td halign="top">\r
10 <h1>WinBoard 4.4.0</h1>\r
11 <h2>"For the ultimate WinBoard experience"</h2>\r
12 <h3>Introduction</h3>\r
13 <p>\r
14 The WinBoard 4.3 series was a continuation of the WinBoard_x line by Allessandro Scotti.\r
15 It has been further developed, and is maintained, by H.G. Muller.\r
16 Most addtions and improvements that went into this since the last version produced\r
17 by the GNU-Savannah xboard project team, WinBoard 4.2.7b,\r
18 were unfortunately not parallelled in XBoard.\r
19 On the contrary, they had destroyed the compatibility of the back-end sources\r
20 shared by WinBoard and XBoard with the XBoard front-end of version 4.2.7b.\r
21 Since WinBoard 4.3.14, however, the releases again comes with a compatible XBoard front-end.\r
22 That does not mean that all the features added to WinBoard can already be used\r
23 in the latest XBoard version.\r
24 But some can, an in 4.3.15 many more have been added.\r
25 </p><p>\r
26 WinBoard 4.4 is a merger of the WinBoard 4.3 line (WinBoard 4.3.pre16) \r
27 and what was left in the GNU-Svannah XBoard repository (WinBoard 4.2.pre8).\r
28 More WinBoard functionality has been ported to XBoard,\r
29 but there still is a sizable gap to bridge.\r
30 </p><p>\r
31 The description below applies specifically to WinBoard, \r
32 although we have tried to mark features that can also be used in xboard by (x) everywhere.\r
33 This version of XBoard now does have some new menus added to control such features.\r
34 Other functions, if they work at all, must be switched on from the command line.\r
35 </p>\r
36 </td><td width="20">\r
37 </td><td width="200" halign="center" cellpdding="20">\r
38 <img src="mini.gif">\r
39 </td></tr></table>\r
40 <h3>New features since 4.2.7b</h3>\r
41 <p>\r
42 Below follows a table that lists the new features, \r
43 the command-line option needed to control them,\r
44 and if there is a menu provided that can switch the option while WinBoard is running\r
45 (command-line options exert their effect only at startup).\r
46 Note that, unlike WinBoard 4.2.7, the WinBoard 4.3 series is fully castling and e.p. aware,\r
47 and handles the castling, e.p. and 50-move field in FENs on input and output as should be expected.\r
48 </p>\r
49 <table cellpadding="3" border="1"><tr><td width="220">\r
50       <h3>command-line option</h3>\r
51     </td><td>\r
52       <h3>description</h3>\r
53     </td><td width="250">\r
54       <h3>menu</h3>\r
55   </td></tr><tr><td>\r
56       \r
57     </td><td bgcolor="lightblue">\r
58       <strong>ENGINE-ENGINE ADJUDICATION OPTIONS<strong>\r
59     </td><td>\r
60       \r
61   </td></tr><tr><td>\r
62       -adjudicateLossThreshold 0 (*x)\r
63     </td><td>\r
64       adjudicates engine-engine game based on score\r
65     </td><td>\r
66       Options -> Engine... (x)\r
67   </td></tr><tr><td>\r
68       -checkMates false (*x)\r
69     </td><td>\r
70       detect and end game on checkmates and stalemates\r
71     </td><td>\r
72       Options -> Engine... (x)\r
73   </td></tr><tr><td>\r
74       -testClaims false (*x)\r
75     </td><td>\r
76       WinBoard corrects false RESULT claims\r
77     </td><td>\r
78       Options -> Engine.. (x)\r
79   </td></tr><tr><td>\r
80       -materialDraws false (*x)\r
81     </td><td>\r
82       adjudicate draw when no mating material present\r
83     </td><td>\r
84       Options -> Engine.. (x)\r
85   </td></tr><tr><td>\r
86       -trivialDraws false (*x)\r
87     </td><td>\r
88       adjudicate draw in endgames like KRKR and KNNK\r
89     </td><td>\r
90       Options -> Engine.. (x)\r
91   </td></tr><tr><td>\r
92       -adjudicateDrawMoves 0 (*x)\r
93     </td><td>\r
94       adjudicate draw when game lasts too long\r
95     </td><td>\r
96       Options -> Engine.. (x)\r
97   </td></tr><tr><td>\r
98       -ruleMoves 51 (*x)\r
99     </td><td>\r
100       number of reversible moves after which to adjudicate draw\r
101     </td><td>\r
102       Options -> Engine.. (x)\r
103   </td></tr><tr><td>\r
104       -repeatsToDraw 6 (*x)\r
105     </td><td>\r
106       adjudicate draw when a position occurs this many times\r
107     </td><td>\r
108       Options -> Engine.. (x)\r
109   </td></tr><tr><td>\r
110       -firstScoreAbs false (x)\r
111       <br>\r
112       -secondScoreAbs false (x)\r
113     </td><td>\r
114       Engine indicates score for white, even when playing black\r
115     </td><td>\r
116       Options -> Adjudications.. (xboard-only)\r
117   </td></tr><tr><td>\r
118       -\r
119     </td><td>\r
120       Adjudicate the game in progress as win to white, win to black, or draw\r
121     </td><td>\r
122       Action -> Adjudicate to White\r
123       <br>\r
124       Action -> Adjudicate to Black\r
125       <br>\r
126       Action -> Adjudicate Draw\r
127   </td></tr><tr><td>\r
128       \r
129     </td><td bgcolor="lightblue">\r
130       <strong>TIME-CONTROL AND TIMING OPTIONS</strong>\r
131     </td><td>\r
132       \r
133   </td></tr><tr><td>\r
134       -firstTimeOdds 1 (x)\r
135       <br>\r
136       -secondTimeOdds 1 (x)\r
137     </td><td>\r
138       reduce the thinking time of the mentioned engine by the given factor\r
139     </td><td>\r
140       Options -> Engine Settings.. (xboard only)\r
141   </td></tr><tr><td>\r
142       -timeOddsMode 1 (*x)\r
143     </td><td>\r
144       determines what happens when both engine have time odds\r
145     </td><td>\r
146       Options -> Engine Settings.. (xboard only)\r
147   </td></tr><tr><td>\r
148       -firstNPS -1 (x)\r
149       <br>\r
150       -secondNPS -1 (x)\r
151     </td><td>\r
152       engine must use node count for its time control, as if running at specified rate\r
153     </td><td>\r
154       -\r
155   </td></tr><tr><td>\r
156       -matchPause 10000 (*x)\r
157     </td><td>\r
158       number of msec to wait between games in match mode\r
159     </td><td>\r
160       -\r
161   </td></tr><tr><td>\r
162       -delayBeforeQuit 0 (*x)\r
163       <br>\r
164       -delayAfterQuit 0 (*x)\r
165     </td><td>\r
166       timing parameter specifying how to terminate the engine processes\r
167     </td><td>\r
168       -\r
169   </td></tr><tr><td>\r
170       -\r
171     </td><td>\r
172       adjust the clocks by 1 minute (up or down)\r
173     </td><td>\r
174       left- or right-cick on clock in edit-game mode\r
175   </td></tr><tr><td>\r
176       -niceEngines 0 (*x)\r
177     </td><td>\r
178       lower the CPU priority of the engines\r
179     </td><td>\r
180       -\r
181   </td></tr><tr><td>\r
182       \r
183     </td><td bgcolor="lightblue">\r
184       <strong>DISPLAY-LOOK OPTIONS</strong>\r
185     </td><td>\r
186       \r
187   </td></tr><tr><td>\r
188       -liteBackTextureFile "" (*)\r
189       <br>\r
190       -darkBackTextureFile "" (*)\r
191       <br>\r
192       -liteBackTextureMode 1 (*)\r
193       <br>\r
194       -darkBackTextureMode 1 (*)\r
195     </td><td>\r
196       Allows you to use any bitmap picture for displaying the board square\r
197     </td><td>\r
198       -\r
199   </td></tr><tr><td>\r
200       -renderPiecesWithFont "" (*)\r
201     </td><td>\r
202       specifies a true-type Chess font to be used for piece symbols\r
203     </td><td>\r
204       -\r
205   </td></tr><tr><td>\r
206       -fontPieceToCharTable "" (*)\r
207     </td><td>\r
208       specifies which font character to use for the various piece types\r
209     </td><td>\r
210       -\r
211   </td></tr><tr><td>\r
212       -overrideLineGap 1 (*)\r
213     </td><td>\r
214       controls the width of the black grid lines between squares\r
215     </td><td>\r
216       -\r
217   </td></tr><tr><td>\r
218       -fontPieceBackColorWhite #0 (*)\r
219       <br>\r
220       -fontPieceForeColorWhite #0 (*)\r
221       <br>\r
222       -fontPieceBackColorBlack #0 (*)\r
223       <br>\r
224       -fontPieceForeColorBlack #0 (*)\r
225     </td><td>\r
226       control piece colors in font-based rendering\r
227     </td><td>\r
228       -\r
229   </td></tr><tr><td>\r
230       -fontPieceSize 80 (*)\r
231     </td><td>\r
232       tunes the size of pieces in font-based rendering (% of square size)\r
233     </td><td>\r
234       -\r
235   </td></tr><tr><td>\r
236       -highlightMoveWithArrow false (*)\r
237     </td><td>\r
238       draws a big arrow to indicate the move last played\r
239     </td><td>\r
240       Options -> General...\r
241   </td></tr><tr><td>\r
242       -highlightArrowColor #FFFF80 (*)\r
243     </td><td>\r
244       controls the color of the highlight arrow\r
245     </td><td>\r
246       -\r
247   </td></tr><tr><td>\r
248       -autoLogo false (*)\r
249       <br>\r
250       -firstLogo ""\r
251       <br>\r
252       -secondLogo ""\r
253     </td><td>\r
254       causes WinBoard to display player logos above the board, next to the clocks.\r
255     </td><td>\r
256       -\r
257   </td></tr><tr><td>\r
258       -\r
259     </td><td>\r
260       Swap white and black clock\r
261     </td><td>\r
262       Options -> Swap Clocks\r
263   </td></tr><tr><td>\r
264       \r
265     </td><td bgcolor="lightblue">\r
266       <strong>(UCI) ENGINE OPTIONS</strong>\r
267     </td><td>\r
268       \r
269   </td></tr><tr><td>\r
270       -polyglotDir "" (*x)\r
271     </td><td>\r
272       tells WinBoard where you installed Polyglot, for automatic invocation with UCI engines\r
273     </td><td>\r
274       Options -> Global Settings... (x)\r
275   </td></tr><tr><td>\r
276       -polyglotBook "" (*x)\r
277     </td><td>\r
278       tells WinBoard which opening book it should use, or should make Polyglot use.\r
279     </td><td>\r
280       Options -> Global Settings... (x)\r
281   </td></tr><tr><td>\r
282       -usePolyglotBook false (*x)\r
283     </td><td>\r
284       turns the use of the Polygot book on or off\r
285     </td><td>\r
286       Options -> Global Settings... (x)\r
287   </td></tr><tr><td>\r
288       -defaultPathEGTB "c:\egtb" (*x)\r
289     </td><td>\r
290       folder where to find end-game tables\r
291     </td><td>\r
292       Options -> Global Settings... (x)\r
293   </td></tr><tr><td>\r
294       -defaultCacheSizeEGTB 4 (*x)\r
295     </td><td>\r
296       specifies the cache size for UCI engines\r
297     </td><td>\r
298       Options -> Global Settings... (x)\r
299   </td></tr><tr><td>\r
300       -defaultHashSize 64 (*x)\r
301     </td><td>\r
302       specifies the size of the main hash table for UCI engines and WinBoard engines implementing the memory command\r
303     </td><td>\r
304       Options -> Global Settings... (x)\r
305   </td></tr><tr><td>\r
306       -firstIsUCI false (x)\r
307       <br>\r
308       -secondIsUCI false (x)\r
309       <br>\r
310       -fUCI (x)\r
311       <br>\r
312       -sUCI (x)\r
313     </td><td>\r
314       tells WinBoard the corresponding engine should be run through Polyglot\r
315     </td><td>\r
316       -\r
317   </td></tr><tr><td>\r
318       -firstHasOwnBookUCI true (x)\r
319       <br>\r
320       -secondHasOwnBookUCI true (x)\r
321       <br>\r
322       -fNoOwnBookUCI true (x)\r
323       <br>\r
324       -sNoOwnBookUCI true (x)\r
325       <br>\r
326       -firstXBook (x)\r
327       <br>\r
328       -secondXBook (x)\r
329     </td><td>\r
330       tells WinBoard (or Polyglot) if the engine should use its own opening book\r
331     </td><td>\r
332       Options -> Global Settings... (x)\r
333   </td></tr><tr><td>\r
334       -smpCores 1 (*x)\r
335     </td><td>\r
336       sets the maximum number of CPUs an SMP engine can use.\r
337       (only affects engines that support the <strong>cores</strong> command of WB protocol)\r
338     </td><td>\r
339       Options -> Global Settings... (x)\r
340   </td></tr><tr><td>\r
341       -egtFormats "" (*x)\r
342     </td><td>\r
343       specifies which end-game tables are installed on the computer,\r
344       and where they can be found\r
345       (e.g. "nalimov:\chess\egtb,scorpio:\chess\bitbases")\r
346     </td><td>\r
347       -\r
348   </td></tr><tr><td>\r
349       -firstOptions "" (x)\r
350       <br>\r
351       -secondOptions "" (x)\r
352     </td><td>\r
353       sets engine-defined options of UCI engines and WinBoard engines that support the option feature.\r
354     </td><td>\r
355       Options -> Engine #1 Settings... (x)\r
356       <br>\r
357       Options -> Engine #2 Settings... (x)\r
358   </td></tr><tr><td>\r
359       -firstNeedsNoncompliantFEN "" (x)\r
360       <br>\r
361       -secondNeedsNoncompliantFEN "" (x)\r
362     </td><td>\r
363       directly specifies castling and e.p. field to be used in all FENs sent to mentioned engine\r
364     </td><td>\r
365       -\r
366   </td></tr><tr><td>\r
367       \r
368     </td><td bgcolor="lightblue">\r
369       <strong>CHESS-VARIANT OPTIONS</strong>\r
370     </td><td>\r
371       \r
372   </td></tr><tr><td>\r
373       -boardHeight -1 (*x)\r
374       <br>\r
375       -boardWidth -1 (*x)\r
376       <br>\r
377       -holdingsSize -1 (*x)\r
378     </td><td>\r
379       specifies the board format and nr of piece types that can be dropped,\r
380       when you want it to be different from what is usual in the chosen varint\r
381     </td><td>\r
382       File -> New Variant...\r
383   </td></tr><tr><td>\r
384       -variant normal (x)\r
385     </td><td>\r
386       supports many new variants: xiangqi, shogi, fischerandom, capabanca, gothic, caparandom, janus,\r
387       shatranj, courier, knightmate, berolina, falcon, cylinder, fairy, super, great\r
388     </td><td>\r
389       File -> New Variant... (x)\r
390   </td></tr><tr><td>\r
391       -defaultFrcOpening -1 (x)\r
392     </td><td>\r
393       allows you to play from a specific opening shuffle, or make a new shuffle each game\r
394     </td><td>\r
395       File -> New Shuffle Game... (x)\r
396   </td></tr><tr><td>\r
397       -pieceToCharTable "" (x)\r
398     </td><td>\r
399       allows you to specify by which letters pieces are referred to in FEN and SAN,\r
400       if you want to deviate from what is usual for the current variant\r
401     </td><td>\r
402       -\r
403   </td></tr><tr><td>\r
404       -flipBlack fase (*x)\r
405     </td><td>\r
406       displays opponent pieces uppside down (for Shogi)\r
407     </td><td>\r
408       Options -> Board...\r
409   </td></tr><tr><td>\r
410       -allWhite false (*x)\r
411     </td><td>\r
412       use white bitmaps (with black outline) also for display of black pieces (for Shogi)\r
413     </td><td>\r
414       Options -> Board...\r
415   </td></tr><tr><td>\r
416       \r
417     </td><td bgcolor="lightblue">\r
418       <strong>PGN FILE OPTIONS</strong>\r
419     </td><td>\r
420       \r
421   </td></tr><tr><td>\r
422       -pgnExtendedInfo false (*x)\r
423     </td><td>\r
424       save engine output (depth, score time) in PGN\r
425     </td><td>\r
426       Options->General...\r
427   </td></tr><tr><td>\r
428       -pgnEventHeader </br>"Computer Chess Game" (*x)\r
429     </td><td>\r
430       specify the event for the PGN event tag\r
431     </td><td>\r
432       -\r
433   </td></tr><tr><td>\r
434       -saveOutOfBookInfo true (*)\r
435     </td><td>\r
436       include an 'annotator' tag in the PGN file\r
437     </td><td>\r
438       \r
439   </td></tr><tr><td>\r
440       -hideThinkingFromHuman false (*x)\r
441     </td><td>\r
442       suppresses the engine thinking output in the display, without the need to switch it off\r
443       (so it can still appear in the PGN file)\r
444     </td><td>\r
445       Options -> General... (x)\r
446   </td></tr><tr><td>\r
447       -userName "" (x)\r
448     </td><td>\r
449       sets the name of the human player\r
450     </td><td>\r
451       Mode -> Enter Username... (x)\r
452   </td></tr><tr><td>\r
453       \r
454     </td><td bgcolor="lightblue">\r
455       <strong>USER-INTERFACE OPTIONS AND WINDOW CONTROL</strong>\r
456     </td><td>\r
457       \r
458   </td></tr><tr><td>\r
459       -moveHistoryUp true (*)\r
460       <br>\r
461       -moveHistoryX 0 (*)\r
462       <br>\r
463       -moveHistoryY 0 (*)\r
464       <br>\r
465       -moveHistoryW 0 (*)\r
466       <br>\r
467       -moveHistoryH 0 (*)\r
468     </td><td>\r
469       controls opening, placement and size of a window containing the moves of the current game\r
470       (new in 4.4 is that all X and Y coordinates of auxiliary windows are stored relative to the main window)\r
471     </td><td>\r
472       Mode -> Show Move History (x)\r
473   </td></tr><tr><td>\r
474       -evalGraphUp true (*)\r
475       <br>\r
476       -evalGraphX 0 (*)\r
477       <br>\r
478       -evalGraphY 0 (*)\r
479       <br>\r
480       -evalGraphW 0 (*)\r
481       <br>\r
482       -evalGraphH 0 (*)\r
483     </td><td>\r
484       controls opening, placement and size of a window containing a graph of the\r
485       evaluation score of the engine(s) as a function of move number of the current game\r
486     </td><td>\r
487       Mode -> Show Evaluation Graph\r
488   </td></tr><tr><td>\r
489       -engineOutputUp true (*)\r
490       <br>\r
491       -engineOutputX 0 (*)\r
492       <br>\r
493       -engineOutputY 0 (*)\r
494       <br>\r
495       -engineOutputW 0 (*)\r
496       <br>\r
497       -engineOutputH 0 (*)\r
498     </td><td>\r
499       controls opening, placement and size of a window containing the thinking output of the engine(s)\r
500     </td><td>\r
501       Mode -> Show Engine Output (x)\r
502   </td></tr><tr><td>\r
503       -stickyWindows true (*)\r
504     </td><td>\r
505       make the various windows snap onto each other, and stick together\r
506     </td><td>\r
507       -\r
508   </td></tr><tr><td>\r
509       -showEvalInMoveHistory true (*)\r
510     </td><td>\r
511       depth/score info of the engine is included as comments in the move history window\r
512     </td><td>\r
513       Options -> General...\r
514   </td></tr><tr><td>\r
515       -evalHistColorWhite #FFFFB0 (*)\r
516       <br>\r
517       -evalHistColorBlack #AD5D3D (*)\r
518     </td><td>\r
519       determines the color of the eval-score comments in the move-history window\r
520     </td><td>\r
521       -\r
522   </td></tr><tr><td>\r
523       -autoDisplayComment true (*)\r
524     </td><td>\r
525       causes a window for displaying PGN comments to pop up automatically when such a comment is encountered\r
526     </td><td>\r
527       -\r
528   </td></tr><tr><td>\r
529       -autoDisplayTags true (*)\r
530     </td><td>\r
531       causes a window with PGN tags to be displayed as soon as a PGN file is loaded\r
532     </td><td>\r
533       -\r
534   </td></tr><tr><td>\r
535       -gameListTags "eprd" (*)\r
536     </td><td>\r
537       specifies the PGN tags that should be displayed in the game list\r
538     </td><td>\r
539       Options -> Game List...\r
540   </td></tr><tr><td>\r
541       -noGUI (x)\r
542     </td><td>\r
543       suppress update of display on all machine and ICS moves (moves, clocks, icon)\r
544     </td><td>\r
545       -\r
546   </td></tr><tr><td>\r
547       \r
548     </td><td bgcolor="lightblue">\r
549       <strong>ICS OPTIONS</strong>\r
550     </td><td>\r
551       \r
552   </td></tr><tr><td>\r
553       -autoKibitz (x)\r
554     </td><td>\r
555       kibitz engine Thinking Output to ICS, and capture opponent kibitz for in PGN\r
556     </td><td>\r
557       -\r
558   </td></tr><tr><td>\r
559       -zippyShortGame 0 (x)\r
560     </td><td>\r
561       ban opponents on ICS that abort without playing\r
562     </td><td>\r
563       -\r
564   </td></tr><tr><td>\r
565       \r
566     </td><td bgcolor="lightblue">\r
567       <strong>MISCELLANEOUS</strong>\r
568     </td><td>\r
569       \r
570   </td></tr><tr><td>\r
571       -debugFile "winboard.debug" (x)\r
572       <br>\r
573       -nameOfDebugFile "winboard.debug" (x)\r
574     </td><td>\r
575       allows you to specify an alternative name for saving the debug information\r
576     </td><td>\r
577       -\r
578   </td></tr><tr><td>\r
579       -engineDebugOutput 0 (x)\r
580     </td><td>\r
581       tells WinBoard if and how to put protocol-violating output in the debug file\r
582     </td><td>\r
583       -\r
584   </td></tr><tr><td>\r
585       -\r
586     </td><td>\r
587       save chess-board display as diagram in bitmap file\r
588       (only works for the smaller board formats!)\r
589     </td><td>\r
590       File -> Save Diagram...\r
591   </td></tr><tr><td>\r
592       -defaultFrcPosition -1 (*x)\r
593     </td><td>\r
594       specify the number of the starting position in shuffle Chess variants\r
595     </td><td>\r
596       File -> New Shuffle Game... (x)\r
597   </td></tr><tr><td>\r
598       -\r
599     </td><td>\r
600       display only those lines in the game list that contain a given string\r
601     </td><td>\r
602       in Game-List window\r
603   </td></tr><tr><td>\r
604       -rewindFile 0 (x)\r
605     </td><td>\r
606       A nonzero value for this option causes the loadGameIndex or loadPositionIndex\r
607       to rewind to the beginning of the Games or Position file when it reaches\r
608       the given value in auto-increment match mode. \r
609       This mode is specified by a negative value as argument of the /lgi or /lpi options,\r
610       where -1 increments the index after every game of the match,\r
611       and -2 after every two games (so that each position is played with black and white).\r
612     </td><td>\r
613       -\r
614   </td></tr><tr><td>\r
615       -sameColorGames 0 (x)\r
616     </td><td>\r
617       play a match, but without alternating the colors (overrules -matchGames)\r
618     </td><td>\r
619       -\r
620 </td></tr></table>\r
621 <p>\r
622 The value with which the option is listed is the default value.\r
623 If it is false or true, it is a Boolean option, a number implies an integer option.\r
624 A value starting with # indicates an RGB color indication in hexadecimal notation.\r
625 Options the settings of which are saved into the winboard.ini file are marked with (*).\r
626 </p>\r
627 </body>\r