WebSVN – Games.Chess Giants – Blame – /cecp.html

Rev	Author	Line No.	Line
128	pmbaty	1	<html>
		2	<head>
		3	<title>Chess Engine Communication Protocol</title>
		4	</head>
		5
		6	<body>
		7	<hr noshade size="2">
		8	<h1>Chess Engine Communication Protocol</h1>
		9	<h2><a href="http://www.tim-mann.org/">Tim Mann</a> & <a href="http://home.hccnet.nl/h.g.muller/winboardF.html">H.G.Muller</a></h2>
		10	<p>
		11	Version 2; implemented in xboard/WinBoard 4.2.1 and later. (Sept 3, 2009)<br>
		12	Changes since version 1 are indicated in <font color=red>red</font>.<br>
		13	Changes for WinBoard 4.3.xx are indicated in <font color=green>green</font>.<br>
		14	Changes for WinBoard 4.4.xx are indicated in <font color=blue>blue</font>.
		15	<hr noshade size="2">
		16
		17	<ul>
		18	<li><a href="#1">1. Introduction</a>
		19	<li><a href="#2">2. Connection</a>
		20	<li><a href="#3">3. Debugging</a>
		21	<li><a href="#4">4. How it got this way</a>
		22	<li><a href="#5">5. WinBoard requires Win32 engines</a>
		23	<li><a href="#6">6. Hints on input/output</a>
		24	<li><a href="#7">7. Signals</a>
		25	<li><a href="#8">8. Commands from xboard to the engine</a>
		26	<li><a href="#9">9. Commands from the engine to xboard</a>
		27	<li><a href="#10">10. Thinking Output</a>
		28	<li><a href="#11">11. Time control</a>
		29	<li><a href="#12">12. Analyze Mode</a>
		30	<li><a href="#13">13. Idioms and backward compatibility features</a>
		31	</ul>
		32
		33	<hr noshade size="2">
		34
		35	<h2><a name="1">1. Introduction</a></h2>
		36
		37	<p>
		38	This document is a set of rough notes on the protocol that xboard and
		39	WinBoard use to communicate with gnuchessx and other chess engines.
		40	These notes may be useful if you want to connect a different chess
		41	engine to xboard. Throughout the notes, "xboard" means both xboard
		42	and WinBoard except where they are specifically contrasted.
		43	</p>
		44
		45	<p>
		46	There are two reasons I can imagine someone wanting to do this:
		47	</p>
		48	<ol>
		49	<li>You have, or are developing, a chess engine but you don't want to
		50	write your own graphical interface.
		51	<li>You have, or are developing,a chess engine, and you want to
		52	interface it to the Internet Chess Server.
		53	</ol>
		54
		55	<p>
		56	In case (2), if you are using xboard, you will need to configure the
		57	"Zippy" code into it, but WinBoard includes this code already. See
		58	the file <a
		59	href="http://www.tim-mann.org/xboard/zippy.README">zippy.README</a>
		60	in the xboard or WinBoard distribution for more information.
		61
		62	</p>
		63
		64	<p>
		65	These notes are unpolished, but I've attempted to make them complete
		66	in this release. If you notice any errors, omissions, or misleading
		67	statements, let me know.
		68	</p>
		69
		70	<p>
		71	I'd like to hear from everyone who is trying to interface their own
		72	chess engine to xboard/WinBoard. Please join the mailing list for
		73	authors of xboard/WinBoard compatible chess engines and post a message
		74	about what you're doing. The list is now hosted by Yahoo Groups; you
		75	can join at <a href="http://groups.yahoo.com/group/chess-engines"
		76	>http://groups.yahoo.com/group/chess-engines</a>, or you can read the
		77	list there without joining. The list is filtered to prevent spam.
		78	</p>
		79	<p>
		80	<font color=green>
		81	Note that the WinBoard 4.3.xx line was developed independently of the
		82	original GNU project, by H.G.Muller.
		83	If you have questions about WinBoard 4.3.xx, or want to report bugs in it,
		84	report them in the appropriate section of the
		85	<a href="http://www.open-aurec.com/wbforum/">WinBoard forum</a>.
		86	</font>
		87	</p>
		88
		89	<h2><a name="2">2. Connection</a></h2>
		90
		91	<p>
		92	An xboard chess engine runs as a separate process from xboard itself,
		93	connected to xboard through a pair of anonymous pipes. The engine
		94	does not have to do anything special to set up these pipes. xboard
		95	sets up the pipes itself and starts the engine with one pipe as its
		96	standard input and the other as its standard output. The engine then
		97	reads commands from its standard input and writes responses to its
		98	standard output. This is, unfortunately, a little more complicated to
		99	do right than it sounds; see <a href="#6">section 6</a> below.
		100	</p>
		101
		102	<p>
		103	And yes, contrary to some people's expectations, exactly the same
		104	thing is true for WinBoard. Pipes and standard input/output are
		105	implemented in Win32 and work fine. You don't have to use DDE, COM,
		106	DLLs, BSOD, or any of the other infinite complexity that
		107	Microsoft has created just to talk between two programs. A WinBoard
		108	chess engine is a Win32 console program that simply reads from its
		109	standard input and writes to its standard output. See sections
		110	<a href="#5">5</a> and <a href="#6">6</a> below for additional details.
		111	</p>
		112
		113	<h2><a name="3">3. Debugging</a></h2>
		114
		115	<p>
		116	To diagnose problems in your engine's interaction with xboard, use the
		117	-debug flag on xboard's command line to see the messages that are
		118	being exchanged. In WinBoard, these messages are written to the file
		119	WinBoard.debug instead of going to the screen.
		120	</p>
		121
		122	<p>
		123	You can turn debug mode on or off while WinBoard is running by
		124	pressing Ctrl+Alt+F12. You can turn debug mode on or off while xboard
		125	is running by binding DebugProc to a shortcut key (and pressing the
		126	key!); see the instructions on shortcut keys in the xboard man page.
		127	</p>
		128
		129	<p>
		130	While your engine is running under xboard/WinBoard, you can send a
		131	command directly to the engine by pressing Shift+1 (xboard) or Alt+1
		132	(WinBoard 4.0.3 and later). This brings up a dialog that you can type
		133	your command into. Press Shift+2 (Alt+2) instead to send to the
		134	second chess engine in Two Machines mode. On WinBoard 4.0.2 and earlier,
		135	Ctrl+Alt is used in place of Alt; this had to be changed due to a conflict
		136	with typing the @-sign on some European keyboards.
		137	</p>
		138
		139	<h2><a name="4">4. How it got this way</a></h2>
		140
		141	<p>
		142	Originally, xboard was just trying to talk to the existing
		143	command-line interface of GNU Chess 3.1+ and 4, which was designed
		144	for people to type commands to. So the communication protocol is very
		145	ad-hoc. It might have been good to redesign it early on, but because
		146	xboard and GNU Chess are separate programs, I didn't want to force
		147	people to upgrade them together to versions that matched. I
		148	particularly wanted to keep new versions of xboard working with old
		149	versions of GNU Chess, to make it easier to compare the play of old
		150	and new gnuchess versions. I didn't foresee the need for a clean
		151	protocol to be used with other chess engines in the future.
		152	</p>
		153
		154	<p>
		155	Circumstances have changed over the years, and now there are many more
		156	engines that work with xboard. I've had to make the protocol
		157	description more precise, I've added some features that GNU Chess
		158	does not support, and I've specified the standard semantics of a few
		159	features to be slightly different from what GNU Chess 4 does.
		160	</p>
		161
		162	<p>
		163	<font color=red>
		164	This release of the protocol specification is the first to carry a
		165	version number of its own -- version 2. Previous releases simply
		166	carried a last-modified date and were loosely tied to specific
		167	releases of xboard and WinBoard. The version number "1" applies
		168	generally to all those older versions of the protocol.
		169	</font>
		170
		171	<font color=red>
		172	<p>Protocol version 2 remains compatible with older engines but has
		173	several new capabilities. In particular, it adds the
		174	"feature" command, a new mechanism for making backward-compatible
		175	changes and extensions to the protocol. Engines that do not support a
		176	particular new feature do not have to use it; new features are not
		177	enabled unless the engine specifically requests them using the feature
		178	command. If an engine does not send the feature command at all, the
		179	protocol behavior is nearly identical to version 1. Several new
		180	features can be selected by the feature command in version 2,
		181	including the "ping" command (recommended for all engines), the
		182	"setboard" command, and many optional parameters. Additional features
		183	will probably be added in future versions.
		184	</p>
		185
		186	<p>
		187	<font color=green>
		188	If it is necessary to have a separate name,
		189	it would be best to refer to the protocol including the green additions as version 2f.
		190	I really don't think it is a different protocol from version 2, though.
		191	I just tried to clarify some ambiguities in the original definition,
		192	now that the WinBoard 4.3.xx line has implemented them in a specific way.
		193	The hand-shaking protocol for features as defined in protocol 2 perfectly
		194	allows addition of an occasional new features without any need for stepping up the protocol version number,
		195	and I think refraining from the latter would enormously lower the barrier for actual
		196	implementation of these features in engines.
		197	<br>
		198	The two really new things are the engine debug comments, and the "nps" command.
		199	The former merely tries to regulate an extremely common existing pactice
		200	of having engines dump debug messages on WinBoard in an unprotected way,
		201	as usually you get away with that.
		202	</font>
		203
		204	</font>
		205
		206	<h2><a name="5">5. WinBoard requires Win32 engines</a></h2>
		207
		208	<p>
		209	Due to some Microsoft brain damage that I don't understand, WinBoard
		210	does not work with chess engines that were compiled to use a DOS
		211	extender for 32-bit addressing. (Probably not with 16-bit DOS or
		212	Windows programs either.) WinBoard works only with engines that are
		213	compiled for the Win32 API. You can get a free compiler that targets
		214	the Win32 API from <a href="http://sources.redhat.com/cygwin/"
		215	>http://sources.redhat.com/cygwin/</a>. I think DJGPP 2.x should also
		216	work if you use the RSXNTDJ extension, but I haven't tried it. Of
		217	course, Microsoft Visual C++ will work. Most likely the other
		218	commercial products that support Win32 will work too (Borland, etc.),
		219	but I have not tried them. Delphi has been successfully used to write
		220	engines for WinBoard; if you want to do this, Tony Werten has donated
		221	some <a href="http://www.tim-mann.org/winboard/delphi.txt" >sample
		222	code</a> that should help you get started.
		223	</p>
		224
		225	<h2><a name="6">6. Hints on input/output</a></h2>
		226
		227	<p>
		228	Beware of using buffered I/O in your chess engine. The C stdio
		229	library, C++ streams, and the I/O packages in most other languages use
		230	buffering both on input and output. That means two things. First,
		231	when your engine tries to write some characters to xboard, the library
		232	stashes them in an internal buffer and does not actually write them to
		233	the pipe connected to xboard until either the buffer fills up or you
		234	call a special library routine asking for it to be flushed. (In C
		235	stdio, this routine is named <tt>fflush</tt>.) Second, when your engine tries
		236	to read some characters from xboard, the library does not read just
		237	the characters you asked for -- it reads all the characters that are
		238	currently available (up to some limit) and stashes any characters you
		239	are not yet ready for in an internal buffer. The next time you ask to
		240	read, you get the characters from the buffer (if any) before the
		241	library tries to read more data from the actual pipe.
		242	</p>
		243
		244	<p>
		245	Why does this cause problems? First, on the output side, remember
		246	that your engine produces output in small quantities (say, a few
		247	characters for a move, or a line or two giving the current analysis),
		248	and that data always needs to be delivered to xboard/WinBoard for
		249	display immediately. If you use buffered output, the data you print
		250	will sit in a buffer in your own address space instead of being
		251	delivered.
		252	</p>
		253
		254	<p>
		255	You can usually fix the output buffering problem by asking for the
		256	buffering to be turned off. In C stdio, you do this by calling
		257	<tt>setbuf(stdout, NULL)</tt>. A more laborious and error-prone
		258	method is to carefully call <tt>fflush(stdout)</tt> after every line
		259	you output; I don't recommend this. In C++, you can try
		260	<tt>cout.setf(ios::unitbuf)</tt>, which is documented in current
		261	editions of "The C++ Programming Language," but not older ones.
		262	Another C++ method that might work is
		263	<tt>cout.rdbuf()->setbuf(NULL, 0)</tt>. Alternatively, you can
		264	carefully call <tt>cout.flush()</tt> after every line you output;
		265	again, I don't recommend this.
		266	</p>
		267
		268	<p>
		269	Another way to fix the problem is to use unbuffered operating system
		270	calls to write directly to the file descriptor for standard output.
		271	On Unix, this means <tt>write(1, ...)</tt> -- see the man page for write(2).
		272	On Win32, you can use either the Unix-like <tt>_write(1, ...)</tt> or Win32
		273	native routines like <tt>WriteFile</tt>.
		274	</p>
		275
		276	<p>
		277	Second, on the input side, you are likely to want to poll during your
		278	search and stop it if new input has come in. If you implement
		279	pondering, you'll need this so that pondering stops when the user
		280	makes a move. You should also poll during normal thinking on your
		281	move, so that you can implement the "?" (move now) command, and so
		282	that you can respond promptly to a "result", "force", or "quit"
		283	command if xboard wants to end the game or terminate your engine.
		284	Buffered input makes polling more complicated -- when you poll, you
		285	must stop your search if there are <em>either</em> characters in the buffer
		286	<em>or</em> characters available from the underlying file descriptor.
		287	</p>
		288
		289	<p>
		290	The most direct way to fix this problem is to use unbuffered operating
		291	system calls to read (and poll) the underlying file descriptor
		292	directly. On Unix, use <tt>read(0, ...)</tt> to read from standard input, and
		293	use <tt>select()</tt> to poll it. See the man pages read(2) and select(2).
		294	(Don't follow the example of GNU Chess 4 and use the FIONREAD ioctl to
		295	poll for input. It is not very portable; that is, it does not exist
		296	on all versions of Unix, and is broken on some that do have it.) On
		297	Win32, you can use either the Unix-like <tt>_read(0, ...)</tt> or the native
		298	Win32 <tt>ReadFile()</tt> to read. Unfortunately, under Win32, the function to
		299	use for polling is different depending on whether the input device is
		300	a pipe, a console, or something else. (More Microsoft brain damage
		301	here -- did they never hear of device independence?) For pipes, you
		302	can use <tt>PeekNamedPipe</tt> to poll (even when the pipe is unnamed).
		303	For consoles,
		304	you can use <tt>GetNumberOfConsoleInputEvents</tt>. For sockets only, you can
		305	use <tt>select()</tt>. It might be possible to use
		306	<tt>WaitForSingleObject</tt> more
		307	generally, but I have not tried it. Some code to do these things can
		308	be found in Crafty's utility.c, but I don't guarantee that it's all
		309	correct or optimal.
		310	</p>
		311
		312	<p>
		313	A second way to fix the problem might be to ask your I/O library not
		314	to buffer on input. It should then be safe to poll the underlying
		315	file descriptor as described above. With C, you can try calling
		316	<tt>setbuf(stdin, NULL)</tt>. However, I have never tried this. Also, there
		317	could be problems if you use <tt>scanf()</tt>, at least with certain patterns,
		318	because <tt>scanf()</tt> sometimes needs to read one extra character and "push
		319	it back" into the buffer; hence, there is a one-character pushback
		320	buffer even if you asked for stdio to be unbuffered. With C++, you
		321	can try <tt>cin.rdbuf()->setbuf(NULL, 0)</tt>, but again, I have never tried
		322	this.
		323	</p>
		324
		325	<p>
		326	A third way to fix the problem is to check whether there are
		327	characters in the buffer whenever you poll. C I/O libraries generally
		328	do not provide any portable way to do this. Under C++, you can use
		329	<tt>cin.rdbuf()->in_avail()</tt>. This method has been reported to
		330	work with
		331	EXchess. Remember that if there are no characters in the buffer, you
		332	still have to poll the underlying file descriptor too, using the
		333	method described above.
		334	</p>
		335
		336	<p>
		337	A fourth way to fix the problem is to use a separate thread to read
		338	from stdin. This way works well if you are familiar with thread
		339	programming. This thread can be blocked waiting for input to come in
		340	at all times, while the main thread of your engine does its thinking.
		341	When input arrives, you have the thread put the input into a buffer
		342	and set a flag in a global variable. Your search routine then
		343	periodically tests the global variable to see if there is input to
		344	process, and stops if there is. WinBoard and my Win32 ports of ICC
		345	timestamp and FICS timeseal use threads to handle multiple input
		346	sources.
		347	</p>
		348
		349	<h2><a name="7">7. Signals</a></h2>
		350
		351	<p>Engines that run on Unix need to be concerned with two Unix
		352	signals: <tt>SIGTERM</tt> and <tt>SIGINT</tt>. This applies both to
		353	engines that run under xboard and (the unusual case of) engines that
		354	WinBoard remotely runs on a Unix host using the -firstHost or
		355	-secondHost feature. It does not apply to engines that run on
		356	Windows, because Windows does not have Unix-style signals.
		357	<font color=red>
		358	Beginning with version 2, you can now turn off the use of
		359	either or both
		360	signals. See the "feature" command in <a href="#6">section 9</a> below.
		361	</font>
		362	</p>
		363
		364	<p>First, when an engine is sent the "quit" command, it is also given
		365	a <tt>SIGTERM</tt> signal shortly afterward to make sure it goes away.
		366	If your engine reliably responds to "quit", and the signal causes
		367	problems for you, you should either ignore it by calling
		368	<tt>signal(SIGTERM, SIG_IGN)</tt> at the start of your program,
		369	or disable it with the "feature" command.</p>
		370
		371	<p>Second, xboard will send an interrupt signal (<tt>SIGINT</tt>) at
		372	certain times when it believes the engine may not be listening to user
		373	input (thinking or pondering). WinBoard currently does this only when
		374	the engine is running remotely using the -firstHost or -secondHost
		375	feature, not when it is running locally. You probably need to know
		376	only enough about this grungy feature to keep it from getting in your
		377	way.
		378	</p>
		379
		380	<p>
		381	The <tt>SIGINT</tt>s are basically tailored to the needs of GNU Chess 4
		382	on systems where its input polling code is broken or disabled.
		383	Because they work in a rather peculiar way, it is recommended that you
		384	either ignore <tt>SIGINT</tt> by having your engine call
		385	<tt>signal(SIGINT, SIG_IGN)</tt>, or disable it with the "feature"
		386	command.</p>
		387
		388	<p>
		389	Here are details for the curious. If xboard needs to send a command
		390	when it is the chess engine's move (such as before the "?" command),
		391	it sends a <tt>SIGINT</tt> first. If xboard needs to send commands when it is
		392	not the chess engine's move, but the chess engine may be pondering
		393	(thinking on its opponent's time) or analyzing (analysis or analyze
		394	file mode), xboard sends a <tt>SIGINT</tt> before the first such command only.
		395	Another <tt>SIGINT</tt> is not sent until another move is made, even if xboard
		396	issues more commands. This behavior is necessary for GNU Chess 4. The
		397	first <tt>SIGINT</tt> stops it from pondering until the next move, but on some
		398	systems, GNU Chess 4 will die if it receives a <tt>SIGINT</tt> when not
		399	actually thinking or pondering.
		400	</p>
		401
		402	<p>
		403	There are two reasons why WinBoard does not send the Win32 equivalent
		404	of <tt>SIGINT</tt> (which is called <tt>CTRL_C_EVENT</tt>) to local
		405	engines. First, the Win32 GNU Chess 4 port does not need it. Second, I
		406	could not find a way to get it to work. Win32 seems to be designed
		407	under the assumption that only console applications, not windowed
		408	applications, would ever want to send a <tt>CTRL_C_EVENT</tt>.
		409	</p>
		410
		411	<h2><a name="8">8. Commands from xboard to the engine</a></h2>
		412
		413	<p>
		414	All commands from xboard to the engine end with a newline (\n), even
		415	where that is not explicitly stated. All your output to xboard must
		416	be in complete lines; any form of prompt or partial line will cause
		417	problems.
		418	</p>
		419
		420	<p>
		421	At the beginning of each game, xboard sends an initialization string.
		422	This is currently "new\nrandom\n" unless the user changes it with the
		423	initString or secondInitString option.
		424	</p>
		425
		426	<p>
		427	xboard normally reuses the same chess engine process for multiple
		428	games. At the end of a game, xboard will send the "force" command
		429	(see below) to make sure your engine stops thinking about the current
		430	position. It will later send the initString again to start a new
		431	game. If your engine can't play multiple games, you can disable reuse
		432	<font color=red>
		433	either with the "feature" command (beginning in protocol version
		434	2; see below) or
		435	</font>
		436	with xboard's -xreuse (or -xreuse2) command line
		437	option. xboard will then ask the process to quit after each game and
		438	start a new process for the next game.
		439	</p>
		440
		441	<dl>
		442	<dt><strong>xboard</strong>
		443	<dd>This command will be sent once immediately after your engine
		444	process is started. You can use it to put your engine into "xboard
		445	mode" if that is needed. If your engine prints a prompt to ask for
		446	user input, you must turn off the prompt and output a newline when the
		447	"xboard" command comes in.
		448	<p>
		449
		450	<dt><font color=red><strong>protover N</strong></font>
		451	<dd><font color=red>
		452	Beginning in protocol version 2 (in which N=2), this command will
		453	be sent immediately after the "xboard" command. If you receive some
		454	other command immediately after "xboard" (such as "new"), you can
		455	assume that protocol version 1 is in use. The "protover" command is
		456	the only new command that xboard always sends in version 2. All other
		457	new commands to the engine are sent only if the engine first enables
		458	them with the "feature" command. Protocol versions will always be
		459	simple integers so that they can easily be compared.
		460
		461	<p>Your engine should reply to the protover command by sending the
		462	"feature" command (see below) with the list of non-default feature
		463	settings that you require, if any.
		464
		465	<p>Your engine should never refuse to run due to receiving a higher
		466	protocol version number than it is expecting! New protocol versions
		467	will always be compatible with older ones by default; the larger
		468	version number is simply a hint that additional "feature" command
		469	options added in later protocol versions may be accepted.
		470	</font>
		471	<p>
		472
		473	<dt><font color=red><strong>accepted</strong></font>
		474	<dt><font color=red><strong>rejected</strong></font>
		475	<dd><font color=red>
		476	These commands may be sent to your engine in reply to the "feature"
		477	command; see its documentation below.
		478	</font>
		479	<p>
		480
		481	<dt><strong>new</strong>
		482	<dd>Reset the board to the standard chess starting position. Set
		483	White on move. Leave force mode and set the engine to play Black.
		484	Associate the engine's clock with Black and the opponent's clock with
		485	White. Reset clocks and time controls to the start of a new game.
		486	Use wall clock for time measurement.
		487	Stop clocks. Do not ponder on this move, even if pondering is on.
		488	Remove any search depth limit previously set by the sd command.
		489	<p>
		490
		491	<dt><strong>variant VARNAME</strong>
		492	<dd>If the game is not standard chess, but a variant, this command is
		493	sent after "new" and before the first move or "edit" command. Currently
		494	defined variant names are:
		495
		496	<table>
		497	<tr align="left"><th>wildcastle<td>Shuffle chess where king can castle from d file
		498	<tr align="left"><th>nocastle<td>Shuffle chess with no castling at all
		499	<tr align="left"><th>fischerandom<td>Fischer Random
		500	<tr align="left"><th>bughouse<td>Bughouse, ICC/FICS rules
		501	<tr align="left"><th>crazyhouse<td>Crazyhouse, ICC/FICS rules
		502	<tr align="left"><th>losers<td>Win by losing all pieces or getting mated (ICC)
		503	<tr align="left"><th>suicide<td>Win by losing all pieces including king,
		504	or by having fewer pieces when one player has no legal moves (FICS)
		505	<tr align="left"><th><font color=red>giveaway</font>
		506	<td><font color=red>Win by losing all pieces including king,
		507	or by having no legal moves (ICC)</font>
		508	<tr align="left"><th>twokings<td>Weird ICC wild 9
		509	<tr align="left"><th>kriegspiel<td>Kriegspiel (engines not supported)
		510	<tr align="left"><th>atomic<td>Atomic
		511	<tr align="left"><th>3check<td>Win by giving check 3 times
		512	<tr align="left"><th><font color=green>xiangqi</font>
		513	<td><font color=green>Chinese Chess (9x10 board)</font>
		514	<tr align="left"><th><font color=green>shogi</font>
		515	<td><font color=green>Japanese Chess (9x9 bord)</font>
		516	<tr align="left"><th><font color=green>capablanca</font>
		517	<td><font color=green>Capablanca Chess (10x8 board, with Archbishop and Chancellor)</font>
		518	<tr align="left"><th><font color=green>gothic</font>
		519	<td><font color=green>Gothic Chess (10x8 board, same with better opening setup)</font>
		520	<tr align="left"><th><font color=green>falcon</font>
		521	<td><font color=green>Falcon Chess (10x8 board, with two Falcon pieces)</font>
		522	<tr align="left"><th><font color=green>shatranj</font>
		523	<td><font color=green>ancient Arabic Chess, with Elephants and General in stead of B and Q</font>
		524	<tr align="left"><th><font color=green>courier</font>
		525	<td><font color=green>Courier Chess (12x8 board, a medieval precursor of modern Chess</font>
		526	<tr align="left"><th><font color=green>knightmate</font>
		527	<td><font color=green>King moves as Knight and vice versa</font>
		528	<tr align="left"><th><font color=green>berolina</font><td>
		529	<font color=green>Pawns capture straight ahead, and move diagonally</font>
		530	<tr align="left"><th><font color=green>janus</font><td>
		531	<font color=green>Janus Chess (10x8, with two Archbishops)</font>
		532	<tr align="left"><th><font color=green>caparandom</font>
		533	<td><font color=green>shuffle variant like FRC (10x8 board)</font>
		534	<tr align="left"><th><font color=green>cylinder</font>
		535	<td><font color=green>Pieces wrap around between side edges, like board is a cylinder</font>
		536	<tr align="left"><th><font color=blue>super</font>
		537	<td><font color=blue>Superchess: a shuffle variant with 4 fairy pieces on 8x8 board</font>
		538	<tr align="left"><th><font color=blue>great</font>
		539	<td><font color=blue>Great Shatranj: sliders are replaced by corresponding short-range pieces on a 10x8 board</font>
		540	<tr align="left"><th>unknown<td>Unknown variant (not supported)
		541	</table>
		542	<p>
		543
		544	<dt><strong>quit</strong>
		545	<dd>The chess engine should immediately exit. This command is used
		546	when xboard is itself exiting, and also between games if the -xreuse
		547	command line option is given (or -xreuse2 for the second engine).
		548	See also <a href="#7">Signals</a> above.
		549	<p>
		550
		551	<dt><strong>random</strong>
		552	<dd>This command is specific to GNU Chess 4. You can either ignore it
		553	completely (that is, treat it as a no-op) or implement it as GNU Chess
		554	does. The command toggles "random" mode (that is, it sets random =
		555	!random). In random mode, the engine adds a small random value to its
		556	evaluation function to vary its play. The "new" command sets random
		557	mode off.
		558	<p>
		559
		560	<dt><strong>force</strong>
		561	<dd>Set the engine to play neither color ("force mode"). Stop clocks.
		562	The engine should check that moves received in force mode are legal
		563	and made in the proper turn, but should not think, ponder, or make
		564	moves of its own.
		565	<p>
		566
		567	<dt><strong>go</strong>
		568	<dd>Leave force mode and set the engine to play the color that is on
		569	move. Associate the engine's clock with the color that is on move,
		570	the opponent's clock with the color that is not on move. Start the engine's
		571	clock. Start thinking and eventually make a move.
		572	<p>
		573
		574	<dt><font color=red><strong>playother</strong></font>
		575	<dd>
		576	<font color=red>
		577	(This command is new in protocol version 2. It is not
		578	sent unless you enable it with the feature command.)
		579	Leave force mode and set the engine to play the color that is <i>not</i> on
		580	move. Associate the opponent's clock with the color that is on move,
		581	the engine's clock with the color that is not on move. Start the opponent's
		582	clock. If pondering is enabled, the engine should begin pondering.
		583	If the engine later receives a move, it should start thinking and eventually
		584	reply.
		585	</font>
		586	<p>
		587
		588	<dt><strong>white</strong>
		589	<dd>
		590	<font color=red>
		591	(This command is obsolete as of protocol version 2, but is still
		592	sent in some situations to accommodate older engines unless you disable it
		593	with the feature command.)
		594	</font>
		595	Set White on move. Set the engine to play Black. Stop clocks.
		596	<p>
		597
		598	<dt><strong>black</strong>
		599	<dd>
		600	<font color=red>
		601	(This command is obsolete as of protocol version 2, but is still
		602	sent in some situations to accommodate older engines unless you disable it
		603	with the feature command.)
		604	</font>
		605	Set Black on move. Set the engine to play White. Stop clocks.
		606	<p>
		607
		608	<dt><strong>level MPS BASE INC</strong>
		609	<dd>Set time controls. See the <a href="#11">Time Control</a> section below.
		610	<p>
		611
		612	<dt><strong>st TIME</strong>
		613	<dd>Set time controls. See the <a href="#11">Time Control</a> section
		614	below.
		615	<p>
		616
		617	<dt><strong>sd DEPTH</strong>
		618	<dd>The engine should limit its thinking to DEPTH ply.
		619	<font color=green>The commands "level" or "st" and "sd" can be used together in an orthogonal way.
		620	If both are issued, the engine should observe both limitations:</font>
		621	In the protocol, the "sd" command isn't a time control. It doesn't
		622	say that your engine has unlimited time but must search to exactly the
		623	given depth. It says that you should pay attention to the time
		624	control as normal, but cut off the search at the specified depth even
		625	if you have time to search deeper. If you don't have time to search
		626	to the specified depth, given your normal time management algorithm,
		627	then you will want to stop sooner than the given depth.
		628	<p>
		629	The "new" command should set the search depth back to unlimited. This
		630	is already stated in the spec. The "level" command should not affect
		631	the search depth. As it happens, xboard/WinBoard currently always
		632	sends sd (if needed) right after level, but that isn't part of the
		633	spec.
		634	<p>
		635
		636	<dt><font color=green><strong>nps NODE_RATE</strong></font>
		637	<dd><font color=green>The engine should not use wall-clock time to make its timing decisions,
		638	but an own internal time measure based on the number of nodes it has searched
		639	(and will report as "thinking output", see <a href="#10">section 10</a>),
		640	converted to seconds through dividing by the given NODE_RATE.
		641	Example: after receiving the commands "st 8" and "nps 10000",
		642	the engine should never use more that 80,000 nodes in the search for any move.
		643	In this mode, the engine should report user CPU time used (in its thinking output),
		644	rather than wall-clock time.
		645	This even holds if NODE_RATE is given as 0,
		646	but in that case it should also use the user CPU time for its timing decisions.
		647	The effect of an "nps" command should persist until the next "new" command.
		648	</font>
		649	<p>
		650
		651	<dt><strong>time N</strong>
		652	<dd>Set a clock that always belongs to the engine. N is a number in
		653	centiseconds (units of 1/100 second). Even if the engine changes to
		654	playing the opposite color, this clock remains with the engine.
		655	<p>
		656
		657	<dt><strong>otim N</strong>
		658
		659	<dd>Set a clock that always belongs to the opponent. N is a number in
		660	centiseconds (units of 1/100 second). Even if the opponent changes to
		661	playing the opposite color, this clock remains with the opponent.
		662	<p>
		663	If needed for purposes of board display in force mode (where the
		664	engine is not participating in the game) the time clock should be
		665	associated with the last color that the engine was set to play, the
		666	otim clock with the opposite color.
		667	</p>
		668	<p>
		669	<font color=green>This business of "clocks remaining with the engine" is apparently so ambiguous
		670	that many engines implement it wrong.
		671	The clocks in fact always remain with the color.
		672	Which clock reading is relayed with "time", and which by "otim", is determined by which side the engine plays.
		673	Note that the way the clocks operate and receive extra time (in accordance with the selected time control)
		674	is not affected in any way by which moves are made by the engine, which by the opponent, and which were forced.
		675	</font>
		676	</p>
		677	<p>
		678	<font color=red>
		679	Beginning in protocol version 2, if you can't handle the time and
		680	otim commands, you can use the "feature" command to disable them; see
		681	below.
		682	</font>
		683	The following techniques from older protocol versions also
		684	work: You can ignore the time and otim commands (that is, treat them
		685	as no-ops), or send back "Error (unknown command): time" the first
		686	time you see "time".
		687	</p>
		688
		689	<dt><strong>MOVE</strong>
		690	<dd>See below for the syntax of moves. If the move is illegal, print
		691	an error message; see the section "<a href="#9">Commands from the engine to
		692	xboard</a>". If the move is legal and in turn, make it. If not in force
		693	mode, stop the opponent's clock, start the engine's clock, start
		694	thinking, and eventually make a move.
		695	<p>
		696	When xboard sends your engine a move, it normally sends coordinate
		697	algebraic notation. Examples:
		698	<p>
		699	<table>
		700	<tr align="left"><td>Normal moves:<td>e2e4
		701	<tr align="left"><td>Pawn promotion:<td>e7e8q
		702	<tr align="left"><td>Castling:<td>e1g1, e1c1, e8g8, e8c8
		703	<tr align="left"><td>Bughouse/crazyhouse drop:<td>P@h3
		704	<tr align="left"><td>ICS Wild 0/1 castling:<td>d1f1, d1b1, d8f8, d8b8
		705	<tr align="left"><td>FischerRandom castling:<td>O-O, O-O-O (oh, not zero)
		706	</table>
		707
		708	<p>
		709	<font color=green>
		710	Note that on boards with more than 9 ranks, counting of the ranks starts at 0.
		711	</font>
		712	</p>
		713	<p>
		714	<font color=red>
		715	Beginning in protocol version 2, you can use the feature command
		716	to select SAN (standard algebraic notation) instead; for example, e4,
		717	Nf3, exd5, Bxf7+, Qxf7#, e8=Q, O-O, or P@h3. Note that the last form,
		718	P@h3, is a extension to the PGN standard's definition of SAN, which does
		719	not support bughouse or crazyhouse.
		720	</font>
		721	</p>
		722
		723	<p>
		724	xboard doesn't reliably detect illegal moves, because it does not keep
		725	track of castling unavailability due to king or rook moves, or en
		726	passant availability. If xboard sends an illegal move, send back an
		727	error message so that xboard can retract it and inform the user; see
		728	the section "<a href="#9">Commands from the engine to xboard</a>".
		729	</p>
		730
		731	<dt><font color=red><strong>usermove MOVE</strong></font>
		732	<dd><font color=red>
		733	By default, moves are sent to the engine without a command name;
		734	the notation is just sent as a line by itself.
		735	Beginning in protocol version 2, you can use the feature command
		736	to cause the command name "usermove" to be sent before the move.
		737	Example: "usermove e2e4".
		738	</font>
		739	</p>
		740
		741	<dt><strong>?</strong>
		742	<dd>Move now. If your engine is thinking, it should move immediately;
		743	otherwise, the command should be ignored (treated as a no-op). It
		744	is permissible for your engine to always ignore the ? command. The
		745	only bad consequence is that xboard's Move Now menu command will do
		746	nothing.
		747	<p>
		748	It is also permissible for your engine to move immediately if it gets
		749	any command while thinking, as long as it processes the command right
		750	after moving, but it's preferable if you don't do this. For example,
		751	xboard may send post, nopost, easy, hard, force, quit,
		752	<font color=red>
		753	or other commands
		754	</font>
		755	while the engine is on move.
		756	</p>
		757
		758	<dt><font color=red><strong>ping N</strong></font>
		759	<dd>
		760	<font color=red>
		761	In this command, N is a decimal number. When you receive the command,
		762	reply by sending the string <strong>pong N</strong>, where N is the
		763	same number you received. Important: You must not reply to a "ping"
		764	command until you have finished executing all commands that you
		765	received before it. Pondering does not count; if you receive a ping
		766	while pondering, you should reply immediately and continue pondering.
		767	Because of the way xboard uses the ping command, if you implement the
		768	other commands in this protocol, you should never see a "ping" command
		769	when it is your move; however, if you do, you must not send the "pong"
		770	reply to xboard until after you send your move. For example, xboard
		771	may send "?" immediately followed by "ping". If you implement the "?"
		772	command, you will have moved by the time you see the subsequent ping
		773	command. Similarly, xboard may send a sequence like "force", "new",
		774	"ping". You must not send the pong response until after you have
		775	finished executing the "new" command and are ready for the new game to
		776	start.
		777
		778	<p>
		779	The ping command is new in protocol version 2 and will not be sent
		780	unless you enable it with the "feature" command. Its purpose is to
		781	allow several race conditions that could occur in previous versions of
		782	the protocol to be fixed, so it is highly recommended that you
		783	implement it. It is especially important in simple engines that do
		784	not ponder and do not poll for input while thinking, but it is needed in all
		785	engines.
		786	</p>
		787	</font>
		788
		789	<dt><strong>draw</strong>
		790	<dd>The engine's opponent offers the engine a draw. To accept the
		791	draw, send "offer draw". To decline, ignore the offer (that is, send
		792	nothing). If you're playing on ICS, it's possible for the draw offer
		793	to have been withdrawn by the time you accept it, so don't assume the
		794	game is over because you accept a draw offer. Continue playing until
		795	xboard tells you the game is over. See also "offer draw" below.
		796	<p>
		797
		798	<dt><strong>result RESULT {COMMENT}</strong>
		799	<dd>After the end of each game, xboard will send you a result command.
		800	You can use this command to trigger learning. RESULT is either 1-0,
		801	0-1, 1/2-1/2, or *, indicating whether white won, black won, the game
		802	was a draw, or the game was unfinished. The COMMENT string is purely
		803	a human-readable comment; its content is unspecified and subject to
		804	change. In ICS mode, it is passed through from ICS uninterpreted.
		805	Example: <pre>result 1-0 {White mates}</pre>
		806	<p>
		807	Here are some notes on interpreting the "result" command. Some apply
		808	only to playing on ICS ("Zippy" mode).
		809	</p>
		810
		811	<p>
		812	If you won but did not just play a mate, your opponent must have
		813	resigned or forfeited. If you lost but were not just mated, you
		814	probably forfeited on time, or perhaps the operator resigned manually.
		815	If there was a draw for some nonobvious reason, perhaps your opponent
		816	called your flag when he had insufficient mating material (or vice
		817	versa), or perhaps the operator agreed to a draw manually.
		818	</p>
		819
		820	<p>
		821	You will get a result command even if you already know the game ended
		822	-- for example, after you just checkmated your opponent. In fact, if
		823	you send the "RESULT {COMMENT}" command (discussed below), you will
		824	simply get the same thing fed back to you with "result" tacked in
		825	front. You might not always get a "result *" command, however. In
		826	particular, you won't get one in local chess engine mode when the user
		827	stops playing by selecting Reset, Edit Game, Exit or the like.
		828	</p>
		829
		830	<dt><font color=red><strong>setboard FEN</strong></font>
		831	<dd><font color=red>
		832	The setboard command is the new way to set up positions, beginning
		833	in protocol version 2. It is not used unless it has been selected
		834	with the feature command. Here FEN is a position in Forsythe-Edwards
		835	Notation, as defined in the PGN standard.</font>
		836	<font color=green>Note that this PGN standard referred to here
		837	only applies to normal Chess;
		838	Obviously in variants that cannot be described by a FEN for normal Chess,
		839	e.g. because the board is not 8x8, other pieces then PNBRQK participate,
		840	there are holdings that need to be specified, etc.,
		841	xboard will use a FEN format that is standard or suitable for that varant.
		842	In particular, in FRC or CRC, WinBoard will use Shredder-FEN or X-FEN standard,
		843	i.e. it can use the rook-file indicator letter to represent a castling right
		844	(like HAha) whenever it wants, but if it uses KQkq, this will always refer
		845	to the outermost rook on the given side.</font>
		846	<font color=red>
		847
		848	<p><i>Illegal positions:</i> Note that either setboard or edit can
		849	be used to send an illegal position to the engine. The user can
		850	create any position with xboard's Edit Position command (even, say,
		851	an empty board, or a board with 64 white kings and no black ones).
		852	If your engine receives a position that it considers illegal,
		853	I suggest that you send the response "tellusererror Illegal position",
		854	and then respond to any attempted move with "Illegal move" until
		855	the next new, edit, or setboard command.</p>
		856	</font>
		857	<p>
		858
		859	<dt><strong>edit</strong>
		860	<dd>
		861	<font color=red>
		862	The edit command is the old way to set up positions. For compatibility
		863	with old engines, it is still used by default, but new engines may prefer
		864	to use the feature command (see below) to cause xboard to use setboard instead.
		865	</font>
		866	The edit command puts the chess engine into a special mode, where
		867	it accepts the following subcommands:
		868	<table>
		869	<tr align="left"><th>c<td>change current piece color, initially white
		870	<tr align="left"><th>Pa4 (for example)<td>place pawn of current color on a4
		871	<tr align="left"><th>xa4 (for example)<td>empty the square a4 (not used by xboard)
		872	<tr align="left"><th>#<td>clear board
		873	<tr align="left"><th>.<td>leave edit mode
		874	</table>
		875	<font color=red>
		876	See the Idioms section below for additional subcommands used in
		877	ChessBase's implementation of the protocol.
		878	</font>
		879
		880	<p>The edit command does not change the side to move. To set up a
		881	black-on-move position, xboard uses the following command sequence:
		882	</p>
		883	<pre>
		884	new
		885	force
		886	a2a3
		887	edit
		888	<edit commands>
		889	.
		890	</pre>
		891
		892	<p>
		893	This sequence is used to avoid the "black" command, which is now
		894	considered obsolete and which many engines never did implement as
		895	specified in this document.
		896	</p>
		897
		898	<p>
		899	After an edit command is complete, if a king and a rook are on their
		900	home squares, castling is assumed to be available to them. En passant
		901	capture is assumed to be illegal on the current move regardless of the
		902	positions of the pawns. The clock for the 50 move rule starts at
		903	zero, and for purposes of the draw by repetition rule, no prior
		904	positions are deemed to have occurred.
		905	<font color=green>
		906	In FRC or CRC, any rook and king put on the back rank should be considered to
		907	have castling rights, even if it later becomes apparent that they cannot be both in the
		908	initial position, because the position just set up is asymmetric.
		909	It is upto WinBoard to find work-around in cases where this is not desired,
		910	similar to the "black kludge" shown above, by setting up an earlier position,
		911	and then do a move to destroy castling rights or create e.p. rights.
		912	(Don't bet your life on it...)
		913	</font>
		914	</p>
		915
		916	<dt><strong>hint</strong>
		917	<dd>If the user asks for a hint, xboard sends your engine the command
		918	"hint". Your engine should respond with "Hint: xxx", where xxx is a
		919	suggested move. If there is no move to suggest, you can ignore the
		920	hint command (that is, treat it as a no-op).
		921	<p>
		922
		923	<dt><strong>bk</strong>
		924	<dd>If the user selects "Book" from the xboard menu, xboard will send
		925	your engine the command "bk". You can send any text you like as the
		926	response, as long as each line begins with a blank space or tab (\t)
		927	character, and you send an empty line at the end. The text pops up in
		928	a modal information dialog.
		929	<p>
		930
		931	<dt><strong>undo</strong>
		932	<dd>If the user asks to back up one move, xboard will send you the
		933	"undo" command. xboard will not send this command without putting you
		934	in "force" mode first, so you don't have to worry about what should
		935	happen if the user asks to undo a move your engine made. (GNU Chess 4
		936	actually switches to playing the opposite color in this case.)
		937	<p>
		938
		939	<dt><strong>remove</strong>
		940	<dd>If the user asks to retract a move, xboard will send you the
		941	"remove" command. It sends this command only when the user is on
		942	move. Your engine should undo the last two moves (one for each
		943	player) and continue playing the same color.
		944	<p>
		945
		946	<dt><strong>hard</strong>
		947	<dd>Turn on pondering (thinking on the opponent's time, also known as
		948	"permanent brain"). xboard will not make any assumption about what
		949	your default is for pondering or whether "new" affects this setting.
		950	<p>
		951
		952	<dt><strong>easy</strong>
		953	<dd>Turn off pondering.
		954	<p>
		955
		956	<dt><strong>post</strong>
		957	<dd>Turn on thinking/pondering output.
		958	See <a href="#10">Thinking Output</a> section.
		959	<p>
		960
		961	<dt><strong>nopost</strong>
		962	<dd>Turn off thinking/pondering output.
		963	<p>
		964
		965	<dt><strong>analyze</strong>
		966	<dd>Enter analyze mode. See <a href="#12">Analyze Mode</a> section.
		967	<p>
		968
		969	<dt><strong>name X</strong> <dd>This command informs the engine of its
		970	opponent's name. When the engine is playing on a chess server, xboard
		971	obtains the opponent's name from the server.
		972	<font color=red>
		973	When the engine is
		974	playing locally against a human user, xboard obtains the user's login
		975	name from the local operating system. When the engine is playing
		976	locally against another engine, xboard uses either the other engine's
		977	filename or the name that the other engine supplied in the myname
		978	option to the feature command. By default, xboard uses the name
		979	command only when the engine is playing on a chess server. Beginning
		980	in protocol version 2, you can change this with the name option to the
		981	feature command; see below.
		982	</font>
		983	<p>
		984
		985	<dt><strong>rating</strong>
		986	<dd>In ICS mode, xboard obtains the ICS opponent's rating from the
		987	"Creating:" message that appears before each game. (This message may
		988	not appear on servers using outdated versions of the FICS code.) In
		989	Zippy mode, it sends these ratings on to the chess engine using the
		990	"rating" command. The chess engine's own rating comes first, and if
		991	either opponent is not rated, his rating is given as 0.
		992	<font color=red>
		993	In the future this command may also be used in other modes, if ratings
		994	are known.
		995	</font>
		996	Example: <pre>rating 2600 1500</pre>
		997	<p>
		998
		999	<dt><font color=red><strong>ics HOSTNAME</strong></font>
		1000	<dd><font color=red>
		1001	If HOSTNAME is "-", the engine is playing against a local
		1002	opponent; otherwise, the engine is playing on an Internet Chess Server
		1003	(ICS) with the given hostname. This command is new in protocol
		1004	version 2 and is not sent unless the engine has enabled it with
		1005	the "feature" command. Example: "ics freechess.org"
		1006	</font>
		1007	<p>
		1008
		1009	<dt><strong>computer</strong>
		1010	<dd>The opponent is also a computer chess engine. Some engines alter
		1011	their playing style when they receive this command.
		1012	<p>
		1013
		1014	<dt><font color=red><strong>pause</strong></font>
		1015	<dt><font color=red><strong>resume</strong></font>
		1016	<dd><font color=red>(These commands are new in protocol
		1017	version 2 and will not be sent unless feature pause=1 is set. At
		1018	this writing, xboard actually does not use the commands at all, but it
		1019	or other interfaces may use them in the future.)
		1020	The "pause" command puts the engine into a special state where it
		1021	does not think, ponder, or otherwise consume significant CPU time.
		1022	The current thinking or pondering (if any) is suspended and both
		1023	player's clocks are stopped. The only command that the interface may
		1024	send to the engine while it is in the paused state is "resume". The
		1025	paused thinking or pondering (if any) resumes from exactly where it
		1026	left off, and the clock of the player on move resumes running from
		1027	where it stopped.
		1028	</font>
		1029	<p>
		1030
		1031	<dt><font color=blue><strong>memory N</strong></font>
		1032	<dd><font color=blue>
		1033	This command informs the engine on how much memory it is allowed to use maximally, in MegaBytes.
		1034	On receipt of this command, the engine should adapt the size of its hash tables accordingly.
		1035	This command does only fix the total memory use,
		1036	the engine has to decide for itself
		1037	(or be configured by the user by other means)
		1038	how to divide up the available memory between the various tables it wants to use
		1039	(e.g. main hash, pawn hash, tablebase cache, bitbases).
		1040	This command will only be sent to engines that have requested it through the memory feature,
		1041	and only at the start of a game,
		1042	as the first of the commands to relay engine option settings just before each "new" command.
		1043	</font>
		1044	<p>
		1045
		1046	<dt><font color=blue><strong>cores N</strong></font>
		1047	<dd><font color=blue>
		1048	This command informs the engine on how many CPU cores it is allowed to use maximally.
		1049	This could be interpreted as the number of search threads for SMP engines.
		1050	(Threads that do not consume significant amounts of CPU time, like I/O threads, need not be included in the count.)
		1051	This command will only be sent to engines that have requested it through the smp feature.
		1052	The engine should be able to respond to the "cores" command any time during a game,
		1053	but it is allowed to finish a search in progress before procesing the command.
		1054	(Obeying the command should take priority over finishing a ponder search, though.)
		1055	In any case it will be sent at the start of every game
		1056	as the last command to relay engine option settings before the "new" command.
		1057	</font>
		1058	<p>
		1059
		1060	<dt><font color=blue><strong>egtpath TYPE PATH</strong></font>
		1061	<dd><font color=blue>
		1062	This command informs the engine in which directory (given by the PATH argument)
		1063	it can find end-game tables of the specified TYPE.
		1064	The TYPE argument can be any character string which does not contain spaces.
		1065	Currently <strong>nalimov</strong> and <strong>scorpio</strong> are defined types,
		1066	for Nalimov tablebases and Scorpio bitbases, respectively,
		1067	but future developers of other formats are free to define their own format names.
		1068	The GUI simply matches the TYPE names the engine says it supports
		1069	with those that the user supplied when configuring xboard.
		1070	For every match, it sends a separate "y" command.
		1071	The PATH argument would normally (for Nalimov) be the pathname of the directory the EGT files are in,
		1072	but could also be the name of a file, or in fact anything the particular EGT type requires.
		1073	It is upto the developer of the EGT format to specify the syntax of this parameter.
		1074	This command will only be sent to engines that have told the GUI they support EGTs of the given TYPE
		1075	through the egt feature.
		1076	It will be sent at the start of each game, before the "new" command.
		1077	</font>
		1078	<p>
		1079
		1080	<dt><font color=blue><strong>option NAME[=VALUE]</strong></font>
		1081	<dd><font color=blue>
		1082	This command changes the setting of the option NAME defined by the engine
		1083	(through an earlier feature command)
		1084	to the given VALUE.
		1085	XBoard will in general have no idea what the option means,
		1086	and will send the command only when a user changes the value of this option through a menu,
		1087	or at startup of the engine
		1088	(before the first 'cores' command or, if that is not sent, the first 'new' command)
		1089	in reaction to command-line options.
		1090	The NAME echoes back to the engine the string that was identified as an option NAME
		1091	in the feature command defining the option.
		1092	The VALUE is of the type (numeric or text or absent) that was implied by the option type
		1093	specified in this feature command,
		1094	i.e. with 'spin' and 'check' options VALUE will be a decimal integer (in the latter case 0 or 1),
		1095	with 'combo' and 'string' options VALUE will be a text string,
		1096	and with 'button' and 'save' options no VALUE will be sent at all.
		1097	</font>
		1098	</dl>
		1099
		1100	<h3>Bughouse commands:</h3>
		1101
		1102	<p>
		1103	xboard now supports bughouse engines when in Zippy mode. See
		1104	<a href="http://www.tim-mann.org/xboard/zippy.README"
		1105	>zippy.README</a> for information on Zippy mode and how to turn on the
		1106	bughouse support. The bughouse move format is given above. xboard
		1107	sends the following additional commands to the engine when in bughouse
		1108	mode.
		1109	Commands to inform your engine of the partner's game state may
		1110	be added in the future.
		1111	</p>
		1112
		1113	<dl>
		1114	<dt><strong>partner <player></strong>
		1115	<dd><player> is now your partner for future games. Example: <pre>partner mann</pre>
		1116	<p>
		1117
		1118	<dt><strong>partner</strong>
		1119	<dd>Meaning: You no longer have a partner.
		1120	<p>
		1121
		1122	<dt><strong>ptell <text></strong>
		1123	<dd>Your partner told you <text>, either with a ptell or an ordinary tell.
		1124	<p>
		1125
		1126	<dt><strong>holding [<white>] [<black>]</strong>
		1127	<dd>White currently holds <white>; black currently holds <black>.
		1128	Example: <pre>holding [PPPRQ] []</pre>
		1129
		1130	<dt><strong>holding [<white>] [<black>] <color><piece></strong>
		1131	<dd>White currently holds <white>; black currently holds <black>, after
		1132	<color> acquired <piece>. Example: <pre>holding [PPPRQ] [R] BR</pre>
		1133	</dl>
		1134
		1135	<h2><a name="9">9. Commands from the engine to xboard</a></h2>
		1136
		1137	<p>
		1138	<font color=red>
		1139	In general, an engine should not send any output to xboard that is not
		1140	described in this document. As the protocol is extended, newer
		1141	versions of xboard may recognize additional strings as commands that
		1142	were previously not assigned a meaning.
		1143	</font>
		1144	</p>
		1145
		1146	<dl>
		1147	<dt><font color=red>
		1148	<strong>feature FEATURE1=VALUE1 FEATURE2=VALUE2 ...</strong>
		1149	</font>
		1150
		1151	<dd><font color=red>
		1152	Beginning with version 2, the protocol includes the "feature"
		1153	command, which lets your engine control certain optional protocol
		1154	features. Feature settings are written as FEATURE=VALUE, where
		1155	FEATURE is a name from the list below and VALUE is the value to be
		1156	assigned. Features can take string, integer, or boolean values; the
		1157	type of value is listed for each feature. String values are written
		1158	in double quotes (for example, <tt>feature myname="Miracle Chess
		1159	0.9"</tt>), integers are written in decimal, and boolean values are
		1160	written as 0 for false, 1 for true. Any number of features can be set
		1161	in one feature command, or multiple feature commands can be given.
		1162
		1163	<p>
		1164	Your engine should send one or more feature commands immediately after
		1165	receiving the "protover" command, since xboard needs to know the
		1166	values of some features before sending further commands to the engine.
		1167	Because engines that predate protocol version 2 do not send "feature",
		1168	xboard uses a timeout mechanism: when it first starts your engine, it
		1169	sends "xboard" and "protover N", then listens for feature commands for
		1170	two seconds before sending any other commands. To end this timeout
		1171	and avoid the wait, set the feature "done=1" at the end of your last
		1172	feature command. To increase the timeout, if needed, set the feature
		1173	"done=0" before your first feature command and "done=1" at the end.
		1174	If needed, it is okay for your engine to set done=0 soon as it starts,
		1175	even before it receives the xboard and protover commands. This can be
		1176	useful if your engine takes a long time to initialize itself. It
		1177	should be harmless even if you are talking to a (version 1) user
		1178	interface that does not understand the "feature" command, since such
		1179	interfaces generally ignore commands from the engine that they do not
		1180	understand.
		1181	</p>
		1182
		1183	<p>
		1184	The feature command is designed to let the protocol change without
		1185	breaking engines that were written for older protocol versions. When
		1186	a new feature is added to the protocol, its default value is always
		1187	chosen to be compatible with older versions of the protocol that did
		1188	not have the feature. Any feature that your engine does not set in a
		1189	"feature" command retains its default value, so as the protocol
		1190	changes, you do not have to change your engine to keep up with it
		1191	unless you want to take advantage of a new feature. Because some
		1192	features are improvements to the protocol, while others are meant to
		1193	cater to engines that do not implement all the protocol features, the
		1194	recommended setting for a feature is not always the same as the
		1195	default setting. The listing below gives both default and recommended
		1196	settings for most features.
		1197	</p>
		1198
		1199	<p>
		1200	You may want to code your engine so as to be able to work with
		1201	multiple versions of the engine protocol. Protocol version 1 does not
		1202	send the protover command and does not implement the feature command;
		1203	if you send a feature command in protocol version 1, it will have no
		1204	effect and there will be no response. In protocol version 2 or later,
		1205	each feature F that you set generates the response "accepted F" if the
		1206	feature is implemented, or "rejected F" if it is not. Thus an engine
		1207	author can request any feature without having to keep track of which
		1208	protocol version it was introduced in; you need only check whether the
		1209	feature is accepted or rejected. This mechanism also makes it
		1210	possible for a user interface author to implement a subset of a
		1211	protocol version by rejecting some features that are defined in that
		1212	version; however, you should realize that engine authors are likely to
		1213	code for xboard and may not be prepared to have a feature that they
		1214	depend on be rejected.
		1215	<font color=blue>If the GUI rejects an option feature because of the
		1216	syntax of the value, it should print the value string with the
		1217	"rejected" command, e.g. "rejected option nonsense" in response
		1218	to receiving feature option="nonsense".</font>
		1219	</p>
		1220
		1221	<p>
		1222	Here are the features that are currently defined.
		1223	</p>
		1224	</font>
		1225
		1226	<dl>
		1227	<dt><font color=red>
		1228	<strong>ping</strong> (boolean, default 0, recommended 1)
		1229	</font>
		1230	<dd><font color=red>
		1231	If ping=1, xboard may use the protocol's new "ping" command;
		1232	if ping=0, xboard will not use the command.
		1233	</font>
		1234
		1235	<dt><font color=red>
		1236	<strong>setboard</strong> (boolean, default 0, recommended 1)
		1237	</font>
		1238	<dd><font color=red>
		1239	If setboard=1, xboard will use the protocol's new "setboard" command
		1240	to set up positions; if setboard=0, it will use the older "edit" command.
		1241	</font>
		1242
		1243	<dt><font color=red>
		1244	<strong>playother</strong> (boolean, default 0, recommended 1)
		1245	</font>
		1246	<dd><font color=red>
		1247	If playother=1, xboard will use the protocol's new "playother" command
		1248	when appropriate; if playother=0, it will not use the command.
		1249	</font>
		1250
		1251	<dt><font color=red>
		1252	<strong>san</strong> (boolean, default 0)
		1253	</font>
		1254	<dd><font color=red>
		1255	If san=1, xboard will send moves to the engine in standard algebraic
		1256	notation (SAN); for example, Nf3. If san=0, xboard will send moves in
		1257	coordinate notation; for example, g1f3. See MOVE in
		1258	<a href="#8">section 8</a> above for more details of both kinds of notation.
		1259	</font>
		1260
		1261	<dt><font color=red>
		1262	<strong>usermove</strong> (boolean, default 0)
		1263	</font>
		1264	<dd><font color=red>
		1265	If usermove=1, xboard will send moves to the engine with the
		1266	command "usermove MOVE"; if usermove=0, xboard will send just the move,
		1267	with no command name.
		1268	</font>
		1269
		1270	<dt><font color=red>
		1271	<strong>time</strong> (boolean, default 1, recommended 1)
		1272	</font>
		1273	<dd><font color=red>
		1274	If time=1, xboard will send the "time" and "otim" commands to
		1275	update the engine's clocks; if time=0, it will not.
		1276	</font>
		1277
		1278	<dt><font color=red>
		1279	<strong>draw</strong> (boolean, default 1, recommended 1)
		1280	</font>
		1281	<dd><font color=red>
		1282	If draw=1, xboard will send the "draw" command if the engine's opponent
		1283	offers a draw; if draw=0, xboard will not inform the engine about
		1284	draw offers. Note that if draw=1, you may receive a draw offer while you
		1285	are on move; if this will cause you to move immediately, you should set
		1286	draw=0.
		1287	</font>
		1288
		1289	<dt><font color=red>
		1290	<strong>sigint</strong> (boolean, default 1)
		1291	</font>
		1292	<dd><font color=red>
		1293	If sigint=1, xboard may send SIGINT (the interrupt signal) to
		1294	the engine as <a href="#7">section 7</a> above; if sigint=0, it will
		1295	not.
		1296	</font>
		1297
		1298	<dt><font color=red>
		1299	<strong>sigterm</strong> (boolean, default 1)
		1300	</font>
		1301	<dd><font color=red>
		1302	If sigterm=1, xboard may send SIGTERM (the termination signal) to
		1303	the engine as <a href="#7">section 7</a> above; if sigterm=0, it will
		1304	not.
		1305	</font>
		1306
		1307	<dt><font color=red>
		1308	<strong>reuse</strong> (boolean, default 1, recommended 1)
		1309	</font>
		1310	<dd><font color=red>
		1311	If reuse=1, xboard may reuse your engine for multiple games. If
		1312	reuse=0 (or if the user has set the -xreuse option on xboard's command
		1313	line), xboard will kill the engine process after every game and start
		1314	a fresh process for the next game.
		1315	</font>
		1316
		1317	<dt><font color=red>
		1318	<strong>analyze</strong> (boolean, default 1, recommended 1)
		1319	</font>
		1320	<dd><font color=red>
		1321	If analyze=0, xboard will not try to use the "analyze" command; it
		1322	will pop up an error message if the user asks for analysis mode. If
		1323	analyze=1, xboard will try to use the command if the user asks for
		1324	analysis mode.
		1325	</font>
		1326
		1327	<dt><font color=red>
		1328	<strong>myname</strong> (string, default determined from engine filename)
		1329	</font>
		1330	<dd><font color=red>
		1331	This feature lets you set the name that xboard will use for your
		1332	engine in window banners, in the PGN tags of saved game files, and when
		1333	sending the "name" command to another engine.
		1334	</font>
		1335
		1336	<dt><font color=red>
		1337	<strong>variants</strong> (string, see text below)
		1338	</font>
		1339	<dd><font color=red>
		1340	This feature indicates which chess variants your engine accepts.
		1341	It should be a comma-separated list of variant names. See the table
		1342	under the "variant" command in <a href="#8">section 8</a> above. If
		1343	you do not set this feature, xboard will assume by default that your
		1344	engine supports all variants. (However, the -zippyVariants
		1345	command-line option still limits which variants will be accepted in
		1346	Zippy mode.) It is recommended that you set this feature to the
		1347	correct value for your engine (just "normal" in most cases) rather
		1348	than leaving the default in place, so that the user will get an
		1349	appropriate error message if he tries to play a variant that your
		1350	engine does not support.</font>
		1351	<br>
		1352	<font color=green>If your engine can play variants on a deviating board size,
		1353	like capablanca on an 8x8 board, or capablanca crazyhouse,
		1354	it can list them amongst the variants with a prefix spcifying board size plus
		1355	holdings size, like 8x8+0_capablanca or 10x8+7_capablanca.
		1356	If it is capable of playing any variant with an arbitrary board size,
		1357	it should list "boardsize" as one of the variants.
		1358	If there is a maximum to the board size, this can be prefixed,
		1359	e.g. "12x10+0_boardsize".
		1360	</font>
		1361
		1362	<dt><font color=red>
		1363	<strong>colors</strong> (boolean, default 1, recommended 0)
		1364	</font>
		1365	<dd><font color=red>
		1366	If colors=1, xboard uses the obsolete "white" and "black"
		1367	commands in a stylized way that works with most older chess engines
		1368	that require the commands. See the "<a href="#13">Idioms</a>" section
		1369	below for details. If colors=0, xboard does not use the "white" and
		1370	"black" commands at all.
		1371	</font>
		1372
		1373	<dt><font color=red>
		1374	<strong>ics</strong> (boolean, default 0)
		1375	</font>
		1376	<dd><font color=red>
		1377	If ics=1, xboard will use the protocol's new "ics" command
		1378	to inform the engine of whether or not it is playing on a chess server;
		1379	if ics=0, it will not.
		1380	</font>
		1381
		1382	<dt><font color=red>
		1383	<strong>name</strong> (boolean, see text below)
		1384	</font>
		1385	<dd><font color=red>
		1386	If name=1, xboard will use the protocol's "name" command
		1387	to inform the engine of the opponent's name; if name=0, it will not.
		1388	By default, name=1 if the engine is playing on a chess server; name=0 if not.
		1389	</font>
		1390
		1391	<dt><font color=red>
		1392	<strong>pause</strong> (boolean, default 0)
		1393	</font>
		1394	<dd><font color=red>
		1395	If pause=1, xboard may use the protocol's new "pause" command;
		1396	if pause=0, xboard assumes that the engine does not support this command.
		1397	</font>
		1398
		1399	<dt><font color=green>
		1400	<strong>nps</strong> (boolean, default ?)
		1401	</font>
		1402	<dd><font color=green>
		1403	If nps=1, it means the engine supports the nps command.
		1404	If nps=0, it means the engine does not support it, and WinBoard should refrain from sending it.
		1405	Default is that WinBoard sends it, in an attempt to try out if the engine understand it.
		1406	The engine should properly respond with "Error (unkown command): nps" if it does not implement it,
		1407	(as any protocol version pre-scribes),
		1408	or WinBoard might assume that the engine did understand the command.
		1409	In that case the use of different time standards that ensues could lead to time forfeits for the engine.
		1410	</font>
		1411
		1412	<dt><font color=green>
		1413	<strong>debug</strong> (boolean, default 0)
		1414	</font>
		1415	<dd><font color=green>
		1416	If debug=1, it means the engine wants to send debug output prefixed by '#',
		1417	which WinBoard should ignore, except for including it in the winboard.debug file.
		1418	As this feature is added to protocol 2 ony late,
		1419	so that not all protocol-2 supporting versions of WinBoard might implement it,
		1420	it is important that engines check if WinBoard accepts the feature.
		1421	If the feature is rejected,
		1422	engines must refrain from sending the debug output,
		1423	or do so at their own risk.
		1424	</font>
		1425
		1426	<dt><font color=blue>
		1427	<strong>memory</strong> (boolean, default 0)
		1428	</font>
		1429	<dd><font color=blue>
		1430	If memory=1, the size of the total amount of memory available for the memory-consuming tables of the engine
		1431	(e.g. hash, EGTB cache)
		1432	will be set by the GUI through the "memory" command.
		1433	</font>
		1434
		1435	<dt><font color=blue>
		1436	<strong>smp</strong> (boolean, default 0)
		1437	</font>
		1438	<dd><font color=blue>
		1439	If smp=1, the GUI will send the "cores" command to the engine to inform it how many CPU cores it can use.
		1440	Note that sending smp=1 does not imply the engine can use more than one CPU;
		1441	just that it wants to receive the "cores" command.
		1442	</font>
		1443
		1444	<dt><font color=blue>
		1445	<strong>egt</strong> (string, see text below)
		1446	</font>
		1447	<dd><font color=blue>
		1448	This feature indicates which end-game table formats the engine supports.
		1449	It should be a comma-separated list of format names.
		1450	See under the "egtpath" command in <a href="#8">section 8</a> above.
		1451	If you do not set this feature, xboard will assume the engine does not support end-game tables,
		1452	and will not send any "egtpath" commands to inform the engine about their whereabouts.
		1453	</font>
		1454
		1455	<dt><font color=blue>
		1456	<strong>option</strong> (string, see text below)
		1457	</font>
		1458	<dd><font color=blue>
		1459	This feature is used by the engine to define an option command to appear in a GUI menu,
		1460	so that the user can change the corresponding setting of the engine through the GUI interactively.
		1461	The string describes the option by defining a name, type, current value and (sometimes) the acceptable value range.
		1462	Unlike other features, option features are accumulated by the GUI,
		1463	and the GUI must be able to add a new option to the list at any time,
		1464	even after having received feature done=1.
		1465	There are ten different options types, each requiring a slighly different syntax of the defining string:
		1466	<br>
		1467	feature option="NAME -button"
		1468	<br>
		1469	feature option="NAME -save"
		1470	<br>
		1471	feature option="NAME -reset"
		1472	<br>
		1473	feature option="NAME -check VALUE"
		1474	<br>
		1475	feature option="NAME -string VALUE"
		1476	<br>
		1477	feature option="NAME -spin VALUE MIN MAX"
		1478	<br>
		1479	feature option="NAME -combo CHOICE1 /// CHOICE2 ..."
		1480	<br>
		1481	feature option="NAME -slider VALUE MIN MAX"
		1482	<br>
		1483	feature option="NAME -file VALUE"
		1484	<br>
		1485	feature option="NAME -path VALUE"
		1486	<br>
		1487	NAME is an arbitrary alphanumeric string which can contain spaces;
		1488	the other words in capitals would be replaced by the current (default) setting of the option,
		1489	(a character string for -string options, a decimal number for -spin and -check options,
		1490	were the latter uses 1=checked, 0=unchecked),
		1491	the minimum or maximum value of numeric (-spin) options,
		1492	or arbitrary text labels (for -combo option).
		1493	In the latter case, the current value will be preceded by an asterisk.
		1494	The -file and -path options are similar to -string, but can be used to inform the GUI that
		1495	the text represents a file name or folder name respectively,
		1496	so the GUI dialog could add the appropriate browse button to the text-edit field.
		1497	Similarly, a -slider option is like a -spin, but the GUI might make a different
		1498	graphical representation for it.
		1499	A -save option is like a -button, and defines an immediate command to be sent by the engine.
		1500	With -save the GUI will make sure all current option settings are flushed to the engine
		1501	before it sends this command.
		1502	A -reset option is like a -button, but use of it purges the list of options before sending
		1503	the corresponding option command to the engine.
		1504	This enables the engine to completely redefine its options or their current settings,
		1505	by sending a new set of option feature commands to the GUI,
		1506	terminated by feature done=1.
		1507	(The effect of sending an option feature for an option with the same name as was defined before,
		1508	without first receiving a -reset option command, is undefined.)
		1509	</font>
		1510
		1511	<dt><font color=red>
		1512	<strong>done</strong> (integer, no default)
		1513	</font>
		1514	<dd><font color=red>
		1515	If you set done=1 during the initial two-second timeout after
		1516	xboard sends you the "xboard" command, the
		1517	timeout will end and xboard will not look for any more feature
		1518	commands before starting normal operation.
		1519	If you set done=0, the initial timeout is increased to one hour;
		1520	in this case, you must set done=1 before xboard will enter normal operation.
		1521	</font>
		1522	</dl>
		1523	<p>
		1524
		1525	<dt><strong>Illegal move: MOVE</strong>
		1526	<dt><strong>Illegal move (REASON): MOVE</strong>
		1527	<dd>If your engine receives a MOVE command that is recognizably a move
		1528	but is not legal in the current position, your engine must print an
		1529	error message in one of the above formats so that xboard can pass the
		1530	error on to the user and retract the move. The (REASON) is entirely
		1531	optional. Examples:
		1532
		1533	<pre>
		1534	Illegal move: e2e4
		1535	Illegal move (in check): Nf3
		1536	Illegal move (moving into check): e1g1
		1537	</pre>
		1538	<p>
		1539	Generally, xboard will never send an ambiguous move, so it does not
		1540	matter whether you respond to such a move with an Illegal move message
		1541	or an Error message.
		1542	</p>
		1543
		1544	<dt><strong>Error (ERRORTYPE): COMMAND</strong>
		1545	<dd>If your engine receives a command it does not understand or does
		1546	not implement, it should print an error message in the above format so
		1547	that xboard can parse it. Examples:
		1548	<pre>
		1549	Error (ambiguous move): Nf3
		1550	Error (unknown command): analyze
		1551	Error (command not legal now): undo
		1552	Error (too many parameters): level 1 2 3 4 5 6 7
		1553	</pre>
		1554
		1555	<dt><strong>move MOVE</strong>
		1556	<dd>Your engine is making the move MOVE. Do not echo moves from
		1557	xboard with this command; send only new moves made by the engine.
		1558
		1559	<font color=red>
		1560	<p>For the actual move text from your chess engine (in place of MOVE
		1561	above), your move should be either
		1562	<ul>
		1563	<li>in coordinate notation (e.g.,
		1564	e2e4, e7e8q) with castling indicated by the King's two-square move (e.g.,
		1565	e1g1), or
		1566	<li>in Standard Algebraic Notation (SAN) as defined in the
		1567	Portable Game Notation standard (e.g, e4, Nf3, O-O, cxb5, Nxe4, e8=Q),
		1568	with the extension piece@square (e.g., P@f7) to handle piece placement
		1569	in bughouse and crazyhouse.
		1570	</ul>
		1571	xboard itself also accepts some variants of SAN, but for compatibility
		1572	with non-xboard interfaces, it is best not to rely on this behavior.
		1573	</p>
		1574
		1575	<p>Warning: Even though all versions of this protocol specification
		1576	have indicated that xboard accepts SAN moves, some non-xboard
		1577	interfaces are known to accept only coordinate notation. See the
		1578	Idioms section for more information on the known limitations of some
		1579	non-xboard interfaces. It should be safe to send SAN moves if you
		1580	receive a "protover 2" (or later) command from the interface, but
		1581	otherwise it is best to stick to coordinate notation for maximum
		1582	compatibility. An even more conservative approach would be for your
		1583	engine to send SAN to the interface only if you have set feature san=1
		1584	(which causes the interface to send SAN to you) and have received
		1585	"accepted san" in reply.
		1586	</p>
		1587	</font>
		1588
		1589	<dt><strong>RESULT {COMMENT}</strong> <dd>When your engine detects
		1590	that the game has ended by rule, your engine must output a line of the
		1591	form "RESULT {comment}" (without the quotes), where RESULT is a PGN
		1592	result code (1-0, 0-1, or 1/2-1/2), and comment is the reason. Here
		1593	"by rule" means that the game is definitely over because of what
		1594	happened on the board. In normal chess, this includes checkmate,
		1595	stalemate, triple repetition, the 50 move rule, or insufficient
		1596	material; it does not include loss on time or the like.
		1597	Examples:
		1598	<pre>
		1599	0-1 {Black mates}
		1600	1-0 {White mates}
		1601	1/2-1/2 {Draw by repetition}
		1602	1/2-1/2 {Stalemate}
		1603	</pre>
		1604
		1605	<p>
		1606	xboard relays the result to the user, the ICS, the other engine in Two
		1607	Machines mode, and the PGN save file as required.
		1608	<font color=green>Note that "definitey over" above means that sending this command
		1609	will be taken by WinBoard as an unconditional refusal of the engine to play on,
		1610	which might cause you to forfeit if the game was in fact not over.
		1611	This command should thus not be used to offer draws, accept draws,
		1612	or make draw-by-rule claims that are not yet valid in the current position
		1613	(but will be after you move).
		1614	For offering and claiming such draws, "offer draw" should be used.</font>
		1615	<p>
		1616	<font color=blue>
		1617	Note that (in accordance with FIDE rules) only KK, KNK, KBK and KBKB with all bishops on the
		1618	same color can be claimed as draws on the basis of insufficient mating material.
		1619	The end-games KNNK, KBKN, KNKN and KBKB with unlike bishops do have mate positions,
		1620	and cannot be claimed.
		1621	Complex draws based on locked Pawn chains will not be recognized as draws by most interfaces,
		1622	so do not claim in such positions, but just offer a draw or play on.
		1623	</font>
		1624	<p>
		1625	<font color=blue>
		1626	Note to GUI programmers: RESULT commands that the engine sends immediately after its move
		1627	might be detected by the GUI only after the opponent has moved, because of communication
		1628	and scheduling delays, no matter how fast the engine sent it.
		1629	Any judgement of the validity of RESULT claims based on te "current" board position
		1630	will have to account for this uncertainty.
		1631	</font>
		1632	</p>
		1633
		1634	<dt><strong>resign</strong>
		1635	<dd>If your engine wants to resign, it can send the command "resign".
		1636	Alternatively, it can use the "RESULT {comment}" command if the string
		1637	"resign" is included in the comment; for example "0-1 {White
		1638	resigns}". xboard relays the resignation to the user, the ICS, the
		1639	other engine in Two Machines mode, and the PGN save file as required.
		1640	<font color=blue>Note that many interfaces work more smoothly if you resign <em>before</em>
		1641	you move.</font>
		1642	<p>
		1643
		1644	<dt><strong>offer draw</strong>
		1645	<dd>If your engine wants to offer a draw by agreement (as opposed to
		1646	claiming a draw by rule), it can send the command "offer draw".
		1647	xboard relays the offer to the user, the ICS, the other engine in Two
		1648	Machines mode, and the PGN save file as required. In Machine White,
		1649	Machine Black, or Two Machines mode, the offer is considered valid
		1650	until your engine has made two more moves.
		1651	<font color=green>This command must also be used to accept a draw offer.
		1652	Do not use the 1/2-1/2 command for that, as the offer might be no longer valid,
		1653	in which case a refusal to play on implied by the RESULT command might make you forfeit the game.
		1654	"offer draw" should also be used to claim 50-move and 3-fold-repetition draws
		1655	that will occur <em>after</em> your move, by sending it <em>before</em> making the move.
		1656	WinBoard will grant draw offers without the opponent having any say in
		1657	it in situations where draws can be claimed.
		1658	Only if the draw cannot be claimed, the offer will be passed to your opponent after you make your next move,
		1659	just before WinBoard relays this move to the opponent.
		1660	</font>
		1661	<p>
		1662
		1663	<dt><font color=red><strong>tellopponent MESSAGE</strong></font>
		1664	<dd><font color=red>
		1665	This command lets the engine give a message to its opponent,
		1666	independent of whether the opponent is a user on the local machine or
		1667	a remote ICS user (Zippy mode). MESSAGE consists of any characters,
		1668	including whitespace, to the end of the line. When the engine is
		1669	playing against a user on the local machine, xboard pops up an
		1670	information dialog containing the message. When the engine is playing
		1671	against an opponent on the ICS (Zippy mode), xboard sends "say
		1672	MESSAGE\n" to the ICS.
		1673	<p>
		1674
		1675	<dt><strong>tellothers MESSAGE</strong>
		1676	<dd>This command lets the engine give a message to people watching the
		1677	game other than the engine's opponent. MESSAGE consists of any
		1678	characters, including whitespace, to the end of the line. When the
		1679	engine is playing against a user on the local machine, this command
		1680	does nothing. When the engine is playing against an opponent on the
		1681	ICS (Zippy mode), xboard sends "whisper MESSAGE\n" to the ICS.
		1682	<p>
		1683
		1684	<dt><strong>tellall MESSAGE</strong>
		1685	<dd>This command lets the engine give a message to its opponent and
		1686	other people watching the game,
		1687	independent of whether the opponent is a user on the local machine or
		1688	a remote ICS user (Zippy mode). MESSAGE consists of any characters,
		1689	including whitespace, to the end of the line. When the engine is
		1690	playing against a user on the local machine, xboard pops up an
		1691	information dialog containing the message. When the engine is playing
		1692	against an opponent on the ICS (Zippy mode), xboard sends "kibitz
		1693	MESSAGE\n" to the ICS.
		1694	</font>
		1695	<p>
		1696
		1697	<dt><strong>telluser MESSAGE</strong>
		1698	<dd>xboard pops up an information dialog containing the message.
		1699	MESSAGE consists of any characters, including whitespace, to the end
		1700	of the line.
		1701	<p>
		1702
		1703	<dt><strong>tellusererror MESSAGE</strong>
		1704	<dd>xboard pops up an error dialog containing the message.
		1705	MESSAGE consists of any characters, including whitespace, to the end
		1706	of the line.
		1707	<p>
		1708
		1709	<dt><strong>askuser REPTAG MESSAGE</strong>
		1710	<dd>Here REPTAG is a string containing no whitespace, and MESSAGE
		1711	consists of any characters, including whitespace, to the end of the
		1712	line. xboard pops up a question dialog that says MESSAGE and
		1713	has a typein box. If the user types in "bar", xboard sends "REPTAG
		1714	bar" to the engine. The user can cancel the dialog and send nothing.
		1715	<p>
		1716
		1717	<dt><strong>tellics MESSAGE</strong>
		1718	<dd>In Zippy mode, xboard sends "MESSAGE\n" to ICS. MESSAGE consists
		1719	of any characters, including whitespace, to the end of the line.
		1720	<p>
		1721
		1722	<dt><font color=red><strong>tellicsnoalias MESSAGE</strong></font>
		1723	<dd><font color=red>
		1724	In Zippy mode, xboard sends "xMESSAGE\n" to ICS, where "x" is a
		1725	character that prevents the ICS from expanding command aliases, if
		1726	xboard knows of such a character. (On chessclub.com and chess.net,
		1727	"/" is used; on freechess.org, "$" is used.) MESSAGE consists of any
		1728	characters, including whitespace, to the end of the line.
		1729	</font>
		1730	<p>
		1731
		1732	<dt><font color=green><strong># COMMENT</strong></font>
		1733	<dd><font color=green>
		1734	The engine can send any string of printable characters, terminated by a newline,
		1735	for inclusion in the winboard.debug file, provided the line starts with a '#' character.
		1736	If the engine has set feature debug=1,
		1737	it is guaranteed that WinBoard (and any future version of it) will completely ignore
		1738	these lines in any other respect.
		1739	</font>
		1740	</dl>
		1741	<p>
		1742
		1743	<h2><a name="10">10. Thinking Output</a></h2>
		1744
		1745	<p>
		1746	If the user asks your engine to "show thinking", xboard sends your
		1747	engine the "post" command. It sends "nopost" to turn thinking off.
		1748	In post mode, your engine sends output lines to show the progress of
		1749	its thinking. The engine can send as many or few of these lines as it
		1750	wants to, whenever it wants to. Typically they would be sent when the
		1751	PV (principal variation) changes or the depth changes. The thinking
		1752	output should be in the following format:
		1753	</p>
		1754
		1755	<pre>ply score time nodes pv</pre>
		1756
		1757	Where:
		1758	<table>
		1759	<tr align="left"><th>ply<td>Integer giving current search depth.
		1760	<tr align="left"><th>score<td>Integer giving current evaluation in centipawns.
		1761	<tr align="left"><th>time<td>Current search time in centiseconds (ex:
		1762	1028 = 10.28 seconds).
		1763
		1764	<tr align="left"><th>nodes<td>Nodes searched.
		1765	<tr align="left"><th>pv<td>Freeform text giving current "best" line.
		1766	You can continue the pv onto another line if you start each
		1767	continuation line with at least four space characters.
		1768	</table>
		1769
		1770	<p>
		1771	Example:
		1772	</p>
		1773
		1774	<pre> 9 156 1084 48000 Nf3 Nc6 Nc3 Nf6</pre>
		1775
		1776	<p>
		1777	Meaning:
		1778	</p>
		1779
		1780	9 ply, score=1.56, time = 10.84 seconds, nodes=48000,
		1781	PV = "Nf3 Nc6 Nc3 Nf6"
		1782
		1783	<p>
		1784	Longer example from actual Crafty output:
		1785	</p>
		1786	<pre>
		1787	4 109 14 1435 1. e4 d5 2. Qf3 dxe4 3. Qxe4 Nc6
		1788	4 116 23 2252 1. Nf3 Nc6 2. e4 e6
		1789	4 116 27 2589 1. Nf3 Nc6 2. e4 e6
		1790	5 141 44 4539 1. Nf3 Nc6 2. O-O e5 3. e4
		1791	5 141 54 5568 1. Nf3 Nc6 2. O-O e5 3. e4
		1792	</pre>
		1793
		1794	<p>
		1795	You can use the PV to show other things; for instance, while in book,
		1796	Crafty shows the observed frequency of different reply moves in its
		1797	book. In situations like this where your engine is not really
		1798	searching, start the PV with a '(' character:
		1799	</p>
		1800
		1801	<pre>
		1802
		1803	</pre>
		1804
		1805	<p>
		1806	GNU Chess output is very slightly different. The ply number is
		1807	followed by an extra nonblank character, and the time is in seconds,
		1808	not hundredths of seconds. For compatibility, xboard accepts the
		1809	extra character and takes it as a flag indicating the different time
		1810	units. Example:
		1811	</p>
		1812
		1813	<pre>
		1814	2. 14 0 38 d1d2 e8e7
		1815	3+ 78 0 65 d1d2 e8e7 d2d3
		1816	3& 14 0 89 d1d2 e8e7 d2d3
		1817	3& 76 0 191 d1e2 e8e7 e2e3
		1818	3. 76 0 215 d1e2 e8e7 e2e3
		1819	4& 15 0 366 d1e2 e8e7 e2e3 e7e6
		1820	4. 15 0 515 d1e2 e8e7 e2e3 e7e6
		1821	5+ 74 0 702 d1e2 f7f5 e2e3 e8e7 e3f4
		1822	5& 71 0 1085 d1e2 e8e7 e2e3 e7e6 e3f4
		1823	5. 71 0 1669 d1e2 e8e7 e2e3 e7e6 e3f4
		1824	6& 48 0 3035 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4
		1825	6. 48 0 3720 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4
		1826	7& 48 0 6381 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4
		1827	7. 48 0 10056 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4
		1828	8& 66 1 20536 d1e2 e8e7 e2e3 e7e6 e3d4 g7g5 a2a4 f7f5
		1829	8. 66 1 24387 d1e2 e8e7 e2e3 e7e6 e3d4 g7g5 a2a4 f7f5
		1830	9& 62 2 38886 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 a2a4 h5h4
		1831	d4e4
		1832	9. 62 4 72578 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 a2a4 h5h4
		1833	d4e4
		1834	10& 34 7 135944 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 c2c4 h5h4
		1835	d4e4 f7f5 e4f4
		1836	10. 34 9 173474 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 c2c4 h5h4
		1837	d4e4 f7f5 e4f4
		1838	</pre>
		1839
		1840	<p>If your engine is pondering (thinking on its opponent's time) in post
		1841	mode, it can show its thinking then too. In this case your engine may
		1842	omit the hint move (the move it is assuming its opponent will make)
		1843	from the thinking lines <em>if and only if</em> it sends xboard the move in
		1844	the usual "Hint: xxx" format before sending the first line.
		1845	</p>
		1846
		1847	<h2><a name="11">11. Time control</a></h2>
		1848
		1849	<p>
		1850	xboard supports three styles of time control: conventional chess clocks,
		1851	the ICS-style incremental clock, and an exact number of seconds per move.
		1852	</p>
		1853
		1854	<p>In conventional clock mode, every time control period is the same.
		1855	That is, if the time control is 40 moves in 5 minutes, then after each
		1856	side has made 40 moves, they each get an additional 5 minutes, and so
		1857	on, ad infinitum. At some future time it would be nice to support a
		1858	series of distinct time controls. This is very low on my personal
		1859	priority list, but code donations to the xboard project are accepted,
		1860	so feel free to take a swing at it. I suggest you talk to me first,
		1861	though.
		1862	</p>
		1863
		1864	<p>
		1865	The command to set a conventional time control looks like this:
		1866	</p>
		1867
		1868	<pre>
		1869	level 40 5 0
		1870	level 40 0:30 0
		1871	</pre>
		1872
		1873	<p>
		1874	The 40 means that there are 40 moves per time control. The 5 means
		1875	there are 5 minutes in the control. In the second example, the 0:30
		1876	means there are 30 seconds. The final 0 means that we are in
		1877	conventional clock mode.
		1878	</p>
		1879
		1880	<p>
		1881	<font color=green>
		1882	Note that the time parameter in this command is not a pure numeric argument,
		1883	but in general is a character string, in order to pass the number of seconds.
		1884	Engines are encouraged to ignore any unexpected characters at the end of this string,
		1885	i.e. following the MIN or MIN:SEC specification.
		1886	Future protocol versions might (under control of an appropriate feature)
		1887	append such extra characters to this argument,
		1888	in order to inform the engine in advance of the time control it can expect after the current session completes.
		1889	E.g. "level 40 25+5 0" could mean that the engine has to play 40 moves in 25 minutes,
		1890	but should expect to get only 5 minutes for the entire remainder of the game after that,
		1891	rather than another 25 minutes for the next 40 moves.
		1892	When the time comes, (i.e. after the 40 moves),
		1893	it will be informed of the time-control change by receiving a new "level 0 5 0" command,
		1894	but engines with advanced time management might want to plan for this in advance.
		1895	</font>
		1896	</p>
		1897
		1898	<p>
		1899	The command to set an incremental time control looks like this:
		1900	</p>
		1901
		1902	<pre>
		1903	level 0 2 12
		1904	</pre>
		1905
		1906	<p>
		1907	Here the 0 means "play the whole game in this time control period",
		1908	the 2 means "base=2 minutes", and the 12 means "inc=12 seconds". As
		1909	in conventional clock mode, the second argument to level can be in
		1910	minutes and seconds.
		1911	</p>
		1912
		1913	<p>
		1914	At the start of the game, each player's clock is set to base minutes.
		1915	Immediately after a player makes a move, inc seconds are added to his
		1916	clock. A player's clock counts down while it is his turn. Your flag
		1917	can be called whenever your clock is zero or negative. (Your clock
		1918	can go negative and then become positive again because of the
		1919	increment.)
		1920	</p>
		1921
		1922	<p><font color=blue>
		1923	The number of moves given in the level command (when non-zero) should
		1924	be taken as the number of moves still to do before the specified time
		1925	will be added to the clock, if the "level" command is received after
		1926	some moves have already been played.
		1927	The time given should be interpreted as the time left on its clock
		1928	(including any time left over from the previous sessions),
		1929	and not necessarily the time that will be added to the clock
		1930	after the specified number of moves has been played.
		1931	This is only relevant in WinBoard 4.3.xx, which might send the engine
		1932	"level" commands during a game,
		1933	just before the engine has to start thinking about the first move of
		1934	a new time-control session.
		1935	Example: if at the start of the game "level 40 60 0" was given
		1936	(40 moves per hour),
		1937	and the engine receives "level 20 22 0" just before move 41,
		1938	it should understand that it should do the next 20 moves in 22 minutes
		1939	(pehaps because the secondary session was 20 moves per 15 minutes,
		1940	and it had 7 minutes left on its clock after the first 40 moves).
		1941	</font></p>
		1942
		1943	<p>
		1944	A special rule on some ICS implementations: if you ask for a game with
		1945	base=0, the clocks really start at 10 seconds instead of 0. xboard
		1946	itself does not know about this rule, so it passes the 0 on to the
		1947	engine instead of changing it to 0:10.
		1948	</p>
		1949
		1950	<p>
		1951	ICS also has time odds games. With time odds, each player has his own
		1952	(base, inc) pair, but otherwise things work the same as in normal
		1953	games. The Zippy xboard accepts time odds games but ignores the fact
		1954	that the opponent's parameters are different; this is perhaps not
		1955	quite the right thing to do, but gnuchess doesn't understand time
		1956	odds. Time odds games are always unrated.
		1957	</p>
		1958
		1959	<p>
		1960	The command to set an exact number of seconds per move looks like this:
		1961	</p>
		1962
		1963	<pre>
		1964	st 30
		1965	</pre>
		1966
		1967	<p>
		1968	This means that each move must be made in at most 30 seconds. Time not used
		1969	on one move does not accumulate for use on later moves.
		1970	</p>
		1971
		1972	<h2><a name="12">12. Analyze Mode</a></h2>
		1973
		1974	<p>xboard supports analyzing fresh games, edited positions, and games
		1975	from files. However, all of these look the same from the chess
		1976	engine's perspective. Basically, the engine just has to respond to the
		1977	"analyze" command.
		1978	<font color=red>
		1979	Beginning in protocol version 2,
		1980	if your engine does not support analyze mode, it should use
		1981	the feature command to set analyze=0.
		1982	</font>
		1983	The older method of
		1984	printing the error message "Error (unknown command): analyze" in
		1985	response to the "analyze" command will also work, however.
		1986	</p>
		1987
		1988	<p>
		1989	To enter analyze mode, xboard sends the command sequence "post", "analyze".
		1990	Analyze mode in your engine should be
		1991	similar to force mode, except that your engine thinks about what move
		1992	it would make next if it were on move. Your engine should accept the
		1993	following commands while in analyze mode:
		1994	</p>
		1995
		1996	<ul>
		1997	<li>Any legal move, as in force mode
		1998	<li><strong>undo</strong>   Back up one move and analyze previous position.
		1999	<li><strong>new</strong>   Reset position to start of game but stay in analyze mode.
		2000	<li><font color=red><strong>setboard</strong> if you have set feature setboard=1; otherwise <strong>edit</strong>. Exiting edit mode returns to analyze mode.
		2001	</font>
		2002	<li><strong>exit</strong>   Leave analyze mode.
		2003	<li><strong>.</strong>   Send a search status update (optional); see below.
		2004	<li><font color=red>
		2005	<strong>bk</strong>   Show book moves from this position,
		2006	if any; see above.</font>
		2007	<li><font color=red>
		2008	<strong>hint</strong>   Show the predicted move from this
		2009	position, if any; see above.</font>
		2010	</ul>
		2011
		2012	<p>
		2013	If the user selects "Periodic Updates", xboard will send the string
		2014	".\n" to the chess engine periodically during analyze mode, unless the
		2015	last PV received began with a '(' character.
		2016	</p>
		2017
		2018	<p>
		2019	The chess engine should respond to ".\n" with a line like this:
		2020	</p>
		2021
		2022	<pre>
		2023	stat01: time nodes ply mvleft mvtot <font color=red>mvname</font>
		2024	</pre>
		2025
		2026	Where:
		2027	<table>
		2028	<tr align="left"><th>time<td>Elapsed search time in centiseconds (ie: 567 = 5.67 seconds).
		2029	<tr align="left"><th>nodes<td>Nodes searched so far.
		2030	<tr align="left"><th>ply<td>Search depth so far.
		2031	<tr align="left"><th>mvleft<td>Number of moves left to consider at this depth.
		2032	<tr align="left"><th>mvtot<td>Total number of moves to consider.
		2033	<tr align="left"><th><font color=red>mvname</font><td><font color=red>
		2034	Move currently being considered (SAN or coordinate notation). Optional;
		2035	added in protocol version 2.</font>
		2036	</table>
		2037
		2038	<p>
		2039	Examples:
		2040	</p>
		2041	<pre>
		2042	stat01: 1234 30000 7 5 30
		2043	stat01: 1234 30000 7 5 30 Nf3
		2044	</pre>
		2045
		2046	<p>
		2047	Meaning:
		2048	</p>
		2049
		2050	<p>After 12.34 seconds, I've searched 7 ply/30000 nodes, there are a
		2051	total of 30 legal moves, and I have 5 more moves to search
		2052	before going to depth 8. In the second example, of the 30 legal
		2053	moves, the one I am currently searching is Nf3.</p>
		2054
		2055	<p>
		2056	Implementation of the "." command is optional. If the engine does not
		2057	respond to the "." command with a "stat01..." line, xboard will stop
		2058	sending "." commands. If the engine does not implement this command,
		2059	the analysis window will use a shortened format to display the engine
		2060	info.
		2061	</p>
		2062
		2063	<p>
		2064	To give the user some extra information, the chess engine can output
		2065	the strings "++\n" and "--\n", to indicate that the current search is
		2066	failing high or low, respectively. You don't have to send anything
		2067	else to say "Okay, I'm not failing high/low anymore." xboard will
		2068	figure this out itself.
		2069	</p>
		2070
		2071	<h2><a name="13">13. Idioms and backward compatibility features</a></h2>
		2072
		2073	<p>
		2074	Some engines have variant interpretations of the force/go/white/black,
		2075	time/otim, and hard/easy command sets.
		2076	In order to accommodate these older engines, xboard uses these commands
		2077	only according to the stylized patterns ("idioms") given in this section.
		2078	The obsolete white and black commands
		2079	have historically been particularly troublesome, and it is recommended
		2080	that new engines set the feature colors=0 and/or ignore the commands.
		2081	</p>
		2082
		2083	<dl>
		2084
		2085	<dt><strong>time N</strong>
		2086	<dt><strong>otim N</strong>
		2087	<dt><strong>MOVE</strong>
		2088	<dd>Sent when the opponent makes a move and the engine is already
		2089	playing the opposite color.
		2090	<p>
		2091
		2092	<dt><strong>white</strong>
		2093	<dt><strong>go</strong>
		2094	<dd>Sent when the engine is in force mode or playing Black but should
		2095	switch to playing White. This sequence is sent only when White is
		2096	already on move.
		2097	<font color=red>
		2098	If you set the feature colors=0, "white" is not sent.
		2099	</font>
		2100	<p>
		2101
		2102	<dt><strong>black</strong>
		2103	<dt><strong>go</strong>
		2104	<dd>Sent when the engine is in force mode or playing White but should
		2105	switch to playing Black. This sequence is sent only when Black is
		2106	already on move.
		2107	<font color=red>
		2108	If you set the feature colors=0, "black" is not sent.
		2109	</font>
		2110	<p>
		2111
		2112	<dt><strong>white</strong>
		2113	<dt><strong>time N</strong>
		2114	<dt><strong>otim N</strong>
		2115	<dt><strong>black</strong>
		2116	<dt><strong>go</strong>
		2117	<dd>Sent when Black is on move, the engine is in force mode or playing
		2118	White, and the engine's clock needs to be updated before it starts
		2119	playing.
		2120	The initial "white" is a kludge to accommodate GNU Chess
		2121	4's variant interpretation of these commands.
		2122	<font color=red>
		2123	If you set the feature colors=0, "white" and "black" are not sent.
		2124	</font>
		2125	<p>
		2126
		2127	<dt><strong>black</strong>
		2128	<dt><strong>time N</strong>
		2129	<dt><strong>otim N</strong>
		2130	<dt><strong>white</strong>
		2131	<dt><strong>go</strong>
		2132	<dd>Sent when White is on move, the engine is in force mode or playing
		2133	Black, and the engine's clock needs to be updated before it starts
		2134	playing. See previous idiom.
		2135	The initial "black" is a kludge to accommodate GNU Chess
		2136	4's variant interpretation of these commands.
		2137	<font color=red>
		2138	If you set the feature colors=0, "black" and "white" are not sent.
		2139	</font>
		2140	<p>
		2141
		2142	<dt><strong>hard</strong>
		2143	<dt><strong>easy</strong>
		2144	<dd>Sent in sequence to turn off pondering if xboard is not sure
		2145	whether it is on. When xboard is sure, it will send "hard" or "easy"
		2146	alone. xboard does this because "easy" is a toggle in GNU Chess 4 but
		2147	"hard" is an absolute on.
		2148
		2149	</dl>
		2150
		2151	<p>
		2152	To support older engines, certain additional commands from the engine
		2153	to xboard are also recognized. (These are commands by themselves, not
		2154	values to be placed in the comment field of the PGN result code.)
		2155	These forms are not recommended for new engines; use the PGN result
		2156	code commands or the resign command instead.
		2157	</p>
		2158
		2159	<table>
		2160	<tr align="left"><th>Command <th>Interpreted as
		2161	<tr align="left"><td>White resigns <td>0-1 {White resigns}
		2162	<tr align="left"><td>Black resigns <td>1-0 {Black resigns}
		2163	<tr align="left"><td>White <td>1-0 {White mates}
		2164	<tr align="left"><td>Black <td>0-1 {Black mates}
		2165	<tr align="left"><td>Draw <td>1/2-1/2 {Draw}
		2166	<tr align="left"><td>computer mates <td>1-0 {White mates} or 0-1 {Black mates}
		2167	<tr align="left"><td>opponent mates <td>1-0 {White mates} or 0-1 {Black mates}
		2168	<tr align="left"><td>computer resigns <td>0-1 {White resigns} or 1-0 {Black resigns}
		2169	<tr align="left"><td>game is a draw <td>1/2-1/2 {Draw}
		2170	<tr align="left"><td>checkmate <td>1-0 {White mates} or 0-1 {Black mates}
		2171	</table>
		2172
		2173	<p>
		2174	Commands in the above table are recognized if they begin a line and
		2175	arbitrary characters follow, so (for example) "White mates" will be
		2176	recognized as "White", and "game is a draw by the 50 move rule" will
		2177	be recognized as "game is a draw". All the commands are
		2178	case-sensitive.
		2179	</p>
		2180
		2181	<p>
		2182	An alternative move syntax is also recognized:
		2183	</p>
		2184
		2185	<table>
		2186	<tr align="left"><th>Command <th>Interpreted as
		2187	<tr align="left"><td>NUMBER ... MOVE <td>move MOVE
		2188	</table>
		2189
		2190	<p>
		2191	Here NUMBER means any string of decimal digits, optionally ending in a
		2192	period. MOVE is any string containing no whitespace. In this command
		2193	format, xboard requires the "..." even if your engine is playing
		2194	White. A command of the form NUMBER MOVE will be ignored. This odd
		2195	treatment of the commands is needed for compatibility with gnuchessx.
		2196	The original reasons for it are lost in the mists of time, but I
		2197	suspect it was originally a bug in the earliest versions of xboard,
		2198	before I started working on it, which someone "fixed" in the wrong
		2199	way, by creating a special version of gnuchess (gnuchessx) instead of
		2200	changing xboard.
		2201	</p>
		2202
		2203	<p>
		2204	Any line that contains the words "offer" and "draw" is recognized as
		2205	"offer draw".
		2206	</p>
		2207
		2208	<p>
		2209	The "Illegal move" message is recognized even if spelled "illegal
		2210	move" and even if the colon (":") is omitted. This accommodates GNU
		2211	Chess 4, which prints messages like "Illegal move (no matching
		2212	move)e2e4", and old versions of Crafty, which print just "illegal move".
		2213	</p>
		2214
		2215	<p>
		2216	In Zippy mode, for compatibility with older versions of Crafty,
		2217	xboard passes through to ICS any line that begins "kibitz", "whisper",
		2218	"tell", or "draw". Do not use this feature in new code. Instead, use the
		2219	commands "tellall", "tellothers", "tellopponent", "tellics" (if needed),
		2220	"1/2-1/2 {COMMENT}", or "offer draw", as appropriate.
		2221	</p>
		2222
		2223	<p>
		2224	<font color=red>
		2225	If the engine responds to the "sd DEPTH" command with an error message
		2226	indicating the command is not supported (such as "Illegal move: sd"),
		2227	xboard sets an internal flag and subsequently uses the command
		2228	"depth\nDEPTH" instead, for the benefit of GNU Chess 4. Note the
		2229	newline in the middle of this command! New engines should not rely on
		2230	this feature.
		2231	</font>
		2232	</p>
		2233
		2234	<p>
		2235	<font color=red>
		2236	If the engine responds to the "st TIME" command with an error message
		2237	indicating the command is not supported (such as "Illegal move: st"),
		2238	xboard sets an internal flag and subsequently uses the command "level
		2239	1 TIME" instead, for the benefit of GNU Chess 4. Note that this is
		2240	not a standard use of the level command, as TIME seconds are not added
		2241	after each player makes 1 move; rather, each move is made in at most
		2242	TIME seconds. New engines should not implement or rely on this
		2243	feature.
		2244	</font>
		2245	</p>
		2246
		2247	<font color=red>
		2248	<p>
		2249	In support of the -firstHost/-secondHost features, which allow a chess
		2250	engine to be run on another machine using the rsh protocol, xboard recognizes
		2251	error messages that are likely to come from rsh as fatal errors. The following
		2252	messages are currently recognized:
		2253	</p>
		2254
		2255	<blockquote>
		2256	unknown host<br>
		2257	No remote directory<br>
		2258	not found<br>
		2259	No such file<br>
		2260	can't alloc<br>
		2261	Permission denied<br>
		2262	</blockquote>
		2263	</font>
		2264
		2265	<p>
		2266	<font color=red>
		2267	ChessBase/Fritz now implements the xboard/winboard protocol and can use
		2268	WinBoard-compatible engines in its GUI. ChessBase's version of the
		2269	protocol is generally the same as version 1, except that they have
		2270	added the commands <strong>fritz</strong>, <strong>reset</strong>, and
		2271	<strong>ponder</strong>, and the edit subcommands
		2272	<strong>castle</strong> and <strong>ep</strong>. If you want your
		2273	engine to work well with the ChessBase/Fritz GUI, you may need to
		2274	implement these additional commands, and you should also be aware of
		2275	the peculiar way that ChessBase uses the protocol. See their <a
		2276	href="http://www.chessbase.com/Products/engines/winboard/tech.htm"
		2277	>web page</a> for documentation.
		2278	</font>
		2279	</p>
		2280
		2281	<p>
		2282	<font color=red>
		2283	ChessMaster 8000 also implements version 1 of the xboard/winboard
		2284	protocol and can use WinBoard-compatible engines. The original
		2285	release of CM8000 also has one additional restriction: only pure
		2286	coordinate notation (e.g., e2e4) is accepted in the move command. A
		2287	patch to correct this should be available from The Learning Company
		2288	(makers of CM8000) in February 2001.
		2289	</font>
		2290	</p>
		2291
		2292	<hr noshade size="2">
		2293	<address>converted to HTML by <a href="http://www.jakob.at/steffen/">Steffen A. Jakob</a></address>
		2294	</body>
		2295	</html>

Subversion Repositories Games.Chess Giants

Games.Chess Giants/cecp.html – Rev 128