YAPP (Yet Another Permission Plugin)

Introduction

There are many permission plugins available to choose from. This is yet another one.

I had a couple reasons in mind when I started creating this plugin. The first was that I wanted to learn how to use Bukkit's permission system, since I didn't have a good understanding of how it worked. The second reason is that I thought I could make a system that is very simple and intuitive to use. I wanted it to be extremely user-friendly. The commands and in game interface should be easy to use, and the generated files should be easy to edit without making mistakes.

So, I hope I've accomplished my goals with this plugin. I believe I have, but we'll have to wait and see.

Features

This is a full-featured permission management plugin. It should be able to do most everything you think a permissions plugin should be able to do.

What Are Permissions?

If you have never used a permissions plugin before, you may not know exactly how they work or what they are used for. If that is true, then this section is for you. If you are already familiar with other permissions plugins, you can skip this section.

A permissions plugin allows you to have detailed control over what kinds of things your players can do. Each plugin can define certain permission "nodes" that control certain actions from that plugin. A node generally takes the form of pluginname.command or pluginname.feature.something. In order for a player to use that command or feature, they must have the associated permission node. Each plugin should have a list of permission nodes somewhere on its project page or website.

This plugin allows you to assign permission nodes directly to players. It also allows you to set up permission groups. You can then assign permission nodes to groups instead of to the players. Then you can put a player in the groups they belong in, and they will inherit the permissions of the group.

In addition, groups can be members of other groups. So for example, you could have an "admins" group, that inherits (is a member of) the "moderators" group, which inherits the "members" group. If a player is placed in the "admins" group, then they will get those permissions, as well as the "moderators" and "members" permissions.

This plugin also allows you to set up server-wide permissions and world-specific permissions. For example, you could give a certain permission node to a group, but then remove that permission node for that group in a specific world. Or you can ignore server-wide permissions all together and put all permission data in each individual world. How you set it up is your choice.

Download

You can download the current version of YAPP here:

YAPP Plugin

Installation

Simply download the file above, and drop it into your plugins folder. That's it!

Converting

YAPP has the ability to convert from a few other common permission plugins, including PermissionsEx, GroupManager, and PermissionsBukkit. Please note that it will only do a basic conversion. Some of these plugins have some features that YAPP does not have, and those types of things will not get converted properly. Groups, users, permissions, and prefixes will be converted.

To perform a conversion, use the command /yappconvert <plugin>. For example, to convert from PermissionsEx, type /yappconvert pex.

You will want to look over the converted files to make sure that everything is still set up the way you want it. It's very probable that the conversion will not be perfect, but it should give you a good start.

Configuration

When you start your server for the first time after installing YAPP, a config.txt file will be created in your plugins/YAPP folder. An important thing about this configuration file (and all files this plugin creates) is that they are much more friendly than yml files. It is okay to add extra whitespace, including both tabs and spaces.

Default Config File

== GENERAL ==

debug               : false

default group       : default
use build perm      : true
modal menu          : true
enable wildcard     : true

update player list  : true
update display name : true
display name format : %color%%name%
use chat formatting : true
chat format         : %prefix%%color%<%name%> &f%message%

set group perm      : false
set player metadata : false
set nameplate color : false

== LADDERS ==

main : default, vips, mods, admins

== DENY PERMISSIONS ==

place    : false
break    : false
craft    : false
pickup   : false
drop     : false
useitem  : false
useblock : false
interact : false
targeted : false
attack   : false
damage   : false

== MYSQL ==

enabled : false
host    : localhost
user    : bukkit
pass    : walrus
db      : minecraft
prefix  : yapp_

General Settings

There are several options in the config.txt file under the General header you can modify. These are listed in the table below.

