1Zippy README file 2For version xboard/WinBoard 4.2.4 and later only 3----------------------------------------------------- 4 5Zippy is a program that lets GNU Chess act as a computer player on an 6Internet Chess Server. It also works with Crafty. Zippy is 7unsupported, experimental code. 8 9Zippy is based on XBoard, a graphical interface to GNU Chess and to 10the ICS for the X Window system on Unix. Zippy consists of exactly 11the same code as XBoard, plus one extra module that ties together the 12otherwise-separate functions of talking to GNU Chess and talking to 13the ICS. Zippy is included in the XBoard distribution. 14 15There is also a version of Zippy that is based on WinBoard, a port of 16XBoard to Win32 (Microsoft Windows NT and Windows 95). WinBoard does 17*not* run on Windows 3.1 or 3.11, not even with Win32s. In versions 183.5 and later, the Zippy code is included in WinBoard.exe. 19 20If you use Zippy, I ask you to do the following: 21 22- Don't expect fast response if you send me mail about problems. It 23might take weeks for me to get back to you, or I might answer right 24away. Try to solve problems yourself before you mail me about them. 25Try asking someone who is actively running a Zippy-based player on ICC 26or FICS for help getting started. Mail me only if you get stuck. 27 28- Be honest. Tell the admins of whatever ICS you use that your player 29is a computer, so that it gets put onto the computer list, and follow 30the ICS computer policies. On ICC these are in "help computer"; read 31this file and abide by what it says. 32 33- If you want to interface some other chess program to ICS, feel free 34to start with this code. Some documentation is in the file 35engine-intf.html in the distribution. 36 37- Please do not use the -zt flag to have your program shout Zippy the 38Pinhead sayings (or other things that my Zippy shouts). One pinhead 39per server is plenty, and I'd like to keep the franchise. Feel free 40to use -zt to have your program shout some other kind of sayings if 41you like. Some of the jokes that Zippy shouts on ICC came from 42ftp://ftp.cco.caltech.edu/pub/humor. The poetry came from Project 43Gutenberg; try http://www.cs.cmu.edu/Web/booktitles.html as a starting 44point. You might find other suitable material at these sites. Prose 45tends to work poorly because it is dull when shouted in isolated 46250-character chunks. 47 48 --Tim Mann 49 http://www.tim-mann.org/chess.html 50 51* * * 52 53Unix: To build the Zippy version of xboard, on most systems just do: 54 configure --enable-zippy 55 make 56 57Windows: WinBoard.exe (versions 3.5 and later) includes the Zippy 58code. There is no longer a distinct WinZippy.exe. 59 60In both xboard and WinBoard, the Zippy features are off by default. 61You can activate them with two new resources/command line options, and 62you can fine-tune them with some new environment variables, all 63described below. 64 65You will probably want to make a shell script or Windows .BAT file 66that sets the environment variables you want to use and invokes Zippy 67with the right command line options for your situation. Some examples 68are at the bottom of this file. 69 70If you have problems building or running Zippy, see the rest of the 71xboard documentation: INSTALL documents the configure program, while 72READ_ME and xboard.man (or xboard.txt) document xboard itself, and 73WinBoard.hlp documents WinBoard. FAQ answers some frequently asked 74questions. The file engine-intf.html contains some information about 75the interface between xboard/WinBoard and GNU Chess (or other chess 76engines). 77 78=========== 79NEW OPTIONS 80=========== 81 82 -zippyPlay True/False or -zp/-xzp 83 If zippyPlay is set to True, when xboard is in -ics mode, it 84 will interface a chess engine to the ICS instead of letting you 85 play. You must also set -ics when you use this mode. 86 87 In zippyPlay mode, xboard blindly issues an accept command for 88 every (well, almost every, see below) challenge it gets, 89 without remembering anything about the challenge afterwards. 90 This means that often it will get several challenges very 91 close together and try to accept them all! ICS gives an error 92 message for every accept command after the one that actually 93 starts a match, but xboard just happily ignores the message. 94 xboard doesn't actually start the chess engine playing until 95 the first board image comes in from ICS. 96 97 The getMoveList option controls how adjourned games are 98 continued. If it is True (the default), xboard fetches the 99 move list from ICS and feeds it into the chess program before 100 having the program start play. If False, xboard feeds the 101 current position into the chess program and has it start from 102 there. The latter option gets the program going sooner, but 103 can cause problems with detection of en passant legality, 104 castling legality (if a king or rook has moved and then 105 returned to its home square), draw by repetition, and draw by 106 the 50 move rule. 107 108 In zippyPlay mode, colorization in the ICS interaction window, 109 and the sounds corresponding to colors in that window, do not 110 work. zippyPassword and related features (see below) capture 111 the tells, etc., before they can be matched by the color/sound 112 code. 113 114 -zippyTalk True/False or -zt/-xzt 115 If zippyTalk is set to True and xboard is in -ics mode: 116 117 (1) It will reply to anything said to it with a saying (if 118 there is a file of sayings in its working directory). This 119 includes channel tells and shouts where its name is mentioned. 120 Some things it says to opponents in specific situations will 121 also be made Zippy-ish; you might want to change that. See 122 zippyLines below for the file format. 123 124 (2) If a player XXX in your notify list logs on, xboard sends 125 the command "greet XXX" to ICS and tells XXX something from 126 its sayings file. You can alias this to whatever you like. 127 If XXX is censoring you, he is automatically removed from your 128 notify list. 129 130 (3) If a player XXX in your notify list logs off, xboard sends 131 the command "farewell XXX" to ICS. You can alias this to 132 whatever you like. Note that the player is already gone, so 133 telling him something is futile. 134 135 If zippyTalk is on, colorization in the ICS interaction 136 window, and the sounds corresponding to colors in that window, 137 do not work. The reply feature captures the tells, etc., 138 before they can be matched by the color/sound code. 139 140 In both -zp and -zt modes, if admin X spoofs Zippy, Zippy sends the 141 command "spoofedby X" to ICS. You can alias this to something if you 142 want; otherwise it will produce a harmless error message. 143 144 -zippyPinhead string 145 In zippyTalk mode, if user XXX shouts anything containing 146 this string, xboard sends the command "insult XXX" to ICS. 147 You can alias "insult" to whatever you like. This feature is 148 disabled if the option is not set. 149 150 -zippyPassword string 151 If someone does an ICS "tell" to xboard that begins with this 152 password, it will type the same string back as a command with 153 the password stripped off. For example, if the password is 154 !%%! and xboard sees the string "Darooha tells you: !%%!shout 155 Hi there", it will type the command "shout Hi there" to the 156 ICS. This feature is disabled if the option is not set. 157 158 -zippyPassword2 string 159 If someone does an ICS "tell" to xboard that begins with this 160 password, it will send the same string directly to the chess 161 engine with the password stripped off. This feature is 162 disabled if the option is not set. Use with caution. 163 164 -zippyWrongPassword string 165 This is a joke feature. If player XXX does an ICS "tell" to 166 xboard that begins with this password, it will send the 167 command "wrong XXX" to ICS. ICS does not define a "wrong" 168 command, but you can alias it to whatever you like. The 169 feature is supposed to be used after you've changed the 170 zippyPassword, so that people who knew the old password get a 171 funny message. Disabled if not set. 172 173 -zippyUseI True/False or -zui/-xzui 174 If this option is true, Zippy's shouts use the "i" command with 175 funny verbs; otherwise they use the "shout" command. Default 176 is true. The variable is automatically set to false if the "i" 177 command is disabled on ICS by the admins. 178 179 -zippyLines filename 180 Name of the file Zippy looks in for sayings when -zt is set. 181 Default: yow.lines. File format: There must be a single ^ 182 character or null character (control-@, ASCII code \000) after 183 each saying. Sayings can have newlines in them; Zippy will 184 remove them. Sayings can be at most about 250 characters; 185 longer ones will be ignored. The first saying in the file is 186 never used; you should put a comment there. If you have only 187 one or two sayings in your file, Zippy may get into a loop 188 trying to choose one. Zippy chooses a saying by seeking to a 189 random character position in the file, skipping ahead to the 190 *next* null character, and printing the saying that starts 191 there. If it hits end of file without finding a new saying, 192 it tries again. Yes, this is a dumb algorithm. 193 194 -zippyAcceptOnly string 195 Normally, Zippy automatically accepts challenges from all 196 opponents. If this option is set to an ICS login name, Zippy 197 will auto-accept challenges only from that opponent. Set the 198 option to an invalid name like "0" if you don't want Zippy to 199 auto-accept any challenges. You can still accept challenges 200 manually. Setting this option also suppresses the 201 zippyGameEnd feature described below. Default: not set. 202 203 -zippyNoplayCrafty True/False or -znc/-xznc 204 If this option is set to True, if Zippy's opponent kibitzes 205 "Hello from Crafty" within the first couple of moves, Zippy 206 will abort the game and add the opponent to his noplay list. 207 Default: False. 208 209 -zippyGameStart string 210 At the start of each game Zippy plays (including resuming from 211 adjournment), it sends this string to ICS, followed by a newline. 212 If the option is not set, nothing is sent. 213 214 -zippyGameEnd string 215 At the end of each game, Zippy sends this string to ICS, 216 followed by a newline. If you do not set this option, the 217 string "gameend" is sent. This is not a legal ICS command, 218 but you can alias it to whatever you like, or you can leave 219 it undefined, which will cause ICS to print a harmless error 220 message after each game. If you want to send more than one 221 command at the end of the game, on ICC you can alias gameend 222 to a "multi" command (see the ICC help files), but on FICS that 223 does not work. Instead, use the -zippyGameEnd option to have 224 a string of several commands sent, with newlines in between. 225 For example, you could give WinBoard the command line option 226 -zippyGameEnd=\"say thanks\\nseek 5 0\\nseek 2 12\\n\" 227 Note the extra backslashes: these are essential, because the 228 shell will strip them from the command before passing it to 229 XBoard, and XBoard needs to see the quotes (which would 230 otherwise be stripped by the shell as well), because only within 231 quotes it will recognize the \n as a linefeed. 232 233 -zippyAdjourn True/False or -zadj/-xzadj 234 Zippy will allow its opponent to adjourn if this option is 235 set to true. Default: False. 236 237 -zippyAbort True/False or -zab/-xzab 238 Zippy will allow its opponent to abort if this option is 239 set to true. Default: False. 240 241 -zippyVariants string 242 Zippy will decline to play chess variants unless their names 243 (as given in engine-intf.html) are listed in this option. 244 Default: "normal". Example: "suicide,losers,bughouse,normal". 245 246 Obviously, zippyVariants other than "normal" will work only 247 if your chess engine can play those variants. GNU Chess 248 certainly cannot, but there are some suicide and bughouse 249 engines available. While playing bughouse, Zippy passes 250 certain extra information on to the engine; see 251 engine-intf.html. 252 253 -zippyBughouse int 254 This option controls how Zippy handles bughouse partner 255 requests. If zippyBughouse is set to 0, Zippy will decline 256 any offers of partnership and tell the offerer that it cannot 257 play bughouse. If zippyBughouse is set to 1, Zippy will 258 decline offers, but you can make Zippy your partner by having 259 *it* offer *you* partnership (by using zippyPassword or typing 260 directly into its window). If zippyBughouse is set to 2, 261 Zippy will accept all offers of partnership, even if it 262 already has a partner. zippyBughouse must be at least 1 for 263 partner tells to be relayed to the engine with the ptell 264 command. 265 266 -zippyMaxGames int 267 -zippyReplayTimeout 268 If zippyMaxGames > 0, Zippy will play at most the given number 269 of consecutive games against the same opponent. Thereafter, 270 Zippy will decline all challenges from that opponent (with an 271 explanatory tell) until either someone else has played or 272 zippyReplayTimeout seconds have elapsed. Defaults: 273 zippyMaxGames=0, zippyReplayTimeout=120. 274 275 Note: If you use these options and you have Zippy doing seeks, 276 be sure to include the "m" flag in the ICS seek command. If 277 you use "seek m", when a player responds to the seek, the ICS 278 gives Zippy a challenge that it can either accept or decline. 279 If you use a seek without the "m" flag, the ICS immediately 280 starts a game between Zippy and the first opponent to respond, 281 giving Zippy no choice about whether to accept or decline. 282 283 -zippyShortGame int 284 If zippyShortGame > 0, Zippy will decline all challenges 285 from an opponent that terminated a game before the given number 286 of ply (with an explanatory tell) until either someone else has 287 played or zippyReplayTimeout seconds have elapsed. Do not set 288 the number of moves to large; the number of ply during which 289 opponents can abort a game without rating change would be a 290 good setting. Default: zippyShortGame=0. 291 292===================== 293ENVIRONMENT VARIABLES 294===================== 295 296 For backward compatibility with version 4.0.2 and earlier only, most 297 of the command line options listed above can also be set as 298 environment variables. For boolean options, use 0 for false, 1 for 299 true in the corresponding environment variable. The following 300 environment variables are supported.: 301 302 ZIPPYPINHEAD, ZIPPYPASSWORD, ZIPPYPASSWORD2, ZIPPYWRONGPASSWORD, 303 ZIPPYUSEI, ZIPPYLINES, ZIPPYACCEPTONLY, ZIPPYNOPLAYCRAFTY, 304 ZIPPYGAMESTART, ZIPPYGAMEEND, ZIPPYADJOURN, ZIPPYABORT, 305 ZIPPYVARIANTS, ZIPPYBUGHOUSE 306 307 Warnings: (1) If both the command line option and the corresponding 308 environment variable are set, the environment variable takes 309 precedence! (2) Some of the environment variables have names that 310 are too long for Solaris 2.5's /bin/csh. Use the command line 311 options instead. (3) Newer options DO NOT have environment 312 variables. If you don't see it in the list above, it doesn't exist. 313 (4) In the future the environment variables may go away entirely. 314 It would be a good idea to stop using them now and switch to the 315 command line options. 316 317You may also want to customize other things by editing zippy.c and 318recompiling the program. 319 320===================== 321ICS VARIABLE SETTINGS 322===================== 323 324You need to do the following settings on ICS: 325 326 set highlight 0 <-- I'm not sure this is still needed 327 set oldmatch 0 328 set examine 0 329 330If you want to use the zippyPassword remote-control feature, it's a 331good idea to do the following, so that commands you give Zippy won't 332be truncated because the ICS wrapped a "tell" to a new line: 333 334 set wrap 0 <-- on ICC, or 335 set width 255 <-- on FICS 336 337You will probably want to turn on server-side autoflagging too: 338 339 set autoflag 1 340 341====== 342SIMULS 343====== 344 345It has been discovered that Zippy can play simuls on ICC (but not on 346FICS). If you arrange for Zippy to send the ICC command "simulize" in 347the -zippyGameStart string, it will accept additional games while 348playing. Zippy will use the same engine for every game, so whenever 349it switches opponents, the engine's state will be reset with the "new" 350command. This will of course weaken its play, so don't enable simuls 351if you want your engine to have the highest possible rating. 352 353Zippy was never designed to work with simuls; it just works by 354accident, and it hasn't been tested much. So please report any bugs 355you notice, but don't expect them to be fixed rapidly. 356 357Be sure to use xboard/WinBoard 4.2.4 or later for simuls, because some 358obscure bugs are fixed in that version that affect starting a game in 359the middle (as with resuming from adjournments or switching opponents 360in a simul). 361 362As noted under -zippyPlay above, you should have -getMoveList on to 363ensure that the engine knows the game history after switching boards 364and thus handles draw by repetition and by the 50-move rule correctly. 365It should, however, also work to turn off this option to speed things 366up and reduce network bandwidth, if you don't mind the engine 367occasionally failing to see draw possibilities. Unfortunately, 368though, with Crafty 18.3 (and probably other versions too) as the 369engine, users trying this have experienced Crafty crashes. This looks 370to me like a Crafty bug, but I wasn't able to reproduce it, so it 371remains a mystery. 372 373 374======== 375EXAMPLES 376======== 377 378Here are some small example command lines. You may want to use more 379options; see the man page, info file, or help file, and perhaps the 380FAQ file too. You may want to put the command line into a Unix shell 381script or Windows .BAT file, which is simply a text file of commands. 382On Unix, turn on execute permission for the file (chmod a+x file); on 383Windows, give it the extension .BAT. You can then run it just like an 384ordinary program. Please do not ask me questions about how to make a 385shell script or .BAT file; these are not functions of xboard/WinBoard, 386but basic operating system features that you can learn about from 387introductory books, friends, teachers, or the online help for your 388system. The examples below should be more than enough to get you 389started. 390 391Unix command lines: 392 393# xboard + GNU Chess on chessclub.com 394xboard -zp -ics -icshost chessclub.com -icshelper timestamp \ 395 -zippyPassword beer 396 397# xboard + GNU Chess on freechess.org 398xboard -zp -ics -icshost freechess.org -icshelper timeseal \ 399 400# xboard + Crafty on chessclub.com 401xboard -zp -ics -icshost chessclub.com \ 402 -fd /home/crafty -fcp crafty -icshelper timestamp \ 403 -zippyPassword beer 404 405# xboard + Crafty on freechess.org 406xboard -zp -ics -icshost freechess.org -autoflag \ 407 -fd /home/crafty -fcp crafty -icshelper timeseal \ 408 -zippyPassword beer 409 410Windows command lines: 411 412REM WinBoard + GNU Chess on chessclub.com 413WinBoard -zp -ics -icshost chessclub.com -fcp GNUChess -icshelper timestamp -zippyPassword beer 414 415REM WinBoard + GNU Chess on freechess.org 416WinBoard -zp -ics -icshost freechess.org -fcp GNUChess -icshelper timeseal -zippyPassword beer 417 418REM WinBoard + Crafty on chessclub.com 419WinBoard -zp -ics -icshost chessclub.com -fd C:\Crafty -fcp WCrafty -icshelper timestamp -zippyPassword beer 420 421REM WinBoard + Crafty on freechess.org 422WinBoard -zp -ics -icshost freechess.org -fd C:\Crafty -fcp WCrafty -icshelper timestamp -zippyPassword beer 423