Fifth article of the FICS bot writing tutorial. In this chapter, I am to discuss different methods a bot may use to communicate with players.
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.