Option Description Default
debug Toggle debug mode. If this is true, you will see a lot of information on the console when the plugin loads data. false
default group The name of the default group players are placed in if they are not in any group. If this group does not exist, it will be created when the plugin loads. default
use build perms Whether to use the yapp.build permission to restrict players' ability to build. true
modal menu If this is true, all incoming chat will be blocked while using the in-game menu. true
enable wildcard Whether to enable the magic wildcard (***) when processing permissions. See the wildcard permissions section for more information. true
update player list Whether to use the player color to update the names on the in-game player list (the one accessed with tab). true
update display name Whether to update the player's display name with their color. This is for compatibility with other plugins, such as chat plugins. true
display name format If the update display name option is true, this setting will determine how the display name is formatted. This can be used to change the way other plugins display player names (assuming they use the display name). By default, it just uses the color followed by the player's name. The valid formatting variables are %name% for the player's name, %message% for the message sent, %color% for the player's color, and %prefix% for the player's prefix. %color%%name%
use chat formatting Whether to use the prefix and player color to format chat messages. true
chat format If the use chat formatting option is true, this setting will determine how chat messages are formatted. The valid formatting variables are %name% for the player's display name, %rawname% for the player's actual name, %message% for the message sent, %color% for the player's color, and %prefix% for the player's prefix. You can specify formatting and color codes with the ampersand (&) character (for example, &f for white). %prefix%%color%<%name%> &f%message%
set group perm Whether to give players the permission group.groupname based on their primary group. This is for compatibility for plugins that may need this. false
set player metadata Whether to set the player's metadata with their primary group (and maybe other info). This is probably not useful at the moment, but may be in the future. false
set nameplate color Whether to set the player's nameplate color. This requires the TagAPI plugin. false

Ladders (Promote/Demote)

You can create as many promotion ladders as you wish. Each ladder is given a name, followed by a colon, followed by a comma-separated list of group names. The groups are in order from lowest to highest. In the example in the default config file, the ladder name is main and it will promote from default to vips to mods and finally to admins.

Please note that the example in the default config is just an example. That ladder will not work by default because most of those groups don't exist, and you probably won't want to be able to promote people to the admins group anyway.

Deny Permissions

YAPP has a system that allows you to deny a player or group the ability to interact with the world in various ways. For example, you can prevent a certain group from placing TNT, or using buckets, or picking up dropped items. If you want to use these features, you will need to enable them in the config. Each "category" must be enabled individually. These are the categories:

  • place -- Placing (building) blocks
  • break -- Breaking blocks
  • craft -- Crafting items
  • pickup -- Picking up item drops
  • drop -- Dropping items from inventory to the ground
  • useitem -- Using an item in hand by right or left clicking
  • useblock -- Using a block in the world by right or left clicking
  • interact -- Right clicking on entities (such as villagers for trading)
  • targeted -- Being targeted by monsters
  • attack -- Attacking other entities (players or monsters)
  • damage -- Receiving damage

The plugin uses these categories for efficiency reasons. If you don't care to restrict pickups or drops, there is no reason for the plugin to be watching for it.

MySQL

YAPP now has support for saving its data in MySQL. This should be considered still in a "beta" state. To enable MySQL support, you must set the enabled option to true, then set the MySQL connection options (host, user, pass, db) for your MySQL database. The plugin will create the necessary tables automatically when you first load the plugin after changing these settings. This means the user you specify must have the ability to create and alter tables on the database.

Permissions

This plugin defines several permission nodes.

Permission Description
yapp.* Grants all permission nodes listed below. Defaults to op-only.
yapp.build A player must have this permission to interact with the world. This permission can be disabled in the configuration file. Defaults to false.
yapp.admin Only those with this permission can use the in-game commands to modify permission settings. Defaults to op-only.
yapp.promote The base permission to use the /promote command. You will need other permissions to actually promote players. Defaults to op-only.
yapp.demote The base permission to use the /demote command. You will need other permissions to actually demote players. Defaults to op-only.
yapp.promote.* A player with this command can promote players along any ladder. Defaults to op-only.
yapp.demote.* A player with this command can demote players along any ladder. Defaults to op-only.
yapp.promote.laddername A player with this command can promote players along the specified ladder.
yapp.demote.laddername A player with this command can demote players along the specified ladder.

Deny Permissions

