Creating new commands

This document covers how to create a new command, which basically means that is it a guide on

1. The perfect function

Define a function that is the same name as the command you want. If you want a command called !!/createcommand, you would write a function like this:

def createcommand():
    return None

This command will do nothing. The function returns a string or None. If a string is returned, the string will be posted to chat. If None is returned, nothing will be posted to chat. You can put anything (read: the thing you want to do with this command) inside the function body.

2. Configuration of the @command()

Supported arguments:

command(privileged=False, whole_msg=False, arity=None, aliases=[], give_name=False, reply=False)

To tweak the settings of your command, you have to edit the parameters inside @command()

3. Post something

To post data that is what you expected, simply execute return "some message"

If you encounter an error, you can raise a CmdException with a string as the error message. The string will be sent to chat. The difference is that with return, the response can be suppressed if the command is issued in “silent mode” (ends with an additional hyphen, e.g. !!/command-). With raise CmdException, the response suppression will be ignored and Smokey will always response with the string in the exception.

def somerandomcommand():
    if True:
        raise CmdException("Error: this error will be fixed in 6 to 8 weeks! HAHA")
    return None

If you want to send a message to all the rooms that Smokey is running in, use tell_rooms:

tell_rooms("A message")

The longhand version of this (which allows additional configuration) is:

tell_rooms(message, (roles to have...), (roles not to have...))

It’s recommended that you send messages to rooms that are interested in debug messages, instead of spamming all rooms. You can use tell_rooms_with:

tell_rooms_with('debug', "A debug message")

You can also use tell_rooms_without to post to all rooms without a specific role:

tell_rooms_without("metatavern", "Tavern on the Meta sucks")