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
configure_custom_commands
,configure_custom_commands_acl
,list_custom_commands
(and oneuse_??_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.
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.