2. Development: Start Here

Note: This tutorial covers the OLD bot, version 6.x. For the current 7.x bot see here

Goals

0. Create an extension
1. Listen to chat in the server
2. Send chat messages

Distribution note

Extensions can be loaded from anywhere, so long as you know the URL. However, to create an extension which can automatically launch when the bot is loaded, you need an account on blockheadsfans.com/messagebot. This tutorial will assume that you have an account there.

Tutorial

This tutorial assumes you have a working knowledge of JavaScript. If you do not, much of the code found here will be confusing. Now, onward!

The first step when creating an extension should be to decide what you want to do, in this case, given our goals, we will be creating an extension that acts much like a simplified version of the bot's built in triggers.

When someone says /marco in chat, our extension should respond with polo.

Simple enough, let's begin! Start by creating an extension object. It is important that the MessageBotExtension function is passed the name of the variable of the extension.

var marcopolo = MessageBotExtension('marcopolo');

To avoid cluttering the global scope with variables which should only be used by this extension, all initialization will be performed in an IIFE.

var marcopolo = MessageBotExtension('marcopolo');

(function(ex) {
    //todo
}(marcopolo));

Let's start with listening to chat. To do this, we need to create a function which takes two to three arguments, name, command, and possibly args. In this case we don't need any arguments so we can leave off args.

var marcopolo = MessageBotExtension('marcopolo');

(function(ex) {
    function marcoListener(name, command) {
        //todo
    }
}(marcopolo));

Now we have to tell the bot to call this function when someone says something in chat. This can be accomplished by listening to a key through the hook interface on the bot. (This sounds more complicated than it is, really. Just stick with me, or if you must, give this a quick read) Looking at the documentation, we see that the key world.command will work perfectly for this extension as it is checked when someone says something that starts with a slash. Lets update our code so that the function is called.

var marcopolo = MessageBotExtension('marcopolo');

(function(ex) {
    function marcoListener(name, command) {
        //todo
    }

    ex.hook.listen('world.command', marcoListener);
}(marcopolo));

Okay, now that that's done, let's respond to /marco. To do this we call the ex.bot.send(message) function.

Advanced note: Alternatively, we could have called ex.api.send(message), but this is generally a bad idea for extensions as it can cause a race condition which creates issues where multiple messages can be sent together. Additionally, error handling is not done by the bot if you use ex.api.send(message).

var marcopolo = MessageBotExtension('marcopolo');

(function(ex) {
    function marcoListener(name, command) {
        if (command.toLocaleLowerCase() == 'marco') {
            ex.bot.send('Polo!');
        }
    }

    ex.hook.listen('world.command', marcoListener);
}(marcopolo));

At this point, you have code which will run. Go give it a shot! Start the bot, open your developer tools (Try pressing F12), and paste the above code into the console tab. Then type /marco in chat. If all went well, you will get "Polo!" as a response.

---

Though the extension works right now, it is not complete. No one but you can use it! To publish it so others can install it, just a few more things need to be added. First, let's add an uninstall function. This function should remove any hook listeners, remove any tabs added to the bot, and remove any stored data from the browser's storage. In this extension, we just need to remove the listener.

var marcopolo = MessageBotExtension('marcopolo');

(function(ex) {
    function marcoListener(name, command) {
        if (command.toLocaleLowerCase() == 'marco') {
            ex.bot.send('Polo!');
        }
    }

    ex.hook.listen('world.command', marcoListener);

    ex.uninstall = function() {
        ex.hook.remove('world.command', marcoListener);
    }
}(marcopolo));

Almost done! By default, extensions will be run once. While this is fine for some extensions, we want this extension to be automatically loaded whenever the bot is loaded. This is easy to do with a call to ex.setAutoLaunch(shouldAutoload)

var marcopolo = MessageBotExtension('marcopolo');

(function(ex) {
    function marcoListener(name, command) {
        if (command.toLocaleLowerCase() == 'marco') {
            ex.bot.send('Polo!');
        }
    }

    ex.hook.listen('world.command', marcoListener);

    ex.uninstall = function() {
        ex.hook.remove('world.command', marcoListener);
    }

    ex.setAutoLaunch(true);
}(marcopolo));

Congratulations! You have now created a basic extension which can be published. To publish an extension go to blockheadsfans.com/messagebot and log in. Now go to the Dashboard page and click New Extension. Enter a name and description of your choice. The extension ID should be the same as the variable name used to create your extension. If it is different then your extension won't autoload correctly. In this example it would be marcopolo. You can see an example of this here.

Once you create an extension you can load it into your bot by going to the extensions page, clicking on "Load By ID/URL", and entering the ID you chose. If you want the extension to be listed, please contact me through the Blockheads Forums here.