YAPP has a system that allows you to deny a player or group the ability to interact with the world in various ways. For example, you can prevent a certain group from placing TNT, or using buckets, or picking up dropped items. To use these features, you give players and/or groups special deny permissions. However, before doing this, you must enable the appropriate categories in the configuration.

The general format for these permissions is: yapp.deny.category.id. For example, if you want to prevent a group from placing TNT, you would first enable the place category in the configuration, then give them the permission node yapp.deny.place.46. It is also possible to deny all types in the category. For example, if you want to prevent a group from picking up any item drop at all, you could give them the permission yapp.deny.pickup.*.

A list of ids for blocks, items, and entities can be found on this Minecraft Wiki page. The entity id for players is 0. For the damage category, you can also use damage cause types. The list of valid damage causes are: contact, entity_attack, projectile, suffocation, fall, fire, fire_tick, lava, drowning, block_explosion, entity_explosion, void, lightning, suicide, starvation, poison, magic, wither, falling_block, and custom.

You can see a complete list of the different categories in the configuration section above.

Wildcard Permissions

YAPP has support for wildcard permissions (as of version 1.3), which allow you to apply multiple permission nodes with just one node. This feature must be enabled in the config file. There are three types of wildcard nodes.

The first wildcard node is the *** node. A person with this node will receive all of the permission nodes that a server op would receive.

The second wildcard node is the some.perm.*** style node. That example will give the player all permissions that begin with some.perm..

The third wildcard node is the regular expression node, which begins with regex: and is followed by a regular expression. This is the most complex type, and an explanation of how regular expressions work is outside the scope of this document. However, they are available for use should you need them.

Please note that many plugins provide their own special nodes for granting permission sets. If possible, you should always try to use a plugin-provided node before resorting to a YAPP wildcard node.

Additionally, the YAPP wildcard nodes will only grant permissions that have been properly defined by a plugin. This restriction applies to all three types of wildcard nodes. As an example, the deny permissions within this very plugin are not individually defined (because that would be a lot of nodes to define, and there would be new ones with each Minecraft update). This means that something like yapp.deny.break.*** will not work. (However, YAPP defines its own wildcard nodes for deny permissions, so you can use those instead.)

Usage

The methods for modifying permission settings are designed to be very easy to use and easy to remember. There are actually three ways to make changes to the permission system.

Menu

The main command in this plugin is /yapp. The aliases /perm and /perms are also available. If you use this command on its own without any arguments, it will open a guided menu system. The menu is the easiest way to make simple modifications to permission and group information.

While you are in the menu system, there are a few options that are always available to you.

  • < will return you to the previous menu
  • ! will return you to the main menu
  • ? will tell you your current selection, and will sometimes give help about the current screen
  • q or quit will exit the menu

Many of the menu screens will have a list of numbered options with highlighted words. To select an option, you can either type the number, type the highlighted word, or just type the highlighted letter within the word.

You will need to reload for many of the changes to take effect. The option to reload is in the main menu, option '5' or 'S' or 'R'.

Commands

Changing settings with normal commands will require multiple commands in sequence. These commands can be used both in-game (with the yapp.admin permission node) and on the command line. In general, your commands will use the following pattern:

  1. Select something (a player or group, and world if desired)
  2. Make changes to the selected object
  3. Save the settings and reload the permission data

You can look at some examples to help you understand how it works.

There are also commands for promoting and demoting players.

Selecting

Before you can make changes, you need to select what you want to make changes to. This can either be a player or a group. You can also select a specific world to work with. If you do not select a world, your changes will be made at the server level.

To select a player, simply type /yapp playername. For example, to select the player nisovin I would type /yapp nisovin. It can also match partial names, so I could instead just type /yapp nis. You can also select an offline player by using the o: prefix. For example, if you want to give Notch some permissions, you could type /yapp o:notch.

To select a group, use the g: prefix. To select the default group, you would type /yapp g:default. If you try to select a group that does not exist, it will be automatically created for you.

To select a world, use the w: prefix. Typing /yapp w:world will select the world named world. You can clear the world selection by typing the w: prefix without a world. So, type /yapp w: to clear your world selection.

