1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<title>Chess Engine Communication Protocol</title>
</head>
<body>
<hr noshade size="2">
<h1>Chess Engine Communication Protocol</h1>
<h2><a href="http://www.tim-mann.org/chess.html">Tim Mann</a></h2>
<p>
Last modified on Sun Sep 17 23:37:17 PDT 2000 by mann
<hr noshade size="2">
<ul>
<li><a href="#1">1. Introduction</a>
<li><a href="#2">2. Connection</a>
<li><a href="#3">3. Debugging</a>
<li><a href="#4">4. How it got this way</a>
<li><a href="#5">5. WinBoard requires Win32 engines</a>
<li><a href="#6">6. Hints on input/output</a>
<li><a href="#7">7. Interrupts</a>
<li><a href="#8">8. Commands from xboard to the engine</a>
<li><a href="#9">9. Commands from the engine to xboard</a>
<li><a href="#10">10. Thinking Output</a>
<li><a href="#11">11. Time control</a>
<li><a href="#12">12. Analyze Mode</a>
<li><a href="#13">13. Idioms and backward compatibility features</a>
</ul>
<hr noshade size="2">
<h2><a name="1">1. Introduction</a></h2>
<p>
This document is a set of rough notes on the protocol that xboard and
WinBoard use to communicate with gnuchessx and other chess engines.
These notes may be useful if you want to connect a different chess
engine to xboard. Throughout the notes, "xboard" means both xboard
and WinBoard except where they are specifically contrasted.
</p>
<p>
There are two reasons I can imagine someone wanting to do this:
</p>
<ol>
<li>You have, or are developing, a chess engine but you don't want to
write your own graphical interface.
<li>You have, or are developing,a chess engine, and you want to
interface it to the Internet Chess Server.
</ol>
<p>
In case (2), if you are using xboard, you will need to configure the
"Zippy" code into it, but WinBoard includes this code already. See
the file <a
href="http://www.tim-mann.org/xboard/zippy.README">zippy.README</a>
in the xboard or WinBoard distribution for more information.
</p>
<p>
These notes are unpolished, but I've attempted to make them complete
in this release. If you notice any errors, omissions, or misleading
statements, let me know.
</p>
<p>
I'd like to hear from everyone who is trying to interface their own
chess engine to xboard/WinBoard. Please email me, <a
href="mailto:[email protected]">[email protected]</a>. Also, please join
the mailing list for authors of xboard/WinBoard compatible chess
engines. The list is now hosted by egroups.com; you can join at <a
href="http://www.egroups.com/group/chess-engines"
>http://www.egroups.com/group/chess-engines</a>, or you can read the
list there without joining. The list is filtered to prevent spam.
</p>
<h2><a name="2">2. Connection</a></h2>
<p>
An xboard chess engine runs as a separate process from xboard itself,
connected to xboard through a pair of anonymous pipes. The engine
does not have to do anything special to set up these pipes. xboard
sets up the pipes itself and starts the engine with one pipe as its
standard input and the other as its standard output. The engine then
reads commands from its standard input and writes responses to its
standard output. This is, unfortunately, a little more complicated to
do right than it sounds; see <a href="#6">section 6</a> below.
</p>
<p>
And yes, contrary to some people's expectations, exactly the same
thing is true for WinBoard. Pipes and standard input/output are
implemented in Win32 and work fine. You don't have to use DDE, COM,
DLLs, BSOD, or any of the other infinite complexity that
Microsoft has created just to talk between two programs. A WinBoard
chess engine is a Win32 console program that simply reads from its
standard input and writes to its standard output. See sections
<a href="#5">5</a> and <a href="#6">6</a> below for additional details.
</p>
<h2><a name="3">3. Debugging</a></h2>
<p>
To diagnose problems in your engine's interaction with xboard, use the
-debug flag on xboard's command line to see the messages that are
being exchanged. In WinBoard, these messages are written to the file
WinBoard.debug instead of going to the screen.
</p>
<p>
You can turn debug mode on or off while WinBoard is running by
pressing Ctrl+Alt+F12. You can turn debug mode on or off while xboard
is running by binding DebugProc to a shortcut key (and pressing the
key!); see the instructions on shortcut keys in the xboard man page.
</p>
<p>
While your engine is running under xboard/WinBoard, you can send a
command directly to the engine by pressing Shift+1 (xboard) or Alt+1
(WinBoard 4.0.3 and later). This brings up a dialog that you can type
your command into. Press Shift+2 (Alt+2) instead to send to the
second chess engine in Two Machines mode. On WinBoard 4.0.2 and earlier,
Ctrl+Alt is used in place of Alt; this had to be changed due to a conflict
with typing the @-sign on some European keyboards.
</p>
<h2><a name="4">4. How it got this way</a></h2>
<p>
Originally, xboard was just trying to talk to the existing
command-line interface of gnuchess, designed for people to type
commands to. So the communication protocol is very ad-hoc. (The
reason why there is a gnuchessx that's different from gnuchessr is
buried in the mists of time, before I started working on xboard, but I
think it was due to someone working around a stupid bug in xboard by
changing gnuchess instead of fixing the bug. The differences are
tiny.) It's now tough to change the interface, because xboard and
gnuchess are separate programs, and I don't want to force people to
upgrade them together to versions that match.
</p>
<p>
Things have changed a bit now that there are many more engines that
work with xboard. I've had to make the protocol description more
precise, and I've added some features that GNU Chess does not support.
In the latest version, I've specified a standard semantics for many
commands that differs in some details from what GNU Chess provides,
but is easier to work with. In the future I may release a modified
GNU Chess that conforms exactly to this protocol.
</p>
<h2><a name="5">5. WinBoard requires Win32 engines</a></h2>
<p>
Due to some Microsoft brain damage that I don't understand, WinBoard
does not work with chess engines that were compiled to use a DOS
extender for 32-bit addressing. (Probably not with 16-bit DOS or
Windows programs either.) WinBoard works only with engines that are
compiled for the Win32 API. You can get a free compiler that targets
the Win32 API from <a href="http://sourceware.cygnus.com/cygwin/"
>http://sourceware.cygnus.com/cygwin/</a>. I think DJGPP 2.x should
also work if you use the RSXNTDJ extension, but I haven't tried it.
Of course, Microsoft Visual C++ will work. Most likely the other
commercial products that support Win32 will work too (Borland, etc.),
but I have not tried them.
</p>
<h2><a name="6">6. Hints on input/output</a></h2>
<p>
Beware of using buffered I/O in your chess engine. The C stdio
library, C++ streams, and the I/O packages in most other languages use
buffering both on input and output. That means two things. First,
when your engine tries to write some characters to xboard, the library
stashes them in an internal buffer and does not actually write them to
the pipe connected to xboard until either the buffer fills up or you
call a special library routine asking for it to be flushed. (In C
stdio, this routine is named <tt>fflush</tt>.) Second, when your engine tries
to read some characters from xboard, the library does not read just
the characters you asked for -- it reads all the characters that are
currently available (up to some limit) and stashes any characters you
are not yet ready for in an internal buffer. The next time you ask to
read, you get the characters from the buffer (if any) before the
library tries to read more data from the actual pipe.
</p>
<p>
Why does this cause problems? First, on the output side, remember
that your engine produces output in small quantities (say, a few
characters for a move, or a line or two giving the current analysis),
and that data always needs to be delivered to xboard/WinBoard for
display immediately. If you use buffered output, the data you print
will sit in a buffer in your own address space instead of being
delivered.
</p>
<p>
You can usually fix the output buffering problem by asking for the
buffering to be turned off. In C stdio, you do this by calling
<tt>setbuf(stdout, NULL)</tt>. A more laborious and error-prone
method is to carefully call <tt>fflush(stdout)</tt> after every line
you output; I don't recommend this. In C++, you can try
<tt>cout.setf(ios::unitbuf)</tt>, which is documented in current
editions of "The C++ Programming Language," but not older ones.
Another C++ method that might work is
<tt>cout.rdbuf()->setbuf(NULL, 0)</tt>. Alternatively, you can
carefully call <tt>cout.flush()</tt> after every line you output;
again, I don't recommend this.
</p>
<p>
Another way to fix the problem is to use unbuffered operating system
calls to write directly to the file descriptor for standard output.
On Unix, this means <tt>write(1, ...)</tt> -- see the man page for write(2).
On Win32, you can use either the Unix-like <tt>_write(1, ...)</tt> or Win32
native routines like <tt>WriteFile</tt>.
</p>
<p>
Second, on the input side, you are likely to want to poll during your
search and stop it if new input has come in. If you implement
pondering, you'll need this so that pondering stops when the user
makes a move. You should also poll during normal thinking on your
move, so that you can implement the "?" (move now) command, and so
that you can respond promptly to a "result", "force", or "quit"
command if xboard wants to end the game or terminate your engine.
Buffered input makes polling more complicated -- when you poll, you
must stop your search if there are <em>either</em> characters in the buffer
<em>or</em> characters available from the underlying file descriptor.
</p>
<p>
The most direct way to fix this problem is to use unbuffered operating
system calls to read (and poll) the underlying file descriptor
directly. On Unix, use <tt>read(0, ...)</tt> to read from standard input, and
use <tt>select()</tt> to poll it. See the man pages read(2) and select(2).
(Don't follow the example of GNU Chess and use the FIONREAD ioctl to
poll for input. It is not very portable; that is, it does not exist
on all versions of Unix, and is broken on some that do have it.) On
Win32, you can use either the Unix-like <tt>_read(0, ...)</tt> or the native
Win32 <tt>ReadFile()</tt> to read. Unfortunately, under Win32, the function to
use for polling is different depending on whether the input device is
a pipe, a console, or something else. (More Microsoft brain damage
here -- did they never hear of device independence?) For pipes, you
can use <tt>PeekNamedPipe</tt> to poll (even when the pipe is unnamed).
For consoles,
you can use <tt>GetNumberOfConsoleInputEvents</tt>. For sockets only, you can
use <tt>select()</tt>. It might be possible to use
<tt>WaitForSingleObject</tt> more
generally, but I have not tried it. Some code to do these things can
be found in Crafty's utility.c, but I don't guarantee that it's all
correct or optimal.
</p>
<p>
A second way to fix the problem might be to ask your I/O library not
to buffer on input. It should then be safe to poll the underlying
file descriptor as descrbed above. With C, you can try calling
<tt>setbuf(stdin, NULL)</tt>. However, I have never tried this. Also, there
could be problems if you use <tt>scanf()</tt>, at least with certain patterns,
because <tt>scanf()</tt> sometimes needs to read one extra character and "push
it back" into the buffer; hence, there is a one-character pushback
buffer even if you asked for stdio to be unbuffered. With C++, you
can try <tt>cin.rdbuf()->setbuf(NULL, 0)</tt>, but again, I have never tried
this.
</p>
<p>
A third way to fix the problem is to check whether there are
characters in the buffer whenever you poll. C I/O libraries generally
do not provide any portable way to do this. Under C++, you can use
<tt>cin.rdbuf()->in_avail()</tt>. This method has been reported to
work with
EXchess. Remember that if there are no characters in the buffer, you
still have to poll the underlying file descriptor too, using the
method descrbed above.
</p>
<p>
A fourth way to fix the problem is to use a separate thread to read
from stdin. This way works well if you are familiar with thread
programming. This thread can be blocked waiting for input to come in
at all times, while the main thread of your engine does its thinking.
When input arrives, you have the thread put the input into a buffer
and set a flag in a global variable. Your search routine then
periodically tests the global variable to see if there is input to
process, and stops if there is. WinBoard and my Win32 ports of ICC
timestamp and FICS timeseal use threads to handle multiple input
sources.
</p>
<h2><a name="7">7. Signals</a></h2>
<p>Engines that run on Unix need to be concerned with two Unix
signals: <tt>SIGTERM</tt> and <tt>SIGINT</tt>. This applies both to
engines that run under xboard and (the unusual case of) engines that
WinBoard remotely runs on a Unix host using the -firstHost or
-secondHost feature. It does not apply to engines that run on
Windows, because Windows does not have Unix-style signals.</p>
<p>First, when an engine is sent the "quit" command, it is also given a
<tt>SIGTERM</tt> signal shortly afterward to make sure it goes away. If your
engine reliably responds to "quit", and the signal causes problems for
you, you should ignore it by calling <tt>signal(SIGTERM, SIG_IGN)</tt> at the
start of your program.</p>
<p>Second,
xboard will send an interrupt signal (<tt>SIGINT</tt>) at certain times when it
believes the engine may not be listening to user input (thinking or
pondering). WinBoard currently does this only when the engine is
running remotely using the -firstHost or -secondHost feature, not when
it is running locally. You probably need to know only enough about
this grungy feature to keep it from getting in your way.
</p>
<p>
The <tt>SIGINT</tt>s are basically tailored to the needs of GNU Chess on
systems where its input polling code is broken or disabled. Because
they work in a rather peculiar way, it is recommended that you simply
ignore <tt>SIGINT</tt> when running under Unix in xboard mode. You can do this
by having your engine call <tt>signal(SIGINT, SIG_IGN)</tt>. Alternatively,
you can configure your personal copy of xboard to not send <tt>SIGINT</tt> by
running configure with the --disable-sigint option. This won't help
you if you give your engine to other people who don't want to
recompile their xboard and possibly break its interaction with GNU
Chess.
</p>
<p>
Here are details for the curious. If xboard needs to send a command
when it is the chess engine's move (such as before the "?" command),
it sends a <tt>SIGINT</tt> first. If xboard needs to send commands when it is
not the chess engine's move, but the chess engine may be pondering
(thinking on its opponent's time) or analyzing (analysis or analyze
file mode), xboard sends a <tt>SIGINT</tt> before the first such command only.
Another <tt>SIGINT</tt> is not sent until another move is made, even if xboard
issues more commands. This behavior is necessary for GNU Chess. The
first <tt>SIGINT</tt> stops it from pondering until the next move, but on some
systems, GNU Chess will die if it receives a <tt>SIGINT</tt> when not actually
thinking or pondering.
</p>
<p>
There are two reasons why WinBoard does not send the Win32 equivalent
of <tt>SIGINT</tt> (which is called <tt>CTRL_C_EVENT</tt>) to local engines. First, the
Win32 GNU Chess port does not need it. Second, I could not find a way
to get it to work. Win32 seems to be designed under the assumption
that only console applications, not windowed applications, would ever
want to send a <tt>CTRL_C_EVENT</tt>. (More Microsoft brain damage.)
</p>
<h2><a name="8">8. Commands from xboard to the engine</a></h2>
<p>
All commands from xboard to the engine end with a newline (\n), even
where that is not explicitly stated. All your output to xboard must
be in complete lines; any form of prompt or partial line will cause
problems.
</p>
<p>
At the beginning of each game, xboard sends an initialization string.
This is currently "new\nrandom\n" unless the user changes it with the
initString or secondInitString option.
</p>
<p>
xboard normally reuses the same chess engine process for multiple
games. At the end of a game, xboard will send the
"force" command (see
below) to make sure your engine stops thinking about the current
position. It will later send the initString again to start a new
game. If your engine can't play multiple games, give xboard the
-xreuse (or -xreuse2) command line option to disable reuse. xboard
will then ask the process to quit after each game and start a new
process for the next game.
</p>
<dl>
<dt><strong>xboard</strong>
<dd>This command will be sent once immediately after your engine
process is started. You can use it to put your engine into "xboard
mode" if that is needed. If your engine prints a prompt to ask for
user input, you must turn off the prompt and output a newline when the
"xboard" command comes in.
<p>
<dt><strong>new</strong>
<dd>Reset the board to the standard chess starting position. Set
White on move. Leave force mode and set the engine to play Black.
Associate the engine's clock with Black and the opponent's clock with
White. Reset clocks and time controls to the start of a new game.
Stop clocks. Do not ponder on this move, even if pondering is on.
Remove any search depth limit previously set by the sd command.
<p>
<dt><strong>variant VARNAME</strong>
<dd>If the game is not standard chess, but a variant, this command is
sent after "new" and before the first move or "edit" command. Currently
defined variant names are:
<table>
<tr align="left"><th>wildcastle<td>Shuffle chess where king can castle from d file
<tr align="left"><th>nocastle<td>Shuffle chess with no castling at all
<tr align="left"><th>fischerandom<td>FischeRandom (not supported yet)
<tr align="left"><th>bughouse<td>Bughouse, ICC/FICS rules
<tr align="left"><th>crazyhouse<td>Crazyhouse, ICC/FICS rules
<tr align="left"><th>losers<td>Win by losing all pieces or getting mated (ICC)
<tr align="left"><th>suicide<td>Win by losing all pieces including king (FICS)
<tr align="left"><th>twokings<td>Weird ICC wild 9
<tr align="left"><th>kriegspiel<td>Kriegspiel (not really supported)
<tr align="left"><th>atomic<td>Atomic (not really supported)
<tr align="left"><th>3check<td>Win by giving check 3 times (not supported)
<tr align="left"><th>unknown<td>Unknown variant (not supported)
</table>
<p>
<dt><strong>quit</strong>
<dd>The chess engine should immediately exit. This command is used
when xboard is itself exiting, and also between games if the -xreuse
command line option is given (or -xreuse2 for the second engine).
See also <a href="#7">Signals</a> above.
<p>
<dt><strong>random</strong>
<dd>This command is specific to GNU Chess. You can either ignore it
completely (that is, treat it as a no-op) or implement it as GNU Chess
does. The command toggles "random" mode (that is, it sets random =
!random). In random mode, the engine adds a small random value to its
evaluation function to vary its play. The "new" command sets random
mode off.
<p>
<dt><strong>force</strong>
<dd>Set the engine to play neither color ("force mode"). Stop clocks.
The engine should check that moves received in force mode are legal
and made in the proper turn, but should not think, ponder, or make
moves of its own.
<p>
<dt><strong>white</strong>
<dd>Set White on move. Set the engine to play Black. Stop clocks.
<p>
<dt><strong>black</strong>
<dd>Set Black on move. Set the engine to play White. Stop clocks.
<p>
<dt><strong>level MPS BASE INC</strong>
<dd>Set time controls. See the <a href="#11">Time Control</a> section below.
<p>
<dt><strong>st TIME</strong>
<dd>Set time controls. See the <a href="#11">Time Control</a> section
below. The commands "level" and "st" are not used together.
<p>
<dt><strong>sd DEPTH</strong>
<dd>The engine should limit its thinking to DEPTH ply.
<p>
<dt><strong>time N</strong>
<dd>Set a clock that always belongs to the engine. N is a number in
centiseconds (units of 1/100 second). Even if the engine changes to
playing the opposite color, this clock remains with the engine.
<p>
<dt><strong>otim N</strong>
<dd>Set a clock that always belongs to the opponent. N is a number in
centiseconds (units of 1/100 second). Even if the opponent changes to
playing the opposite color, this clock remains with the opponent.
<p>
If needed for purposes of board display in force mode (where the
engine is not participating in the game) the time clock should be
associated with the last color that the engine was set to play, the
otim clock with the opposite color.
</p>
<p>
If you can't handle the time and otim commands, you can ignore them
(that is, treat them as no-ops); or better, send back "Error (unknown
command): time" the first time you see "time", and xboard will realize
you don't implement the command.
</p>
<dt><strong>go</strong>
<dd>Leave force mode and set the engine to play the color that is on
move. Associate the engine's clock with the color that is on move,
the opponent's clock with the opposite color. Start the engine's
clock. Start thinking and eventually make a move.
<p>
<dt><strong>MOVE</strong>
<dd>See below for the syntax of moves. If the move is illegal, print
an error message; see the section "<a href="#9">Commands from the engine to
xboard</a>". If the move is legal and in turn, make it. If not in force
mode, stop the opponent's clock, start the engine's clock, start
thinking, and eventually make a move.
<p>
When xboard sends your engine a move, it always sends coordinate
algebraic notation. There is no command name; the notation is just
sent as a line by itself. Examples:
<p>
<table>
<tr align="left"><td>Normal moves:<td>e2e4
<tr align="left"><td>Pawn promotion:<td>e7e8q
<tr align="left"><td>Castling:<td>e1g1, e1c1, e8g8, e8c8
<tr align="left"><td>Bughouse drop:<td>P@h3
<tr align="left"><td>ICS Wild 0/1 castling:<td>d1f1, d1b1, d8f8, d8b8
<tr align="left"><td>FischerRandom castling:<td>o-o, o-o-o (future)
</table>
<p>
If your engine can't handle this kind of output, change the routine
SendMoveToProgram in backend.c to send the kind of notation you need.
If you define SAN_TO_PROGRAM, your engine will be sent Standard
Algebraic Notation (as defined by the PGN standard); for example, e4,
Nf3, exd5, Bxf7+, Qxf7#, e8=Q, O-O, or P@h3. (The P@h3 notation is a
nonstandard extension to SAN.) In the future, I may make
SAN_TO_PROGRAM a runtime option if there is demand for it.
</p>
<p>
xboard doesn't reliably detect illegal moves, because it does not keep
track of castling unavailablity due to king or rook moves, or en
passant availability. If xboard sends an illegal move, send back an
error message so that xboard can retract it and inform the user; see
the section "<a href="#9">Commands from the engine to xboard</a>".
</p>
<dt><strong>?</strong>
<dd>Move now. If your engine is thinking, it should move immediately;
otherwise, the command should be ignored (treated as a no-op). It
is permissible for your engine to always ignore the ? command. The
only bad consequence is that xboard's Move Now menu command will do
nothing.
<p>
It is also permissible for your engine to move immediately if it gets
any command while thinking, as long as it processes the command right
after moving, but it's preferable if you don't do this. For example,
xboard may send post, nopost, easy, hard, force, or quit while the
engine is on move.
</p>
<dt><strong>draw</strong>
<dd>The engine's opponent offers the engine a draw. To accept the
draw, send "offer draw". To decline, ignore the offer (that is, send
nothing). If you're playing on ICS, it's possible for the draw offer
to have been withdrawn by the time you accept it, so don't assume the
game is over because you accept a draw offer. Continue playing until
xboard tells you the game is over. See also "offer draw" below.
<p>
<dt><strong>result RESULT {COMMENT}</strong>
<dd>After the end of each game, xboard will send you a result command.
You can use this command to trigger learning. RESULT is either 1-0,
0-1, 1/2-1/2, or *, indicating whether white won, black won, the game
was a draw, or the game was unfinished. The COMMENT string is purely
a human-readable comment; its content is unspecified and subject to
change. In ICS mode, it is passed through from ICS uninterpreted.
Example: <pre>result 1-0 {White mates}</pre>
<p>
Here are some notes on interpreting the "result" command. Some apply
only to playing on ICS ("Zippy" mode).
</p>
<p>
If you won but did not just play a mate, your opponent must have
resigned or forfeited. If you lost but were not just mated, you
probably forfeited on time, or perhaps the operator resigned manually.
If there was a draw for some nonobvious reason, perhaps your opponent
called your flag when he had insufficient mating material (or vice
versa), or perhaps the operator agreed to a draw manually.
</p>
<p>
You will get a result command even if you already know the game ended
-- for example, after you just checkmated your opponent. In fact, if
you send the "RESULT {COMMENT}" command (discussed below), you will
simply get the same thing fed back to you with "result" tacked in
front. You might not always get a "result *" command, however. In
particular, you won't get one in local chess engine mode when the user
stops playing by selecting Reset, Edit Game, Exit or the like.
</p>
<dt><strong>edit</strong>
<dd>The edit command puts the chess engine into a special mode, where
it accepts the following subcommands:
<table>
<tr align="left"><th>c<td>change current piece color, initially white
<tr align="left"><th>Pa4 (for example)<td>place pawn of current color on a4
<tr align="left"><th>xa4 (for example)<td>empty the square a4 (not used by xboard)
<tr align="left"><th>#<td>clear board
<tr align="left"><th>.<td>leave edit mode
</table>
<p>The edit command does not change the side to move. To set up a
black-on-move position, xboard uses the following command sequence:
</p>
<pre>
new
force
a2a3
edit
<edit commands>
.
</pre>
<p>
This sequence is used for compatibility with engines that do not
interpret the "black" command according to the specification above;
see "<a href="#13">Idioms</a>" below.
</p>
<p>
After an edit command is complete, if a king and a rook are on their
home squares, castling is assumed to be available to them. En passant
capture is assumed to be illegal on the current move regardless of the
positions of the pawns. The clock for the 50 move rule starts at
zero, and for purposes of the draw by repetition rule, no prior
positions are deemed to have occurred.
</p>
<dt><strong>hint</strong>
<dd>If the user asks for a hint, xboard sends your engine the command
"hint". Your engine should respond with "Hint: xxx", where xxx is a
suggested move. If there is no move to suggest, you can ignore the
hint command (that is, treat it as a no-op).
<p>
<dt><strong>bk</strong>
<dd>If the user selects "Book" from the xboard menu, xboard will send
your engine the command "bk". You can send any text you like as the
response, as long as each line begins with a blank space or tab (\t)
character, and you send an empty line at the end. The text pops up in
a modal information dialog.
<p>
<dt><strong>undo</strong>
<dd>If the user asks to back up one move, xboard will send you the
"undo" command. xboard will not send this command without putting you
in "force" mode first, so you don't have to worry about what should
happen if the user asks to undo a move your engine made. (GNU Chess
actually switches to playing the opposite color in this case.)
<p>
<dt><strong>remove</strong>
<dd>If the user asks to retract a move, xboard will send you the
"remove" command. It sends this command only when the user is on
move. Your engine should undo the last two moves (one for each
player) and continue playing the same color.
<p>
<dt><strong>hard</strong>
<dd>Turn on pondering (thinking on the opponent's time, also known as
"permanent brain"). xboard will not make any assumption about what
your default is for pondering or whether "new" affects this setting.
<p>
<dt><strong>easy</strong>
<dd>Turn off pondering.
<p>
<dt><strong>post</strong>
<dd>Turn on thinking/pondering output.
See <a href="#10">Thinking Output</a> section.
<p>
<dt><strong>nopost</strong>
<dd>Turn off thinking/pondering output.
<p>
<dt><strong>analyze</strong>
<dd>Enter analyze mode. See <a href="#12">Analyze Mode</a> section.
</dl>
<h3>Here are some special commands for Zippy mode:</h3>
<dl>
<dt><strong>name X</strong>
<dd>In ICS mode, xboard obtains the name of its opponent from ICS when
a game starts and saves it for use in the PGN tags. In Zippy mode, it
also passes the opponent's name on to the chess engine with the name
command. Example: <pre>name mann</pre>
<dt><strong>rating</strong>
<dd>In ICS mode, xboard obtains the ICS opponent's rating from the
"Creating:" message that appears before each game. (This message may
not appear on servers using outdated versions of the FICS code.) In
Zippy mode, it sends these ratings on to the chess engine using the
"rating" command. The chess engine's own rating comes first, and if
either opponent is not rated, his rating is given as 0. Example:
<pre>rating 2600 1500</pre>
<dt><strong>computer</strong>
<dd>The opponent is on the ICS computer list.
</dl>
<h3>Bughouse commands:</h3>
<p>
xboard now supports bughouse engines when in Zippy mode. See
<a href="http://www.tim-mann.org/xboard/zippy.README"
>zippy.README</a> for information on Zippy mode and how to turn on the
bughouse support. The bughouse move format is given above. xboard
sends the following additional commands to the engine when in bughouse
mode. Commands to inform your engine of the partner's game state may
be added in the future.
</p>
<dl>
<dt><strong>partner <player></strong>
<dd><player> is now your partner for future games. Example: <pre>partner mann</pre>
<p>
<dt><strong>partner</strong>
<dd>Meaning: You no longer have a partner.
<p>
<dt><strong>ptell <text></strong>
<dd>Your partner told you <text>, either with a ptell or an ordinary tell.
<p>
<dt><strong>holding [<white>] [<black>]</strong>
<dd>White currently holds <white>; black currently holds <black>.
Example: <pre>holding [PPPRQ] []</pre>
<dt><strong>holding [<white>] [<black>] <color><piece></strong>
<dd>White currently holds <white>; black currently holds <black>, after
<color> acquired <piece>. Example: <pre>holding [PPPRQ] [R] BR</pre>
</dl>
<h2><a name="9">9. Commands from the engine to xboard</a></h2>
<dl>
<dt><strong>Illegal move: MOVE</strong>
<dt><strong>Illegal move (REASON): MOVE</strong>
<dd>If your engine receives a MOVE command that is recognizably a move
but is not legal in the current position, your engine must print an
error message in one of the above formats so that xboard can pass the
error on to the user and retract the move. The (REASON) is entirely
optional. Examples:
<pre>
Illegal move: e2e4
Illegal move (in check): Nf3
Illegal move (moving into check): e1g1
</pre>
<p>
Generally, xboard will never send an ambiguous move, so it does not
matter whether you respond to such a move with an Illegal move message
or an Error message.
</p>
<dt><strong>Error (ERRORTYPE): COMMAND</strong>
<dd>If your engine receives a command it does not understand or does
not implement, it should print an error message in the above format so
that xboard can parse it. Examples:
<pre>
Error (ambiguous move): Nf3
Error (unknown command): analyze
Error (command not legal now): undo
Error (too many parameters): level 1 2 3 4 5 6 7
</pre>
<p>
Note: versions of xboard prior to 3.6.11beta do not parse the "Error"
format. To ease the transition, it is acceptable to use the "Illegal
move" format for all errors, even if the command given was not a
move.
</p>
<dt><strong>move MOVE</strong>
<dd>Your engine is making the move MOVE. Do not echo moves from
xboard with this command; send only new moves made by the engine.
<p>
Note: versions of xboard prior to 3.6.11beta do not parse the above
format, so you may want to use the old "NUMBER ... MOVE" format
temporarily. See the section "<a href="#13">Idioms and backward
compatibility features</a>" below.
</p>
<p>
For the actual move text from your chess engine (in place of MOVE
above), xboard will accept any kind of unambiguous algebraic format,
including coordinate notation, SAN, and some slight variants of SAN.
You don't have to send the pure coordinate notation that xboard sends
to your engine; xboard parses the output with its general-purpose
move parser, which was built to extract human-typed game scores from
netnews messages. For example, the following will all work:
</p>
<pre>
e2e4
e4
Nf3
ed
exd
exd5
Nxd5
Nfd3
e8q
e8Q
e8=q
e8(Q)
e7e8q
o-o
O-O
0-0
</pre>
<p>
and many more.
</p>
<dt><strong>RESULT {COMMENT}</strong>
<dd>When your engine detects that the game has ended by rule
(checkmate, stalemate, triple repetition, the 50 move rule, or
insufficient material), your engine must output a line of the form
"RESULT {comment}" (without the quotes), where RESULT is a PGN result
code (1-0, 0-1, or 1/2-1/2), and comment is the reason. Examples:
<pre>
0-1 {Black mates}
1-0 {White mates}
1/2-1/2 {Draw by repetition}
1/2-1/2 {Stalemate}
</pre>
<p>
xboard relays the result to the user, the ICS, the other engine in Two
Machines mode, and the PGN save file as required.
</p>
<dt><strong>resign</strong>
<dd>If your engine wants to resign, it can send the command "resign".
Alternatively, it can use the "RESULT {comment}" command if the string
"resign" is included in the comment; for example "0-1 {White
resigns}". xboard relays the resignation to the user, the ICS, the
other engine in Two Machines mode, and the PGN save file as required.
<p>
<dt><strong>offer draw</strong>
<dd>If your engine wants to offer a draw by agreement (as opposed to
claiming a draw by rule), it can send the command "offer draw".
xboard relays the offer to the user, the ICS, the other engine in Two
Machines mode, and the PGN save file as required. In Machine White,
Machine Black, or Two Machines mode, the offer is considered valid
until your engine has made two more moves.
<p>
<dt><strong>telluser MESSAGE</strong>
<dd>xboard pops up a modal information dialog containing the message.
MESSAGE consists of any characters, including whitespace, to the end
of the line.
<p>
<dt><strong>tellusererror MESSAGE</strong>
<dd>xboard pops up a non-modal error dialog containing the message.
MESSAGE consists of any characters, including whitespace, to the end
of the line.
<p>
<dt><strong>askuser REPTAG MESSAGE</strong>
<dd>Here REPTAG is a string containing no whitespace, and MESSAGE
consists of any characters, including whitespace, to the end of the
line. xboard pops up a modal question dialog that says MESSAGE and
has a typein box. If the user types in "bar", xboard sends "REPTAG
bar" to the engine. The user can cancel the dialog and send nothing.
<p>
<dt><strong>tellics MESSAGE</strong>
<dd>In Zippy mode, xboard sends "MESSAGE\n" to ICS. MESSAGE consists
of any characters, including whitespace, to the end of the line.
</dl>
<h2><a name="10">10. Thinking Output</a></h2>
<p>
If the user asks your engine to "show thinking", xboard sends your
engine the "post" command. It sends "nopost" to turn thinking off.
In post mode, your engine sends output lines to show the progress of
its thinking. The engine can send as many or few of these lines as it
wants to, whenever it wants to. Typically they would be sent when the
PV (principal variation) changes or the depth changes. The thinking
output should be in the following format:
</p>
<pre>ply score time nodes pv</pre>
Where:
<table>
<tr align="left"><th>ply<td>Integer giving current search depth.
<tr align="left"><th>score<td>Integer giving current evaluation in centipawns.
<tr align="left"><th>time<td>Current search time in centiseconds (ex:
1028 = 10.28 seconds).
<tr align="left"><th>nodes<td>Nodes searched.
<tr align="left"><th>pv<td>Freeform text giving current "best" line.
You can continue the pv onto another line if you start each
continuation line with at least four space characters.
</table>
<p>
Example:
</p>
<pre> 9 156 1084 48000 Nf3 Nc6 Nc3 Nf6</pre>
<p>
Meaning:
</p>
9 ply, score=1.56, time = 10.84 seconds, nodes=48000,
PV = "Nf3 Nc6 Nc3 Nf6"
<p>
Longer example from actual Crafty output:
</p>
<pre>
4 109 14 1435 1. e4 d5 2. Qf3 dxe4 3. Qxe4 Nc6
4 116 23 2252 1. Nf3 Nc6 2. e4 e6
4 116 27 2589 1. Nf3 Nc6 2. e4 e6
5 141 44 4539 1. Nf3 Nc6 2. O-O e5 3. e4
5 141 54 5568 1. Nf3 Nc6 2. O-O e5 3. e4
</pre>
<p>
You can use the PV to show other things; for instance, while in book,
Crafty shows the observed frequency of different reply moves in its
book. In situations like this where your engine is not really
searching, start the PV with a '(' character:
</p>
<pre>
0 0 0 0 (e4 64%, d4 24%)
</pre>
<p>
GNU Chess output is very slightly different. The ply number is
followed by an extra nonblank character, and the time is in seconds,
not hundredths of seconds. For compatibility, xboard accepts the
extra character and takes it as a flag indicating the different time
units. Example:
</p>
<pre>
2. 14 0 38 d1d2 e8e7
3+ 78 0 65 d1d2 e8e7 d2d3
3& 14 0 89 d1d2 e8e7 d2d3
3& 76 0 191 d1e2 e8e7 e2e3
3. 76 0 215 d1e2 e8e7 e2e3
4& 15 0 366 d1e2 e8e7 e2e3 e7e6
4. 15 0 515 d1e2 e8e7 e2e3 e7e6
5+ 74 0 702 d1e2 f7f5 e2e3 e8e7 e3f4
5& 71 0 1085 d1e2 e8e7 e2e3 e7e6 e3f4
5. 71 0 1669 d1e2 e8e7 e2e3 e7e6 e3f4
6& 48 0 3035 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4
6. 48 0 3720 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4
7& 48 0 6381 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4
7. 48 0 10056 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4
8& 66 1 20536 d1e2 e8e7 e2e3 e7e6 e3d4 g7g5 a2a4 f7f5
8. 66 1 24387 d1e2 e8e7 e2e3 e7e6 e3d4 g7g5 a2a4 f7f5
9& 62 2 38886 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 a2a4 h5h4
d4e4
9. 62 4 72578 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 a2a4 h5h4
d4e4
10& 34 7 135944 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 c2c4 h5h4
d4e4 f7f5 e4f4
10. 34 9 173474 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 c2c4 h5h4
d4e4 f7f5 e4f4
</pre>
<p>If your engine is pondering (thinking on its opponent's time) in post
mode, it can show its thinking then too. In this case your engine may
omit the hint move (the move it is assuming its opponent will make)
from the thinking lines <em>if and only if</em> it sends xboard the move in
the usual "Hint: xxx" format before sending the first line.
</p>
<h2><a name="11">11. Time control</a></h2>
<p>
xboard supports three styles of time control: conventional chess clocks,
the ICS-style incremental clock, and an exact number of seconds per move.
</p>
<p>In conventional clock mode, every time control period is the same.
That is, if the time control is 40 moves in 5 minutes, then after each
side has made 40 moves, they each get an additional 5 minutes, and so
on, ad infinitum. At some future time it would be nice to support a
series of distinct time controls. This is very low on my personal
priority list, but code donations to the xboard project are accepted,
so feel free to take a swing at it. I suggest you talk to me first,
though.
</p>
<p>
The command to set a conventional time control looks like this:
</p>
<pre>
level 40 5 0
level 40 0:30 0
</pre>
<p>
The 40 means that there are 40 moves per time control. The 5 means
there are 5 minutes in the control. In the second example, the 0:30
means there are 30 seconds. The final 0 means that we are in
conventional clock mode.
</p>
<p>
The command to set an incremental time control looks like this:
</p>
<pre>
level 0 2 12
</pre>
<p>
Here the 0 means "play the whole game in this time control period",
the 2 means "base=2 minutes", and the 12 means "inc=12 seconds". As
in conventional clock mode, the second argument to level can be in
minutes and seconds.
</p>
<p>
At the start of the game, each player's clock is set to base minutes.
Immediately after a player makes a move, inc seconds are added to his
clock. A player's clock counts down while it is his turn. Your flag
can be called whenever your clock is zero or negative. (Your clock
can go negative and then become positive again because of the
increment.)
</p>
<p>
A special ICS rule: if you ask for a game with base=0, the clocks
really start at 10 seconds instead of 0. xboard itself does not know
about this rule currently, so it may pass the 0 on to the engine
instead of changing it to 0:10.
</p>
<p>
ICS also has time odds games. With time odds, each player has his own
(base, inc) pair, but otherwise things work the same as in normal
games. The Zippy xboard accepts time odds games but ignores the fact
that the opponent's parameters are different; this is perhaps not
quite the right thing to do, but gnuchess doesn't understand time
odds. Time odds games are always unrated.
</p>
<p>The command to set an exact number of seconds per move looks like this:
</p>
<pre>
st 30
</pre>
<p>
This means that each move must be made in 30 seconds. Time not used
on one move does not accumulate for use on later moves.
</p>
<h2><a name="12">12. Analyze Mode</a></h2>
<p>xboard supports analyzing fresh games, edited positions, and games
from files. However, all of these look the same from the chess
engine's perspective. Basically, the engine just has to respond to the
"analyze" command. If your engine does not support analyze mode, it
should print the error message "Error (unknown command): analyze" in
response to the "analyze" command.
</p>
<p>
To enter analyze mode, xboard sends the command sequence "post",
"white" or "black", "analyze". Analyze mode in your engine should be
similar to force mode, except that your engine thinks about what move
it would make next if it were on move. Your engine should accept the
following commands while in analyze mode:
</p>
<ul>
<li>Any legal move, as in force mode
<li>"undo"
<li>"new" (reset position to start of game but stay in analyze mode)
<li>"edit" (exiting edit mode returns to analyze mode)
<li>"exit" (leave analyze mode)
<li>"." (optional, see below)
</ul>
<p>
If the user selects "Periodic Updates", xboard will send the string
".\n" to the chess engine periodically during analyze mode, unless the
last PV received began with a '(' character.
</p>
<p>
The chess engine should respond to ".\n" with a line like this:
</p>
<pre>
stat01: time nodes ply mvleft mvtot
</pre>
Where:
<table>
<tr align="left"><th>time<td>Elapsed search time in centiseconds (ie: 567 = 5.67 seconds).
<tr align="left"><th>nodes<td>Nodes searched so far.
<tr align="left"><th>ply<td>Search depth so far.
<tr align="left"><th>mvleft<td>Number of moves left to consider at this depth.
<tr align="left"><th>mvtot<td>Total number of moves to consider.
</table>
<p>
Example:
</p>
<pre>
stat01: 1234 30000 7 5 30
</pre>
<p>
Meaning:
</p>
<p>After 12.34 seconds, I've searched 7 ply/30000 nodes, there are a
total of 30 legal moves, and I have 5 more moves to search
before going to depth 8.</p>
<p>
Implementation of the "." command is OPTIONAL. If the engine does not
respond to the "." command with a "stat01..." line, xboard will stop
sending "." commands. If the engine does not implement this command,
the analysis window will use a shortened format to display the engine
info.
</p>
<p>
To give the user some extra information, the chess engine can output
the strings "++\n" and "--\n", to indicate that the current search is
failing high or low, respectively. You don't have to send anything
else to say "Okay, I'm not failing high/low anymore." xboard will
figure this out itself.
</p>
<h2><a name="13">13. Idioms and backward compatibility features</a></h2>
<p>
Some engines have variant interpretations of the force/go/white/black,
time/otim, and hard/easy command sets. New engines should not use
these interpretations, but in order to accommodate existing engines,
xboard is currently very conservative about how it uses these
commands. Only the following idioms are currently used.
</p>
<dl>
<dt><strong>white</strong>
<dt><strong>go</strong>
<dd>Sent when the engine is in force mode or playing Black but should
switch to playing White. This sequence is sent only when White is
already on move.
<p>
<dt><strong>black</strong>
<dt><strong>go</strong>
<dd>Sent when the engine is in force mode or playing White but should
switch to playing Black. This sequence is sent only when Black is
already on move.
<p>
<dt><strong>time N</strong>
<dt><strong>otim N</strong>
<dt><strong>MOVE</strong>
<dd>Sent when the opponent makes a move and the engine is already
playing the opposite color.
<p>
<dt><strong>white</strong>
<dt><strong>time N</strong>
<dt><strong>otim N</strong>
<dt><strong>black</strong>
<dt><strong>go</strong>
<dd>Sent when Black is on move, the engine is in force mode or playing
White, and the engine's clock needs to be updated before it starts
playing. The initial "white" is a kludge to accommodate GNU Chess
4.0.77's variant interpretation of these commands. It may be removed
in the future, especially if it causes problems for other engines.
<p>
<dt><strong>black</strong>
<dt><strong>time N</strong>
<dt><strong>otim N</strong>
<dt><strong>white</strong>
<dt><strong>go</strong>
<dd>Sent when White is on move, the engine is in force mode or playing
Black, and the engine's clock needs to be updated before it starts
playing. See previous idiom.
<p>
<dt><strong>hard</strong>
<dt><strong>easy</strong>
<dd>Sent in sequence to turn off pondering if xboard is not sure
whether it is on. When xboard is sure, it will send "hard" or "easy"
alone. xboard does this because "easy" is a toggle in GNU Chess but
"hard" is an absolute on.
</dl>
<p>
To support older engines, certain additional commands from the engine
to xboard are also recognized. (These are commands by themselves, not
values to be placed in the comment field of the PGN result code.)
These forms are not recommended for new engines; use the PGN result
code commands or the resign command instead:
</p>
<table>
<tr align="left"><th>Command <th>Interpreted as
<tr align="left"><td>White resigns <td>0-1 {White resigns}
<tr align="left"><td>Black resigns <td>1-0 {Black resigns}
<tr align="left"><td>White <td>1-0 {White mates}
<tr align="left"><td>Black <td>0-1 {Black mates}
<tr align="left"><td>Draw <td>1/2-1/2 {Draw}
<tr align="left"><td>computer mates <td>1-0 {White mates} or 0-1 {Black mates}
<tr align="left"><td>opponent mates <td>1-0 {White mates} or 0-1 {Black mates}
<tr align="left"><td>computer resigns <td>0-1 {White resigns} or 1-0 {Black resigns}
<tr align="left"><td>game is a draw <td>1/2-1/2 {Draw}
<tr align="left"><td>checkmate <td>1-0 {White mates} or 0-1 {Black mates}
</table>
<p>
Commands in the above table are recognized if they begin a line and
arbitrary characters follow, so (for example) "White mates" will be
recognized as "White", and "game is a draw by the 50 move rule" will
be recognized as "game is a draw". All the commands are
case-sensitive.
</p>
<p>
An alternative move syntax is also recognized:
</p>
<table>
<tr align="left"><th>Command <th>Interpreted as
<tr align="left"><td>NUMBER ... MOVE <td>move MOVE
</table>
<p>
Here NUMBER means any string of decimal digits, optionally ending in a
period. MOVE is any string containing no whitespace. In this command
format, xboard requires the "..." even if your engine is playing
White. A command of the form NUMBER MOVE will be ignored. This odd
treatment of the commands is needed for compatibility with gnuchessx.
The original reasons for it are lost in the mists of time, but I
suspect it was originally a bug in the earliest versions of xboard,
before I started working on it, which someone "fixed" in the wrong
way, by creating a special version of gnuchess (gnuchessx) instead of
changing xboard.
</p>
<p>
Any line that contains the words "offer" and "draw" is recognized as
"offer draw".
</p>
<p>
The "Illegal move" message is recognized even if spelled "illegal
move" and even if the colon (":") is omitted. This accommodates GNU
Chess 4.0.77, which prints messages like "Illegal move (no matching
move)e2e4", and old versions of Crafty, which print just "illegal move".
</p>
<p>
In Zippy mode, for compatibility with existing versions of Crafty,
xboard passes through to ICS any line that begins "kibitz", "whisper",
"tell", or "draw". Do not use this feature in new code.
</p>
<p>
Before the "sd DEPTH" command, xboard also sends the command
"depth\nDEPTH", for the benefit of GNU Chess. Note the newline in the
middle of this command. Ugh.
</p>
<p>
For the benefit of GNU Chess, if an "st TIME"-style time control is
being used, TIME is also given to the engine as a command-line
argument when it is started. Ugh.
</p>
<hr noshade size="2">
<address>converted to HTML by <a href="http://www.jakob.at/steffen/">Steffen A. Jakob</a></address>
</body>
</html>
|
