"The bot for all your needs [tm]"

[ home ] [ module tutorial ] [ mailing lists ]

Tutorial on creating modules for the Techbot IRC bot

First, I'll start by answering a few questions that you may have if you haven't talked to us on irc:

What is Techbot?
Techbot is a modular IRC bot written in C, it uses several libraries that you probably wouldn't normally find in an irc bot, the aim of Techbot is to keep the "core" bot as small as possible and to push all the functionality that you might expect into loadable modules.

Why use the <insert library name here>?
There are many reasons for our choosing these libraries:

Writing Techbot Modules
Ok, if you have read this far, you probably want to write a module, so here we go...

First, you need to decide if you want the module to be distributed as part of techbot, or separately, we don't mind either, however, the paths will be slightly different if you choose to distribute separately. For the purpose of this tutorial we are going to assume that you are going to make the module part of techbot (it is easier that way).

Next, after you have checked the source out from cvs, you need to go into the modules directory "techbot/modules/", in here are directories containing existing modules, you will probably recognise "helloworld" as the standard template. Make a directory and copy the "helloworld" source files, Makefile.am and Makefile.in into your new directory. Go through these files and do a global search and replace for helloworld and replace it with <your module name>, for example in vim we would use:

After this has been done, you can actually get round to writing the module, open up your main source file, probably <your module name>.c. In here you will find the example helloworld module.

You will notice that there are a number of skeleton functions, these are called whenever a certain irc callback is received, the table of functions and meanings is printed below:

Function Explaination
botmod_init This is called once when the module is loaded, use it to setup your module.
botmod_maint This is called whenever the bot goes through a maintenence cycle, normally ever 60 seconds.
botmod_save (fixme)
botmod_help (fixme)
botmod_report When this is called, it should send back a pointer to a string containing a report.
botmod_mode This is called whenever a channel or user mode is changed.
botmod_privmsg This is called whenever the bot receives a Private Message.
botmod_chanmsg This is called whenever anyone talks on the channel.
botmod_joinmsg This is called whenever anyone joins the channel.
botmod_partmsg This is called when anyone parts the channel, not to be confused with botmod_quitmsg.
botmod_actionmsg This is called whenever someone does an action (/me) on the channel.
botmod_nickmsg This is called whenever someone changes their nick.
botmod_kickmsg This is called when someone (incl. the bot) is kicked from the channel.
botmod_topicmsg This is called when the topic is changed.
botmod_quitmsg This is called when someone quits irc altogether, not to be confused with botmod_partmsg.
Table 1.1: "Module functions and explainations"

Right, by now, you must be thinking there is nothing to programming a module, you would be right, we have designed the module architecture so that you have to do as little work as possible, neat huh? To prove this, and by popular demand, I will show you some code from our helloworld module and explain how it works: 

void botmod_chanmsg(TechBot *bot, Channel *channel, char *nick, char *msg)
{
        gboolean greeting = FALSE;

        g_debug("chanmsg (%s) received from %s: %s", channel->name, nick, msg);

        /* Does message contain 'hello' or 'hi', and the bot's nick? */

        if(!strstr(msg, bot->nick)) 
	{
                if(!strstr(msg, "hello") || !strstr(msg, "hi"))
		{
                        greeting = TRUE;
                }
        }

        if(!greeting)
        {
                return;
        }

        /* Respond */

        techbot_chanmsg(bot, channel, "Hi there, %s.", nick);
}

When someone talks in the channel, it is passed to the module, and it calls the botmod_chanmsg function, passing the the channel structure and pointers to strings with the nick and message. This function compares the message with the bots current nick and if it is true goes on to compare it with two well known greetings. If it decides that the message is a greeting, then it responds, if not it just returns.

All that remains is to wish you good luck in creating your own module, we hope that you will choose to distribute it with techbot, but don't feel obliged. If you require any further information or you think there is something we have missed out in this tutorial, please let us know either on irc or by email on the mailling list.