At any type you can type /yapp ? to see what you currently have selected.

Making Changes

Now that you have selected something to work with, you can make changes. All changes are made by using one of the operators, which are outlined in the table below. The commands follow this general pattern: /yapp <operator> <something to set>.

Operator Description
+ The intelligent add operator. This will add either a permission node or an inherited group to the selected player or group. If there is a period in the item you are adding, it assumes it is a permission node, otherwise it assumes it is a group. You can force it to treat the item as a permission node or group by using the n: or g: prefix, respectively.
- The intelligent remove operator. It follows the same rules outlined for the + operator.
-- The negate permission operator. This will force a permission node to be off, even if it has been inherited from another group.
+n or n+ The add permission node operator.
+g or g+ The add group operator.
-n or n- The remove permission node operator.
-g or g- The remove group operator.
=g or g= or g The set group operator. This will remove all other groups and add the new group.
= The set operator. This is used to set things such as the chat prefix and color. This uses the format /yapp = <item> <value>. The item and operator can also be reversed: /yapp <item> = <value>.
? The test operator. This will test to see if a player or group has a permission or is in a group. It follows the same rules as the + operator.
@ The save and reload operator. This will save your changes to disk and reload the permission data. It will also read any changes that have been made to the files on disk. Many of your changes will not take effect until this is done. See below for more information. You can also use /yapp reload.

Saving and Reloading

The command to reload is /yapp @ or /yapp reload. You can also reload just a specific player's permissions with the command /yapp @ playername. Note that this will only reload simple changes, like adding or removing permission nodes or groups directly to the player (if you add or remove permissions to a group, reloading the player will not reload the group changes).

Multiple Commands

It is possible to put multiple commands into one command by separating them with a vertical bar. This is intended to be used with other plugins that allow you to specify commands to run. Please note that an error in one command will not prevent the remaining commands from being executed, so if you're running commands manually it's safest to run them one at a time to keep yourself from making mistakes.

Examples

The easiest way to understand how this works is to just give a few examples. This first example will add the yapp.build permission node to the default group.

/yapp g:default
/yapp + yapp.build
/yapp @

This next example will give nisovin a cool new chat prefix and name color.

/yapp nisovin
/yapp prefix = "[&bAwesome&f] "
/yapp color = blue
/yapp @ nisovin

This example is the same as the one above, except it is combined into one single command.

/yapp nisovin | prefix = "[&bAwesome&f] " | color = blue | @ nisovin

This final example will give Bob (who is currently offline) permission to build, but only in the nether.

/yapp o:Bob
/yapp w:world_nether
/yapp + yapp.build
/yapp @

Promoting and Demoting

You can promote and demote players with the /promote and /demote commands. These commands require special permissions to use. They will promote and demote players along predefined ladders, based on the player's primary group. The primary group can be set in the menu, and is the first group listed in the player file.

The commands use the format /promote <player> [world]. Specifing a world is optional. If you do not specify a world, it will promote (or demote) the player using their server-level group settings. You can also use the o: prefix to promote an offline player, similar to other commands.

Files

The file storage system for this plugin is designed to be very easy to read and understand. It is whitespace-friendly, meaning you can add extra spaces, tabs, and line breaks without problem. The one disadvantage is that the information is spread into many different files. However, this can also be seen as an advantage, as you don't have to scroll through huge files to find what you're looking for.

The plugin's folder structure looks something like this:

  • YAPP
    • groups [this folder stores server-level group info]
      • default.txt
      • admins.txt
    • players [this folder stores server-level player info]
      • bob.txt
      • joe.txt
      • sally.txt
    • worlds
      • world
        • groups [this folder stores group info for world]
          • default.txt
          • admins.txt
        • players [this folder stores player info for world]
          • bob.txt
          • joe.txt
          • sally.txt
      • world_nether
        • groups [this folder stores group info for world_nether]
          • default.txt
          • admins.txt
        • players [this folder stores player info for world_nether]
          • bob.txt
          • joe.txt
          • sally.txt

