PluginPermissions

Plugin Permission API

Twasi-core wants to make your life easy, and therefore comes with an easy to use and highly configurable permission system.

Brief declaration of the entities

Group

Group defines the basic connection between permission keys and users.

Every group has:

• A list of predefined groups
• A list of excluded members (if you want to use predefined groups but explicitly exclude some users)
• A list of members
• A list of permission keys
• A list of parent groups
• A name

Default Groups

There are two default groups already created.

Default

One group is called default. Everyone is in the group default (except when the user is explicitly excluded).

Moderators

The other group is called moderators. Moderators should have access to the bot's moderation functions. It consist of your twitch moderators per default.

Member

A member is basically a twitch account, connected using the unique twitch id.

Predefined Group

A predefined group is a group that is defined by twitch, like mods or subs.

Permission Key

A permission key is a string splitted by dots. Every action in your plugin should have an own key.

Basic example: Commands plugin

Example of keys used by the default commands plugin:

• commands.moderation.add
• commands.moderation.remove
• commands.moderation.edit
• commands.all.list
• commands.all.execute

As you can see, the keys are already split up to something like groups. This makes it easier to assign them to a real group (using wildcards). To continue with our example, we would adapt the following groups:

Default

Everyone should be able to list and execute all commands. Therefore, the already created group default will get this permission key assigned:

commands.all.*

The wildcard signals to include all keys that start with commands.all. Therefore all users will be able to list and execute commands.

Moderators

All moderators should be able to create, update and delete commands. We can also use wildcards here:

commands.moderation.*

This is exactly what the commands plugin does on installation. It adds the keys to the default groups.

Integrating your own plugin

Now you know how the permission system works in theory. Let's do a step by step walk trough on how to integrate permissions to your own plugin (we will stick to the commands plugin):

1. Write all your permission keys into your plugin.yml.

This part looks something like this:

permissions:
  - commands.moderation.add
  - commands.moderation.edit
  - commands.moderation.delete
  - commands.all.list
  - commands.all.execute

This is used for twasi-core to determine if all permission keys are valid. It also makes it easier for users since they don't have to search for the correct keys.

2. Add default keys onInstall / remove onUninstall

If the plugin is installed, we want to add our keys to the default groups. This allows the user to use the plugin with zero-configuration. We want to assign commands.moderation to all the moderators and commands.all to the default group. This should look like this in your plugin:

@Override
public void onInstall(TwasiInstallEvent e) {
  e.getDefaultGroup().addKey("commands.all.*");
  e.getModeratorsGroup().addKey("commands.moderation.*");
}

@Override
public void onUninstall(TwasiPluginInstaller installer) {
  installer.getDefaultGroup().removeKey("commands.all.*");
  installer.getModeratorsGroup().removeKey("Commands.moderation.*");
}

3. Check if the sender has the permission

This is easy. Just call sender.hasPermission(permissionKey)

@Override
public void onCommand(TwasiCommandEvent e) {
  Command command = e.getCommand();
  if (command.getName().equalsIgnoreCase("add") && command.getSender().hasPermission("commands.moderation.add")) {
    // Add the command
  }

  if (command.getName().equalsIgnoreCase("edit") && command.getSender().hasPermission("commands.moderation.edit")) {
    // Edit the command
  }

  if (command.getName().equalsIgnoreCase("delete") && command.getSender().hasPermission("commands.moderation.delete")) {
    // Delete the command
  }
  
  if (command.getName().equalsIgnoreCase("list") && command.getSender().hasPermission("commands.all.list")) {
    // List all commands
  }
}

@Override
public void onMessage(TwasiMessageEvent e) {
  Message message = e.getMessage();
  if (message.getSender().hasPermission("commands.all.execute")) {
    // Execute the command
  }
}

That's it. It won't execute the action if you don't have permission to do so.