How to write a FICS bot - part V, chatting

Simple tells

Simple tells were already illustrated in second and fourth parts of this tutorial. The bot can issue usual command like

 tell PlayerName You are registered

and the player will see something like

 BotName tells you: You are registered

There are some problems with this approach, though:

• the text is at most 400 characters long,

• it must be given as a single line, but it may be broken into many lines by FICS (depending how is the width variable of recipient set), and then by the interface (depending on the window size), so longer tells easily result in things like:

    BeautifulBot tells you: You already played your game in this round
    of the
    \ tournament. Your next game will be scheduled at 2008-11-20, visit
    the
    \ pairings page for details.
    

• FICS delays the communication if somebody issues many tells in a short time (Your communication has been queued for 2 second(s).), this in particular defeates the idea of splitting longer information into many short tells.

To summarize: tell-s are good for short notifications, command confirmations and similar messages. And only for them.

Special content of simple tells

Some interfaces (most notably BabasChess) handle texts enclosed in double quotes in a special way - make them highlighted and clickable. Example use of this feature:

tell PlayerName To join, issue "tell BeautifulBot join" command

URLs (webpage addresses) may be highlighted and clickable even without such bracketing (again, this is an interface feature).

FICS does not handle non-ASCII characters, so one can't use ą or ä in tells. People have been discussiong some workarounds. I like the idea of using HTML-like entity encoding (´, &lstroke;, maybe also just ᅽ), but until some mainstream client decides to implement this, this is just an idea.

BabasChess introduced also some special markers in tells and game comments. It sends things like !BCS->(something) and recognizes them - to play specific sounds, or to paint arrows and circles on the examined board.

Messages

Messages may be sent to players who are not logged in at the moment. They are persistent (kept until deleted by the recipient). Therefore they are suitable for things like password reminders, game announcements, useful web links etc.

I haven't given an example of message sending code, but there is not much difference comparing to tells. Replace tell with message and you are (mostly) done. For example:

 message PlayerName New superleague website: http://superleague.com

The same limits as in case of tells apply - at most 400 characters, no control over linebreaks. There is also (new) limit of messages sent to one player within one day. Example information (I got it after sending 20 messages to one recipient):

 You cannot send any more messages to ... at present (24hr limit reached).

So don't plan to send too many messages.

See the limits command for this number and some other limits.

Some players read messages by email (those, who enabled the mailmess variable), others read them within their interface. Keep it in mind while writing a text.

In case recipient's message box is full, he or she won't obtain the message (unless it is forwarded by email). FICS informs about this in the reply to the message command, so it may make sense to grab and analyze it. The good replies are:

 The following message was sent and emailed to ....

and

 The following message was sent to ....

Long tells

If you happened to use mamer, relay, or watchbot you likely spotted that they are able to offer different kind of tells. For example, here is what mamer replies to td lt -j:

:mamer's tourney list:
:
:+----------------------------------------------------------------------------+
:| ID   | Status    | Manager           | Type               | Start Date     |
:|------|-----------|-------------------|--------------------|----------------|
:| 30   | +started< | blkmagic          | 60 15 r SS\4       | 2008.1001.1320 |
:| 31   | +started< | blkmagic          | 60 15 r SS\4       | 2008.1001.1321 |
:+----------------------------------------------------------------------------+

One uses qtell command to use such a format. Something like:

qtell Player mamer's tourney list:\n\n+----------- (...)

Here you face the important problem. This command is restricted. Neither guest, nor even normal account, is allowed to use it. qtell is available only to accounts flagged as TD. So, to use qtell one must ask FICS staff for this privilege.

TD privilege means far more. Apart from qtell-s, it enables commands like rmatch (starting the game on behalf of other player) or robserve (make other player start observing something). Think so: if you got TD, you can do everything mamer or relay do.

But more power means FICS staff is more careful while granting this privilege. Usually you should have something working and useful before asking for TD.

Going back to the technical details: qtell is issued similarly to tell, but one can specify linebreaks (via \n - backslash and n). Still, the text of single qtell can't be longer than 1024 characters (Maximum communication size from limits), so bots sometimes need to split the text into a few qtell-s issued one by one.

In WatchBot I use the following code snippet to issue qtell-s:

def qtellTo(self, who, what):
    """
    Issue qtell to the player who. What is the text to be sent,
    given as an array of lines.
    """
    if len(what) <= 10:
       return self.runCommand(
          "qtell %s %s" % (who, "\\n".join(what)))
    else:
       return self.runCommand(
          "qtell %s %s" % (who, "\\n".join(what[:10]))).addCallback(
          lambda x, who, what: self.qtellTo(who, what), who, what[10:])

The idea is to split the whole text into chunks of no more than 10 lines (safe approximation to keep below 1024 characters limit), then send as many qtells as is necessary. This is an old code, therefore I use addCallback instead of inlineCallbacks trick.

FICS does not show who authored qtell (this is done purposedly, to allow joining a few qtells into the single, bigger message). To avoid confusion always start with some title and mention the bot name (like mamer did above).

Also, don't send a lot of lines at once. Not every interface has good support for console scrolling. It may make more sense to send 20-30 lines, then handle tell MyBot more.

Worth remembering: while BabasChess pops up the chat box and emits sound on usual tell, qtell-s are shown only on the console and there is no sound signal. Some novice players may miss them.

Alternatives

What to do if you don't have TD, but need to provide longer texts to the players? Use some other communication channel. Send email, chat via online messenger, or (the most natural option) provide the link to the webpage.

I will discuss it a bit deeper in some future chapter.