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.
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
widthvariable 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
\ tournament. Your next game will be scheduled at 2008-11-20, visit
\ 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.
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
ᅽ), 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 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
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.
limitscommand for this number and some other limits.
Some players read messages by email (those, who enabled the
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 ....
The following message was sent to ....
If you happened to use
watchbot you likely spotted
that they are able to offer different kind of tells. For example, here
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 |
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
rmatch (starting the game on behalf of other player)
robserve (make other player start observing something). Think so:
if you got
TD, you can do everything
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
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
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:
"qtell %s %s" % (who, "\\n".join(what)))
"qtell %s %s" % (who, "\\n".join(what[:10]))
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
addCallbackinstead 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
qtell-s are shown only on the console and there is no sound signal.
Some novice players may miss them.
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.