Author: Will Singleton
Date: 00:23:30 11/29/00
There's always been a bit of a disconnect when we bring up the Macintosh, and
for good reason. That may change if OS X is successful, and particularly if it
is ported to the x86 cpu.
In any case, I have been running the only automated Mac engine on ICC for the
past two years. I originally wrote my own interface, which lacked timestamp.
The last few months I've been running with the Fixation interface, written by
Craig Knelson, which supports ICC and fics (timestamp and timeseal).
The following is a working, tested online server protocol. I know there are a
few Mac programmers out there, several with programs that have promise but are
untested in the online world. So, I hereby offer a challenge: to anyone who can
implement the following protocol on a Macintosh computer, interface to Fixation,
connect to ICC, and beat Amateur in a ten game match (20 5), within 30 days,
$500.
Fixation Chess Engine Protocol
==============================
Created: November 11, 2000
Revised: November 23, 2000
Fixation 2.0f2 (or higher) supports external chess engines which allows anyone
to run an automated computer account on the online chess servers such as the
Internet Chess Club (ICC) or Free Internet Chess Server (FICS).
As of this date, only the Amateur engine by Will Singleton works with Fixation
2.0f2. Other chess engine authors have expressed interest in using the protocol
as well.
Many of the chess engines currently out there for the Mac such as Screamer by
William Bryant or Sigma Chess by Ole Christensen support the ExaChess Apple
Events protocol. However, investigation of this protocol has revealed
some potential problems and limitations in trying to use it to run an
automated computer account on the online servers.
Will Singleton and I developed an Apple Events protocol based on application
signatures that seems easier to use than the method used by ExaChess.
This protocol is fairly rudimentary at present and has the following
limitations:
- the Apple Event messages are not acknowledged.
- only works when connected to an online server.
- there is no offline user-play mode that allows you to play against
the engine using Fixation as the GUI. Currently, move validation must be
performed by an online server as Fixation does not yet have this capability.
- the engine must be able understand style 12 lines from an online chess server.
Fixation to Engine
------------------
Fixation sends the following commands to the chess engine:
¥ adjourn
The opponent has issued an adjourn request. The engine should respond
with a "server" command either accepting or declining the request.
¥ challenge <account name>
This is sent when Fixation receives a match challenge on the server.
The engine must respond with the "accept" or "decline" command.
¥ draw
The opponent has issued a draw request. The engine should respond
with a "server" command either accepting or declining the request.
¥ fail
Fixation was unable to process a previous command from the chess engine.
The engine may want to try and re-send the previous command. This
command is not implemented in 2.0f2.
¥ gameover
This is sent when Fixation receives a game end message from the server.
The engine should disable pondering if currently enabled.
¥ newgame {white | black} engRating oppRating (oppTitle)
This is sent when Fixation receives a game started message from the
server. The "white"/"black" parameter says the engine will be white/black.
If "white", the engine could immediately send a "move" command after
it has prepared for a new game or it could wait for the first
board position. The oppTitle could be C, GM, IM, FM, WGM, WIM or empty
for non-titled players. NOTE: The parameters after the color are only
sent by 2.0 (Pre-Release) and not by 2.0f2.
¥ position (pass a complete style 12 position)
This is sent when Fixation receives a style 12 line from the server.
The entire style 12 line is appended to the command. For further
information on style 12, logon to a chess server and enter
"help style12".
¥ quit
Terminates the chess engine. Currently, the user must manually enter
"quit" in the Fixation chess engine window for this to be sent.
¥ takeback [n]
The opponent has issued a takeback request for n moves. If n is not
specified, the takeback is for the last move. The engine should
respond with a "server" command accepting or declining the request.
This command is not implemented in Fixation 2.0f2.
¥ talk [text]
A tell, say, whisper or kibitz has been received from the server. The
text is the entire contents of what has been received.
¥ version
This is sent when the user enables the chess engine option. The engine
must respond by sending "version <engine name> v.rr" to Fixation. Fixation
uses the version information to set the "interface" variable and finger
note one on the online chess server.
Engine to Fixation
------------------
The chess engine sends the following commands to Fixation:
¥ accept <account name>
Sent in response to a "challenge" command from Fixation. Since multiple
challenges could be pending, the engine must also send the account
name passed from the "challenge" command.
¥ decline <account name>
The challenge from <account name> has been declined. Since multiple
challenges could be pending, the engine must also send the account
name received in the "challenge" command from Fixation.
¥ fail
The engine was unable to process a previous command from Fixation.
¥ move [text]
Move made by the engine.
e.g. move a2a3, move a7a8=Q
¥ score_pv [text]
Current score evaluation by the engine. This information is displayed
in the Fixation chess engine window.
e.g. score_pv +15 a3 Bxa3 Qxa3 Rxa3...
¥ server [text]
Sends the text to the server.
e.g. server kibitz Hello from Amateur 1.0
server say I cannot accept takebacks.
¥ version <info>
Sent in response to a "version" command. <info> must contain the
engine name and version information.
e.g. version Amateur 1.0a
Automated Computer Account Setup
--------------------------------
¥ Create a registered account on the ICC, FICS or USCL. Guest accounts cannot
be used.
¥ Follow the server's procedures for designating an account that uses a
computer. Usually reading "help computers" will describe the process.
During logon, if the chess engine is enabled, Fixation checks that the
account being used is a designated (C) account. If it's not, Fixation
automatically disables the chess engine.
¥ Setup an alias on the server for the "gameend" command. Fixation sends this
command to the server at the end of each game. Typically, you would setup
this alias to issue multiples seeks and resume requests if on the ICC.
e.g. +alias gameend multi resume; seek 1 0 m f; seek 3 0 m f;
For FICS/USCL, there is no "multi" command so you are limited to just one
command.
e.g. alias gameend seek 3 0 m f
¥ When issuing seeks, use the "m" (manual) parameter. This allows Fixation
to send the challenge to the engine for screening. For example, Amateur can
be configured to only play a maximum number of games versus a particular
opponent.
¥ The chess engine must be started manually at present. A future version of
Fixation will automate this process when the chess engine option is enabled
within Fixation.
Apple Events Code used by Fixation:
-----------------------------------
The following shows the code used by Fixation to handle the apple event used
by the protcol. For chess engines, you will need to create an event descriptor
for Fixation. In Fixation, the majority of the interface between itself and
the chess engine is implemented by the Engine C++ class (Engine.cpp and
Engine.h).
Fixation 2.0f2 only sends the apple events to applications with the Amateur
signature. Future versions will support additional engine signatures.
¥ Define the application signatures:
#define kFxEngEventClass 'wwsx' /* Chess Engine - Amateur */
#define kFxIntEventClass 'Fxtn' /* Our application signature */
#define kFxAEMessage 'mesg'
#define ENGINE_SIG_AMATEUR "wwsx" /* Amateur by Will Singleton */
static char sEngineSig[4] = ENGINE_SIG_AMATEUR;
¥ The Apple Event handler:
static pascal OSErr AEChess(AppleEvent *theAE, AppleEvent *reply, long refCon)
{
#pragma unused(reply, refCon)
Size s;
DescType desc;
char msg[256];
/* --- Get message sent from the engine --- */
AEGetParamPtr(theAE, kFxAEMessage, typeWildCard, &desc, msg, sizeof(msg)-1,
&s);
msg[s] = 0;
/* --- Do something with the message --- */
...
return noErr;
}
¥ Install the Apple Event handler:
/* NOTE:
** The descriptor must be a static or global variable, not a stack variable.
*/
static RoutineDescriptor sChessRD =
BUILD_ROUTINE_DESCRIPTOR(uppAEEventHandlerProcInfo, AEChess);
err = AEInstallEventHandler(kFxIntEventClass, kFxAEMessage, &sChessRD,
(long int) this, false);
if (err != noErr) ...
¥ Create event descriptor based on the engine signature:
AEDesc aTarget;
err = AECreateDesc(typeApplSignature, &sEngineSig, sizeof(sEngineSig),
&aTarget);
if (err != noErr) ...
/* --- mAppleEvent is a member of the Engine class declared as: AppleEvent
--- */
err = AECreateAppleEvent(kFxEngEventClass, kFxAEMessage, &aTarget,
kAutoGenerateReturnID, kAnyTransactionID, &mAppleEvent);
if (err != noErr) ...
¥ To send a message to the engine:
err = AEPutParamPtr(&mAppleEvent, kFxAEMessage, typeChar, cmd, strlen(cmd));
if (err != noErr) ...
err = AESend(&mAppleEvent, 0, kAENoReply, kAEHighPriority,
kAEDefaultTimeout, 0, 0);
if (err != noErr) ...
This page took 0 seconds to execute
Last modified: Thu, 15 Apr 21 08:11:13 -0700
Current Computer Chess Club Forums at Talkchess. This site by Sean Mintz.