API documentation

First of all, this is very simple template to make scripts (save is as [pluginName].coffee). Note that @respond returns true. If plugin will return this value, it means that execution of all following scripts should stop.

Every object in exports object which is not prepended with _ or $ can be ran easily by just activating it normally. _ is reserved for special purpose functions. Currently, we have _init function (ran at start) and _else function which catches every single message (avoid it unless you have to use it as usage of it as it comes with big performance cost).

exports.hello = ->
    @respond "Hello, world!"

Scripts can be also made in pure JavaScript. While I don't have any examples currently, it's as easy as saving it as [pluginName].js. Scripts for JavaScript have very similar construction, but you should be careful, as unlike CoffeeScript, JavaScript will NOT automatically return true (return value of this.respond). The script below does this same thing as script above.

exports.hello = function () {
    this.respond('Hello, world!');
    // JavaScript doesn't return return value of last expression
    return true;
};

Functions of this object

Respond function

respond: (message, me = false) ->

This function takes message arguments and returns it to whoever sent you a message. If you will set me to true, message will be sent in third person (for example CTCP ACTION in case of IRC which would give results similar to * Bot does something in most IRC clients).

Send function

send: (message, channel, me = false) ->

This function will send message to channel with optional third person (me). Note that in many protocols it's synonym for pm, but you should use send for channels and pm for private messages, otherwise you can have problems in case there are deeper differences between channels and private messages (For examples, Stack Exchange chat system where both channels and users use numeric IDs (Please take note that Stack Exchange chat might be implemented it future)).

Note that this can throw exception if you're on protocol which only has private messages (most instant messaging systems).

Private message function

pm: (message, user, me = false) ->

Just like @send, this will send message to... user. As always, you can specify third person (me). Warnings of @send functions apply in this function too. Always use correct function, instead of depending on just works.

Join function

join: (id) ->

This is obviously join function. It has only one argument, which is id or channel name depending on the protocol. If protocol doesn't support channels, it may throw exception.

Part function

part: (id) ->

Exact opposite of @join function. When @join joins channel, @part leaves it. As always, it may throw exception.

Nick function

nick: (nick) ->

This function will change nick if it is possible, but be careful because many protocols don't make changing nicks easy (IRC is exception). So look out for exception, it's very likely that you will see those...

Variables

@message

@message =
    # Message which was sent to your bot
    text: '++command value'
    # Name of function (in this example, ++ is prefix)
    command: 'command'
    # Value which is sent to function
    value: 'value'
    # Channel to which message was sent. May not exist.
    channel: '#example'
    # Nick which sent this message.
    nick: 'MyGoodNick'
    # Is whoever sent this message owner?
    owner: false
    # Type of message. In most cases, this would be 'private' or 'message',
    # but it might be some implementation specific type, such as... 'notice'.
    type: 'message'

You like messages, do you? This object represents your message. It has few nice properties, but you will be probably interested only with @message.value, unless you have specific needs. Certain protocols might specify other types, for example IRC gives @message.fullhost, @message.host, @message.user and @message.address.

@serverName

Name of current server specified by user.

@config

Configuration of current server.

@channels

Object which has name of channel as key and array of nicks as value.

@storage

Storage for your plugins. Please use @storage[pluginName] in order to access it, unless you want to break other plugins or read data of other plugins. Note that technically you can use static variables, but they are shared between servers, so you should avoid those.

@commands

List of commands which this bot understands.

@_

Storage for current channel. It shouldn't be modified directly, instead you should modify properties.

@$

Storage for current server. As with @_, don't modify it directly. If you need storage for whole bot, use static properties.