Writing your first command plugin

This page contains a tutorial on creating a command plugin.

Example command

The command hook can be used to register a command in CloudBot.

Here's an example command which will return the input given to it, added to itself.

from cloudbot import hook

@hook.command()
def echo(text):
    return text + " " + text

How you can use commands

This defines a command that replies with its input, added together. The @hook.command() tells CloudBot that the function should be registered as a bot command.

Any bot command can be called from an irc channel in the following ways:

- .<command> <arguments>
- TestBot: <command> <arguments>
- TestBot; <command> <arguments>
- TestBot, <command> <arguments>

This is assuming that the bot's name is TestBot, and that the command_prefix is set to '.' in the bot's config.

A bit more on what the 'echo' function actually does

If you look at the 'echo' command, you can see that it's pretty simple. It accepts a variable, text, and it returns text + " " + text.

The 'text' variables represents the arguments for that are used with the command. Then CloudBot will take anything returned by the function, and spit it back into the irc channel.

Here's an example of what would happen with this 'echo' plugin:

<Luke> TestBot, echo hi
<TestBot> (Luke) hi hi

Other ways you can use it

The 'echo' command is called with 'TestBot, echo', just because the function name is 'echo', however you can pass @hook.command a different name if you wanted to, or even multiple names.

Take this plugin for example:

from cloudbot import hook


@hook.command("simpleecho")
def simple(text):
    return text + " " + text

@hook.command("complexecho1", "com")
def complex(text):
    return text + " " + text + " " + text

That plugin adds two command, one called 'simple' and one 'complex'. However, because @hook.command was called with the "simpleecho" parameter, the command will be called with TestBot, simpleecho, not TestBot, simple.

The same with 'complex'. You can call it with TestBot, complexecho1, or TestBot, com.