As you can see, this has the potential to create a lot of files, especially if you have a lot of worlds and want to setup permissions by world. However, it is very organized and easy to find the file you are looking for.

Now, let's open up one of the files and look at it.

== INFORMATION ==

prefix : "[&bADMIN&f] "
color : "blue"

== GROUPS ==

admins
default

== PERMISSIONS ==

 + some.special.permission
 + another.permission
 - some.negated.permission

As you can see, it's fairly straightforward. The Information section contains some information about the group or player you are looking at, such as the chat prefix and color. The Groups section contains a list of groups that are inherited (the first group listed is considered the primary group), and the Permissions section contains all of the permissions.

Please note that the formatting of this file is pretty lenient. Extra spaces, tabs, and line breaks are perfectly acceptable. The plus sign in front of permission nodes is not required, it's only there because it looks nice when alongside the negated permissions (the minus sign on those is required). Even the number of equals signs for the section names can vary, and the case is not important. For example, the following file will work exactly the same as the one above.

= = = info = = =

prefix: "[&bADMIN&f] "
color: "blue"

==Groups

  admins
    default

=== perms==

  some.special.permission
          another.permission
-some.negated.permission

Advanced Topics

Permission Processing Order

When YAPP processes the permission nodes for a player (or group), it starts with the most specific nodes, then moves on to more general ones. This is the processing order:

  1. Player (or group) world-specific permissions
  2. Player (or group) server-wide permissions
  3. World-specific inherited group permissions (in order)
  4. Server-wide inherited group permissions (in order)

If a permission node is defined at multiple levels, it will use the value of the most specific entry. For example, if a player has a server-wide permission of test.node, but a world-specific negation of that node (-test.node), then the player will not have that permission node, assuming they are on that world, because the world permission is more specific.

This applies to inherited groups as well. Player permissions will always override inherited group permissions, and world-specific group permissions will override server-wide ones. Permissions for inherited groups are processed in order, with the first group overriding later groups.

Wildcard permissions work by adding all matching permissions when that permission node is processed. So, if a player has the -test.node negated permission node, but inherits from a group that has the test.*** wildcard node, they will have all of the nodes that begin with test. except for test.node, because the player permission will override the inherited group permission. If the opposite is true, if the player has the test.*** node, and inherits a group that has the -test.node negated node, the player will have all nodes that start with test., even test.node, because the player permission overrides the inherited group permission.

If a permission node and a related wildcard node are both listed at the same level, then the order they are listed in will determine what happens. The nodes are processed in order, with earlier ones overriding later ones. So, if a player has the -test.node negated node followed by the test.*** wildcard node, then they will have all nodes starting with test. except for test.node. However, if the test.*** is listed first, followed by the -test.node negated node, then the player will have all nodes starting with test., because the wildcard will have priority.

Database Info

Table: yapp_data

This table stores information about YAPP. It only has one record.

Field Type Description
schema_version int The current schema version (used to know how to update the schema if necessary).

Table: yapp_inherited_groups

This table stores the inherited groups for both players and groups.

Field Type Description
name varchar(50) The name of the player or group that has an inherited group.
type tinyint 1 for player, 2 for group
world varchar(50) The world, or null for server-wide.
group_name varchar(50) The name of the inherited group.
order int The order (see processing info above).

Table: yapp_permissions

This table stores the permissions for both players and groups.

Field Type Description
name varchar(50) The name of the player or group with the permission.
type tinyint 1 for player, 2 for group
world varchar(50) The world, or null for server-wide.
node varchar(200) The name of the permission node.
value tinyint The permission value (0 for false, 1 for true).
order int The order (see processing info above).

Table: yapp_info

This table stores meta information for both players and groups, such as prefix and color.

Field Type Description
name varchar(50) The name of the player or group.
type tinyint 1 for player, 2 for group
world varchar(50) The world, or null for server-wide.
key varchar(100) The key name for the information (prefix, color, etc).
value varchar(250) The information.
order int The order (see processing info above).