zippy.README

   1 Zippy README file
   2 For version xboard/WinBoard 4.2.4 and later only
   3 -----------------------------------------------------
   4
   5 Zippy is a program that lets GNU Chess act as a computer player on an
   6 Internet Chess Server.  It also works with Crafty.  Zippy is
   7 unsupported, experimental code.
   8
   9 Zippy is based on XBoard, a graphical interface to GNU Chess and to
  10 the ICS for the X Window system on Unix.  Zippy consists of exactly
  11 the same code as XBoard, plus one extra module that ties together the
  12 otherwise-separate functions of talking to GNU Chess and talking to
  13 the ICS.  Zippy is included in the XBoard distribution.
  14
  15 There is also a version of Zippy that is based on WinBoard, a port of
  16 XBoard 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
  18 3.5 and later, the Zippy code is included in WinBoard.exe.
  19
  20 If 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
  23 might take weeks for me to get back to you, or I might answer right
  24 away.  Try to solve problems yourself before you mail me about them.
  25 Try asking someone who is actively running a Zippy-based player on ICC
  26 or 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
  29 is a computer, so that it gets put onto the computer list, and follow
  30 the ICS computer policies.  On ICC these are in "help computer"; read
  31 this file and abide by what it says.
  32
  33 - If you want to interface some other chess program to ICS, feel free
  34 to start with this code.  Some documentation is in the file
  35 engine-intf.html in the distribution.
  36
  37 - Please do not use the -zt flag to have your program shout Zippy the
  38 Pinhead sayings (or other things that my Zippy shouts).  One pinhead
  39 per server is plenty, and I'd like to keep the franchise.  Feel free
  40 to use -zt to have your program shout some other kind of sayings if
  41 you like.  Some of the jokes that Zippy shouts on ICC came from
  42 ftp://ftp.cco.caltech.edu/pub/humor.  The poetry came from Project
  43 Gutenberg; try http://www.cs.cmu.edu/Web/booktitles.html as a starting
  44 point.  You might find other suitable material at these sites.  Prose
  45 tends to work poorly because it is dull when shouted in isolated
  46 250-character chunks.
  47
  48         --Tim Mann
  49           http://www.tim-mann.org/chess.html
  50
  51 * * *
  52
  53 Unix: To build the Zippy version of xboard, on most systems just do:
  54         configure --enable-zippy
  55         make
  56
  57 Windows: WinBoard.exe (versions 3.5 and later) includes the Zippy
  58 code.  There is no longer a distinct WinZippy.exe.
  59
  60 In both xboard and WinBoard, the Zippy features are off by default.
  61 You can activate them with two new resources/command line options, and
  62 you can fine-tune them with some new environment variables, all
  63 described below.
  64
  65 You will probably want to make a shell script or Windows .BAT file
  66 that sets the environment variables you want to use and invokes Zippy
  67 with the right command line options for your situation.  Some examples
  68 are at the bottom of this file.
  69
  70 If you have problems building or running Zippy, see the rest of the
  71 xboard documentation: INSTALL documents the configure program, while
  72 READ_ME and xboard.man (or xboard.txt) document xboard itself, and
  73 WinBoard.hlp documents WinBoard.  FAQ answers some frequently asked
  74 questions.  The file engine-intf.html contains some information about
  75 the interface between xboard/WinBoard and GNU Chess (or other chess
  76 engines).
  77
  78 ===========
  79 NEW 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 =====================
 293 ENVIRONMENT 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
 317 You may also want to customize other things by editing zippy.c and
 318 recompiling the program.
 319
 320 =====================
 321 ICS VARIABLE SETTINGS
 322 =====================
 323
 324 You 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
 330 If you want to use the zippyPassword remote-control feature, it's a
 331 good idea to do the following, so that commands you give Zippy won't
 332 be 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
 337 You will probably want to turn on server-side autoflagging too:
 338
 339     set autoflag 1
 340
 341 ======
 342 SIMULS
 343 ======
 344
 345 It has been discovered that Zippy can play simuls on ICC (but not on
 346 FICS).  If you arrange for Zippy to send the ICC command "simulize" in
 347 the -zippyGameStart string, it will accept additional games while
 348 playing.  Zippy will use the same engine for every game, so whenever
 349 it switches opponents, the engine's state will be reset with the "new"
 350 command.  This will of course weaken its play, so don't enable simuls
 351 if you want your engine to have the highest possible rating.
 352
 353 Zippy was never designed to work with simuls; it just works by
 354 accident, and it hasn't been tested much.  So please report any bugs
 355 you notice, but don't expect them to be fixed rapidly.
 356
 357 Be sure to use xboard/WinBoard 4.2.4 or later for simuls, because some
 358 obscure bugs are fixed in that version that affect starting a game in
 359 the middle (as with resuming from adjournments or switching opponents
 360 in a simul).
 361
 362 As noted under -zippyPlay above, you should have -getMoveList on to
 363 ensure that the engine knows the game history after switching boards
 364 and thus handles draw by repetition and by the 50-move rule correctly.
 365 It should, however, also work to turn off this option to speed things
 366 up and reduce network bandwidth, if you don't mind the engine
 367 occasionally failing to see draw possibilities.  Unfortunately,
 368 though, with Crafty 18.3 (and probably other versions too) as the
 369 engine, users trying this have experienced Crafty crashes.  This looks
 370 to me like a Crafty bug, but I wasn't able to reproduce it, so it
 371 remains a mystery.
 372
 373
 374 ========
 375 EXAMPLES
 376 ========
 377
 378 Here are some small example command lines.  You may want to use more
 379 options; see the man page, info file, or help file, and perhaps the
 380 FAQ file too.  You may want to put the command line into a Unix shell
 381 script or Windows .BAT file, which is simply a text file of commands.
 382 On Unix, turn on execute permission for the file (chmod a+x file); on
 383 Windows, give it the extension .BAT.  You can then run it just like an
 384 ordinary program.  Please do not ask me questions about how to make a
 385 shell script or .BAT file; these are not functions of xboard/WinBoard,
 386 but basic operating system features that you can learn about from
 387 introductory books, friends, teachers, or the online help for your
 388 system.  The examples below should be more than enough to get you
 389 started.
 390
 391 Unix command lines:
 392
 393 # xboard + GNU Chess on chessclub.com
 394 xboard -zp -ics -icshost chessclub.com -icshelper timestamp \
 395     -zippyPassword beer
 396
 397 # xboard + GNU Chess on freechess.org
 398 xboard -zp -ics -icshost freechess.org -icshelper timeseal \
 399
 400 # xboard + Crafty on chessclub.com
 401 xboard -zp -ics -icshost chessclub.com \
 402     -fd /home/crafty -fcp crafty -icshelper timestamp \
 403     -zippyPassword beer
 404
 405 # xboard + Crafty on freechess.org
 406 xboard -zp -ics -icshost freechess.org -autoflag \
 407     -fd /home/crafty -fcp crafty -icshelper timeseal \
 408     -zippyPassword beer
 409
 410 Windows command lines:
 411
 412 REM WinBoard + GNU Chess on chessclub.com
 413 WinBoard -zp -ics -icshost chessclub.com -fcp GNUChess -icshelper timestamp -zippyPassword beer
 414
 415 REM WinBoard + GNU Chess on freechess.org
 416 WinBoard -zp -ics -icshost freechess.org -fcp GNUChess -icshelper timeseal -zippyPassword beer
 417
 418 REM WinBoard + Crafty on chessclub.com
 419 WinBoard -zp -ics -icshost chessclub.com -fd C:\Crafty -fcp WCrafty -icshelper timestamp -zippyPassword beer
 420
 421 REM WinBoard + Crafty on freechess.org
 422 WinBoard -zp -ics -icshost freechess.org -fd C:\Crafty -fcp WCrafty -icshelper timestamp -zippyPassword beer