Custom Commands

As the name implies, this plugins allows you to define your own, channel-wide commands. As of now, each command can respond with a fixed text and can be granted to users/groups individually.

Some other plugins allow their commands to be overwritten with custom commands of the same name. For example, you can create your own, custom !ryder command with your own response. If someone uses the command, your custom response will be used.
Note that not all plugins allow this kind of treatment. See each plugin's documentation, it will state if overwriting is supported or not.

Synopsis

Identifier:

custom_commands

Permissions:

configure_custom_commands, configure_custom_commands_acl, list_custom_commands (and one use_??_cmd permission for each custom command)

Commands:

!cc_set, !cc_get, !cc_del, !cc_list, !cc_allow, !cc_deny

Setup

Simply enable the plugin using the global command !k_enable:

#tester_mantester_man: !k_enable custom_commands
kabukibot: tester_man, the plugin "custom_commands" has been enabled.

Create / Update Commands

In order to create a new custom command, the !cc_set command is used. It needs to know the command name (only letters, numbers and underscores are allowed) as well as the response text. Give the command name first and then the response text (everything after the command name is considered the desired response text).

The command name is always automatically lowercased.

#tester_mantester_man: !cc_set mycommand This is the response text!
kabukibot: tester_man, command !mycommand has been created.

Updating an existing command works the same way. !cc_set will simply overwrite the response text.

#tester_mantester_man: !cc_set mycommand This is the NEW response text!
kabukibot: tester_man, command !mycommand has been updated.

New commands have no permissions set for them yet. This means that, like with everything else, only the channel owner and the bot operator are allowed to use the command.

#tester_mantester_man: !mycommand
kabukibot: This is the NEW response text!

To make the command usable for others, you have to grant permissions for it, just like you grant permissions for everything else. See further down for more information on permissions.

List Commands

To get a list of all defined custom commands, use the !cc_list command.

#tester_mantester_man: !cc_list
kabukibot: tester_man, custom commands are: !mycommand, !myothercommand, !faq, !foo

Note that this always lists all commands, even those the sender might not have access to.

Delete Commands

To remove an existing custom command, use !cc_del and give the command name.

#tester_mantester_man: !cc_del mycommand
kabukibot: tester_man, command !mycommand has been deleted.

All permissions that have been set for the deleted command are also deleted. So when you re-create the command, you will also have to re-create all permissions.

Deleting a command does not require that the sender (the person doing the !cc_del ... command) has permissions on the deleted command.

Command Permissions

Users with the configure_custom_commands_acl permission can control who can use a custom command. The plugin offers two commands for this purpose: !cc_allow and !cc_deny. They work exactly like their global pendants !k_allow and !k_deny.

To allow a user or a group to use a command, use !cc_allow, the name of the command and then give all the users/groups who shall be allowed to use it.

#tester_mantester_man: !cc_allow mycommand $mods,$subs
kabukibot: tester_man, granted permission "use_mycommand_cmd" to $mods, $subs.

The response contains this use_mycommand_cmd permission. If you want to know why it contains this permission and not the command name, read the behind the scenes section further down.

Everything that applies to !k_allow also applies to !cc_allow: Multiple calls are allowed and add up and you can grant to any number of users/groups.

To revoke access again, use !cc_deny:

#tester_mantester_man: !cc_deny mycommand $subs
kabukibot: tester_man, revoked permission "use_mycommand_cmd" from $subs.

Backstory

Why are there two extra commands for managing permissions?

Imagine a high-volume stream doing an intense speedrun. Chat goes crazy like always and moderators do their best to keep it sane. To do so, they want to create a custom command named !uberglitch, explaining an important strategy. We assume they have been granted the configure_custom_commands earlier by the channel owner.

That means that now, in the heat of the stream, they can create the !uberglitch command. Great!

But now they're stuck. If no one can configure that this new command can be used by anyone (because only the channel owner can use !k_allow), then the command is uesless. The channel owner would have to grant permissions during a cutscene, which is definitely not something he/she should be wasting brain cycles on in that moment.

For this reason, it must be possible for others in the chat to control permissions for these custom commands. That is why there are two extra commands. They merely act as "proxies" to the same permission logic as !k_allow et al. use.

Permissions

Use the global commands !k_allow and !k_deny to control the regular permissions for this plugin.

configure_custom_commands

Users with this permission can create, update and delete custom commands. This is something either moderators or a few trusted people should be allowed to do.

configure_custom_commands_acl

Users with this permission can set permissions for custom commands. It's highly recommended to grant this only to very few people, if any.

list_custom_commands

Users with this permission can list all existing commands. It's usually a good idea to allow moderators to do this, as well as all the people who can actually use the custom commands. Adjust if people are spamming the command.

Examples:

#tester_mantester_man: !k_allow configure_custom_commands $mods
kabukibot: tester_man, granted permission "configure_custom_commands" to $mods.

#tester_mantester_man: !k_allow configure_custom_commands_acl my_mom
kabukibot: tester_man, granted permission "configure_custom_commands_acl" to my_mom.

#tester_mantester_man: !k_allow list_custom_commands $mods,$subs
kabukibot: tester_man, granted permission "list_custom_commands" to $mods, $subs.

Behind the Scenes

As seen above, when using the !cc_allow and !cc_deny commands, Kabukibot responds with use_mycommand_cmd names. This is because behind the scenes, the two commands are only proxies to the normal permission system (the ACL) that is being used everywhere else in Kabukibot to control access to certain functionalities.

So when someone is granting permissions on the !mycustomcmd command, Kabukibot handles this as granting the use_mycustomcmd_cmd permission to someone.

This also means that the channel owner can manage permissions for custom commands in two ways: He can either use the recommended !cc_allow <command> command or use the global !k_allow command. The following two examples are equivalent:

#tester_mantester_man: !cc_allow mycustomcmd $mods
kabukibot: tester_man, granted permission "use_mycustomcmd_cmd" to $mods.

#tester_mantester_man: !k_allow use_mycustomcmd_cmd $mods
kabukibot: tester_man, granted permission "use_mycustomcmd_cmd" to $mods.

Examples

Create a new, mod-only command.

#tester_mantester_man: !cc_set mycmd This is my command.
kabukibot: tester_man, command !mycmd has been created.
tester_man: !cc_allow mycmd $mods
kabukibot: tester_man, granted permission "use_mycmd_cmd" to $mods.

Create a new command that everyone can use.

#tester_mantester_man: !cc_set mycmd This is my command.
kabukibot: tester_man, command !mycmd has been created.
tester_man: !cc_allow mycmd $all
kabukibot: tester_man, granted permission "use_mycmd_cmd" to $all.

Setup the plugin so that mods can manage the commands on their own, including setting permissions for commands.

#tester_mantester_man: !k_allow configure_custom_commands $mods
kabukibot: tester_man, granted permission "configure_custom_commands" to $mods.
tester_man: !k_allow configure_custom_commands_acl $mods
kabukibot: tester_man, granted permission "configure_custom_commands_acl" to $mods.
tester_man: !k_allow list_custom_commands $mods
kabukibot: tester_man, granted permission "list_custom_commands" to $mods.