Getting Started

Foreward

In this tutorial, we will be creating a bot that responds to a !givemeblt command. This command will give the requesting user a juicy BLT for their troubles.

From this, you will learn a few useful things:

How to install Tennu
How to create a plugin with commands
How to start your bot

Note: Tennu is beta-quality software. There are rough edges, and updates will often bring backwards-incompatible changes. Be prepared to either stay on the version you are using, or to change your code when updating. Likewise, Tennu is not feature complete.

Installation

Tennu is a Node.js framework. You must have Node.js installed to use Tennu.

Create a new Node.js project. If you've never done this before, here is a simple process for doing so:

Create a directory to store your project.
Open up the directory in your console.
Type npm init and answer its questions.
Type npm install tennu --save.

Your project should now have a package.json file. We will be adding two more items:

config.json: All configuration data for your bot will be located in this file.
tennu_plugins: A directory that will contain all of your custom plugins.

Configuration

We will start with the configuration file. Take this JSON, and save it in config.json.

{
    "server": "irc.your-network.net",
    "password": null,
    "port": 6667,
    "nicknames": ["BLTBot"],
    "username": "blt",
    "realname": "BLTBot in tennu",
    "channels": ["#chan"],
    "nickserv": "nickserv",
    "auth-password": null,
    "plugins": ["blt"],
    "command-trigger": "!",
    "disable-help": false
}

You will want to change these values for your bot, specifically `server` and `channels`.

You can have your bot identify to services (the service named by `nickserv`) by setting the `auth-password` option to the password. You must first register the nickname on the server. See here for more details.

If you want the commmand trigger to be a different character, say @ instead of !, change the `command-trigger` property.

The plugins property already contains a plugin, blt. We haven't written it yet, but this will be its name. Any plugins you want to load, including their dependencies, must be listed in this array, not counting Tennu's default plugins which provide the base functionality of the bot.

Writing the BLT Module

In the previous section, we named the plugin BLT. As such, our plugin will be located at tennu_plugins/blt.js.

Here are the contents of tennu_plugins/blt.js.

var BLTPlugin = {
    init: function (client, imports) {
        return {
            handlers: {
                '!givemeblt': function (command) {
                    client.act(command.channel, 'gives a juicy BLT to ' + command.nickname);
                }
            },

            help: {
                'givemeblt': [
                    'givemeblt',
                    ' ',
                    'Gives the requestor a juicy BLT.'
                ]
            },

            commands: ['givemeblt']
        };
    }
};

module.exports = BLTPlugin;

We send an action to the server in the channel the command came from giving the BLT to the nickname the command originated from.

If you have never used Node.js before, the final line may confuse you. It just means that the Node module is exporting the object at BLTPlugin. If it was not there, Tennu (or any node module) would not be able to access the plugin.

Given this example, every Tennu Plugin file should look minimally like this:

// Initialization of the node module.

var TennuPluginName = {
    init: function (client, imports) {
        // Initialization of the plugin.

        return {
            exports: {
                // Exported properties.
            },

            handlers: {
                '!command': function (command) {
                    // Handle the command
                }
            },

            help: {
                'command': [
                    '!command &lt;command&gt;',
                    ' ',
                    'Help info about command.'
                ]
            },

            commands: ['command']
        };
    }
};

module.exports = TennuPluginName;

Inside a plugin's source code, the command trigger is always "!". Do not change it. Changing the command trigger in config.json is sufficient.

The Tennu Plugin Factory is an object with a single property, init. This property contains a function that takes two values, client and imports. The client is the reference to Tennu, and your way of accessing all of the functionality the library provides outside of the hooks described here. The imports object contains the exports properties of plugins that you require.

The init function returns an object, known as the plugin instance, with various properties, all optional:

exports: Values that are passed to other plugins when they require your plugin.
handlers: This is an object where the property names are the message and command types to listen to, and the functions are the handlers for that message or command type. To distinguish between message and commmand types, commands are prefixed with a `!`. This prefix is separate from the bot's command prefix set in the configuration object.
help: This is a hook for the help plugin to provide help for your commands and other topics. Note the usage of instead of a hard-coded command handler here.
commands: This is also a hook for the help plugin to list the commands provided by your bot.
hooks: Mentioned here for completeness, see hooks.

Comparing this to our bot, our bot does not export any values, and has one command handler that is documented. It does not do any special initialization.

Running Your Bot

Tennu comes with a command line utility for starting bots.

From the command line, in your project directory, utter this incantation:

./node_modules/.bin/tennu config.json -v

This command says run your tennu bot with the configuration located at config.json with verbose output.

If you want your bot not to log to the console, leave off the -v flag.

For extra utility, put this command into the scripts property of your package.json file.

{
    // ...
    "scripts": {
        "start": "tennu config.json -v"
    }
}

Now you can just type npm start to start your bot.