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:

  1. How to install Tennu
  2. How to create a plugin with commands
  3. 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:

  1. Create a directory to store your project.
  2. Open up the directory in your console.
  3. Type npm init and answer its questions.
  4. Type npm install tennu -g. You may have to prepend with sudo.

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
Your plugins will be located in this directory.

If you can't install Tennu globally, you can also install it locally, without the -g flag. If you plan on distributing your bot to others, you should install it locally anyways.

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,
    "nickname": "BLTBot",
    "username": "blt",
    "realname": "BLTBot in tennu",
    "channels": [],
    "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. The only exception are the plugins built into Tennu itself:

Server
Exposes functions that give information about the server.
Action
Coming in Tennu 0.10.0, this plugin provides the actions your bot uses to do things on the server. These commands are also available on the client object.
User
Exposes functions that give information about the server's users.
Channel
Exposes functions that give information about the server's channels.
Help
Controls the commands !help and !commands

Most of these plugins currently expose no functionality.

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: {
                'command': [
                    '!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 other node module) would not be able to access the plugin.

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

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

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

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

            help: {
                'command': [
                    '!command <command>',
                    ' ',
                    'Help info about command.'
                ]
            },

            commands: ['command']
        }
    }
};

module.exports = TennuModuleName;

The Tennu plugin 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. This plugin does not require any other plugins, so it is an empty object.

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 messages and command types to listen to, and the functions are the handlers for that message or command type.
help
This is a hook for the help plugin to provide help for your commands and other topics.
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:

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.

If you plan on distributing your bot, you should run the following shell command:

npm install --save tennu

This will put a local copy of tennu into node_modules/ and add it to the dependencies object in the package.json file.