Minecraft/Bukkit/PermissionsBukkit
From Multiplay Wiki
| This article is in a finalised state, please do not make any major edits to it and instead discuss any changes you wish to make on the talk page. |
Please keep in mind that Support will not write your file for you - we endorse this plugin and will help you manage it or point out any errors on quick fixes, but we lack the resources to spend time writing everyones' files (and we also cannot read your minds).
Bukkit now has a default Permissions handler integrated it, and suggests (as do we) that you use its default Permissions plugin known as PermissionsBukkit.
The PermissionsBukkit permissions are able to be handled by 2 separate files, the plugins/PermissionsBukkit/config.yml and the root permissions.yml.
Before setting up this file, please refer to our guide on Understanding YAML.
Contents |
Setting up config.yml
The default config.yml file in ClanForge is as follows:
users:
DefaultUser1:
permissions:
permissions.example: true
groups:
- admin
groups:
default:
permissions:
permissions.build: false
admin:
permissions:
permissions.*: true
inheritance:
- user
user:
permissions:
permissions.build: true
worlds:
creative:
coolplugin.item: true
inheritance:
- default
messages:
build: '&cYou do not have permission to build here.'
There are 3 separate sections of PermissionsBukkit to modify: Groups, Users, and Messages.
Groups
The groups section of your config.yml is where you set up the different kinds of ranks your users will have on your server. Each one-indentation line followed by a colon specifies a new group. There are three categories within each group: global permissions, world-based permissions, and inheritance.
Global permissions and world-based permissions are relatively self-explanatory. The global permissions uses nodes in the permissions category set to either true or false, a boolean. World-based permissions uses a worlds category with a subcategory for each world that the nodes are stored in, also boolean.
Depending on whether world-based permissions or global permissions are listed first in the file, one will override another. Below is an example where global permissions will override world-based permissions:
user:
worlds:
creative:
permissions.build: false
permissions:
permissions.build: true
And again, below is an example where world-based permissions will override global permissions:
user:
permissions:
permissions.build: true
worlds:
creative:
permissions.build: false
Inheritance is a setting that allows a group to inherit all of the permissions nodes that have been set for a previous group, true or false. Inheritance is a list format category. For more information about list formats, please see the guide to Understanding YAML.
It is important to remember that settings that are listed last have precedence over settings listed first when parsed.
Users
The users section of your config.yml is where you define which users belong to a group other than the default, and if any users have custom permissions and settings. There are two categories for each user: groups and permissions.
The groups category is a list format category, with one list item per group a user is in. Users can exist in multiple groups, and as with nodes will derive their precedence in the order the groups are listed.
The permissions category can be used to define custom permissions nodes for each user in the case that you have an exception of a permission you would like to specify outside of the normal group settings.
Below is an example of a users entry.
users:
Wahrheit:
permissions:
permissions.example: true
groups:
- user
Slantykins:
permissions:
permissions.example.two:true
groups:
- admin
Users not defined in your file will have the permissions specified in the first group listed in your file.
Messages
The messages section of your config.yml is where you define any messages associated with permissions that are denied to override the defaults. Messages are defined as strings for each permissions node and require apostrophes ('example') to function properly. They support Color Codes.
Notes for Defining * Nodes
The nodes with asterisks do not function with PermissionsBukkit like they do with Permissions. You cannot define a single asterisk node and have it blanket all plugins for users or groups, you must define pluginname.* or if the author does not support that you will need to write out individual permissions (and scold the lazy author). Depending on the plugin you can also include pluginname.subgroup.*, and some plugins treat pluginname.subgroup as a wildcard for all nodes within that subgroup.
Setting up permissions.yml
Your permissions.yml file is not actually where you save the configuration for PermissionsBukkit, it is used as a kind of shortcut for your config.yml by creating new nodes out of groups of nodes and settings. This file is blank by default, so we will be walking you through an example config.yml for PermissionsBukkit and permissions.yml file as well.
Creating Custom Nodes
By properly configuring your permissions.yml file you can create a cleaner, more organized config.yml for PermissionsBukkit and eliminate redundancy. Using it, you can create parent permissions that inherit all of the nodes assigned in their children. Here's a fully-written example for admins and basic users.
server.basics:
description: Basic permissions for My Cool Server.
default: true
children:
commandbook.motd: true
commandbook.say: true
commandbook.say.me: true
commandbook.time: true
server.admin:
description: Admin permissions for My Cool Server.
default: op
children:
commandbook.broadcast: true
commandbook.teleport: true
commandbook.kick: true
commandbook.ban: true
As seen above, each parent node has a description, default status, and the children for it.
The description for each node does not require apostrophes, and should be a string. It can be read by plugins and is mostly used for personal reference.
The default status has three options: true, op, and false. True will set the parent node to all groups by default if not defined in the config.yml for PermissionsBukkit, op will set it to true if the user is an op, and false will exclude it from groups by default (you can still define it in the config.yml -- this was the original intention and can be used for some groups but not others).
Child nodes are set exactly like they would be in your config.yml (mind the indentation) but can be assigned all to a single parent so you don't have to keep as many nodes in one file. It is a workaround for if you only want to assign a single group per user, and can include as many nodes and be assigned to as many groups as you like.
Conclusion
Writing your permissions setup can be a daunting and arduous process if approaching it for the first time with many plugins. The best method is to start with the very basics -- the Permissions nodes are available on the Bukkit forums and from there you can work in one plugin at a time, slowly but surely. Included at the bottom are example configuration pairings from more complicated servers to use as reference when creating your own files.
Good luck, and don't forget to parse your files!
