zippy.README

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