[TUTORIAL] How to Install/Use PermissionsEx (Newb-Friendly)!

Notice:
A complete rewrite is in the near future.

Hey guys,
I've noticed in a lot of posts here that people are having trouble finding out what permissions is, how to install it, how to use it, how to set up different groups, etc.
I've gotten so tired of answering these questions, I just decided to make a thread on how to use PermissionsEx and how to install it.

Great Features that PermissionsEx Has

1. 95% of ALL plugins are compatible with PermissionsEx!*
2. Is the most FAMOUS permissions plugin of them all!
3. It's ShootToMaim approved!

* If the plugin(s) says that they are only compatible with PermissionsBukkit or another Permissions Plugin (BESIDES GROUPMANAGER), they are compatible with PermissionsEx because of the compatibility layer built into PermissionsEx. Trust me. I know.

Parts of This Tutorial
1. Basic Tutorial (in this post)
2. Advanced Tutorial (in the next post)

Things You'll Need

1. The Latest Version of Java
2. PermissionsEx
3. Notepad++
4. The Latest CraftBukkit Recommended Build
7. The CraftBukkit Starter
8. A Brain.
9. At least 15 minutes.

PermissionsEx: Basic Tutorial Video

Thanks to @Apachekiller / BukkitTeacher for making this video!

Basic Tutorial:
Notes:
1. I highly suggest you get used to using PermissionEx first, before taking the advanced tutorial.

Steps

1. First, download the Latest CraftBukkit Recommended Build.

2. After downloading, make a folder on your Desktop named "Server".

3. Open that folder up, and drop the .jar in.

4. Rename the jar from whatever it's named to: "craftbukkit-0.0.1-SNAPSHOT" (without the quotes).

5. Download the CraftBukkit Starter, and put it into the "Server" folder.

6. Double-click on the CraftBukkit Starter to start the server. Starting the server will usually take 30 seconds-2 minutes on the first run. Stop the server by typing in: "stop" (without the quotes) in the CMD (the black box that was opened by the CraftBukkit Starter).

7. After running the server, you should find many files generated.

1. A "Plugins" Folder
2. A "world" Folder
3. A "world_nether" Folder
4. A "world_the_end" Folder
5. A "banned-ips" Text File
6. A "banned-players" Text File
7. An "ops" Text File
8. A "permissions.yml" Text File
9. 2 "server" Files, 1 LOG File, and 1 PROPERTIES File
10. A "white-list" Text File

8. Download PermissionsEx.rar. Place the Permissions.jar and the PermissionsEx.jar in the "plugins" folder.

9. Run your server again. Wait until it has finished loading up, and then type in: "save-all" (without the quotes. Then type in: "stop" when it's done saving.

10. Now double-click on the "plugins" folder to open it. You will find that 1 folder has been generated: The "PermissionsEx" folder.

11. Download Notepad++.

12. Download Winrar.

13. Place both files (1 .zip, 1 .exe) on your Desktop.

14. Double click on the .exe with the "wrar" at the start of the name, and follow the on-screen steps to install Winrar.

15. After installing Winrar, open up Notepad++ (the .zip with "npp" at the start of the name) with Winrar.

16. Click on the "unicode" folder, then scroll down.

17. Drag the "notepad+ +.exe" out of the .zip to the Desktop.

18. Now on the Desktop, you should have:

1. Your "server" folder.
2. The Winrar.exe installer.
3. The .zip with "npp" at the start of the name.

19. Now go back to your "plugins" folder. Double-click on the "PermissionsEx" folder in it, and double-click on the "permissions.yml".

20. This should be in the "permissions.yml":

Code:

groups:
    default:
        default: true
        permissions:
        - "modifyworld.*"

The text that I quoted is called a permissions node. Most plugins will have these. modifyworld.* is useless right now, so we can delete this as shown in the next step.

21. Now let's add some more groups into your permissions.yml. Let's say you want a "User" group to be the next rank after the "Default" group, so you would add more lines into the permissions.yml. WARNING: .yml files DO NOT read tabs!

Code:

groups:
    default:
        default: true
        permissions:
        - permissions.build: false
    user:
        permissions:
        -
        inheritance:
        - default

The permissions node "permissions.build: false" means that the default group cannot build. If you want them to be able to build, you can change the "false" to a "true".

22. Adding in a plugin to your server is the most fun part of being a server owner. First, let's get a plugin that is the right one for your server! Go to the plugins page to get plugins! You'll see different plugins with different headings! Here's an example of the PermissionsEx plugin:

Code:

[ADMN/DEV] PermissionsEx (PEX) v1.16 - Tomorrow Is Today! [1337]

Here's a list of what the 1st prefixes (ADMN/DEV) mean. There are different ones as well.

[ADMN] for plugins that provide extra plugin functionality that makes managing a server easier, like giving items, managing plugins, etc
[SEC] for plugins that provide a way to combat and remedy griefing
[CHAT] for plugins that provide improvements to chat like ignoring, local chat, channels
[DEV] for plugins that provide developers with frameworks, new functionality
[ECON] for plugins that provide an in-game economy
[EDIT] for plugins that provide world editing functionality
[FIX] for plugins that fix broken functionality
[FUN] for plugins that add fun mechanics like games, destructive tools etc.
[GEN] for plugins that provide standard functionality like playerlist, whitelist etc.
[INFO] for plugins that provide extra information, like uptime
[TP] for plugins that provide teleporting, homes, warps, etc.
[MECH] for plugins that change Minecraft mechanics that don't fall under any other category
[WEB] for plugins that are accompanied by a website script
[WGEN] for plugins that provide custom world generators
[RPG] for plugins that provide role playing experience mechanics
[MISC] for plugins that don't fall into any other categories

References:
1. http://forums.bukkit.org/threads/pl...egory-requirements-updated-july-19-2011.1755/, by EvilSeph.

If your server is a 1337 server (It says on the download page where you downloaded the SNAPSHOT.jar), you'll want to get a plugin that has a [1337] at the end of it on the title. In the example, PermissionsEx has a [1337] at the back of the title, so you know that the plugin is for 1337, and you can use it.

23. Let's say that you want a jailing plugin. You would search: "jail" in the "Title:" search bar.
Let's say that a plugin named "SimpleJail" pops up. You'll want to check it's CraftBukkit version that it is compatible with.
[ADMN/SEC] SimpleJail v1.7 - Jail those nasty players [1337]
Now you know that this plugin is compatible with CraftBukkit 1337, so you can go ahead and click it.

24. Somewhere on that page it should give you a link to a BukkitDev page. If it doesn't, that's alright.
On the SimpleJail page, you can read the description of it, and watch a video showcasing the plugin (if available). The permissions nodes for SimpleJail are:

Code:

SimpleJail.jail — Allows the use of /jail. Jail let's you jail a player.
SimpleJail.unjail — Allows the use of /unjail. Unjail let's you unjail a player.
SimpleJail.setjail — Allows the use of /setjail and /setunjail. Setjail allows you to set 2 points for the jail point and the unjail point.
SimpleJail.* — Allows all SimpleJail commands

Now let's go back to the permissions.yml in the "PermissionsEx" folder.

Code:

groups:
    default:
        default: true
        permissions:
        - permissions.build: false
    user:
        permissions:
        -
        inheritance:
        - default

Let's say you want the "user" group to be able to set the jail and unjail point, as well as jail a player, while the "default" group can be able to unjail a player, so you would do this:

Code:

groups:
    default:
        default: true
        permissions:
        - permissions.build: false
        - SimpleJail.unjail: true
    user:
        permissions:
        - SimpleJail.jail: true
        - SimpleJail.setjail: true
        - SimpleJail.unjail: false
        inheritance:
        - default

This will give the "user" group permissions to be able to Set the unjail point and the jail point, to jail a player, and to not be able to unjail a player.
The "default" group will only be able to unjail a player.
If you want the "user" group to be able to unjail a player as well, you would just remove the whole "SimpleJail.unjail" permissions node from the group, because the "user" group gets all the permissions nodes that the "default" group has because of the inheritance.

25. Save your permissions.yml, close it, and start up your server!

26. You're done!

More Information Before You Start Personalizing Your "permissions.yml":
a) If you'd like a group to have no permissions, just leave a "-" underneath the permissions like so:

Code:

    user:
        permissions:
        -
        inheritance:
        - default

c) The permissions.yml is something like a rank ladder. The default group is, well, the default group, the worst group in the entire permissions.yml. The "user" group is the best group in the permissions.yml.
d) You can add groups to your permissions.yml. There is no limit of the amount of groups you can add. Just copy the "user" group settings, and paste it at the bottom of your "group" section of the permissions.yml. Change the "user:" part of the permissions settings to your new group name, and the inheritance to the group that's worser than it. For example, if I want the best group to be "Minions", I would do this:

Code:

groups:
    default:
        default: true
        permissions:
        - permissions.build: false
        - SimpleJail.unjail: true
    user:
        permissions:
        - SimpleJail.jail: true
        - SimpleJail.setjail: true
        - SimpleJail.unjail: false
        inheritance:
        - default
    Minions: <------------- Remember to change this!
        permissions:
        -
        inheritance:
        - user  <------------- Remember to change this!

Of course, you don't need the SimpleJail permissions nodes in there, they're just examples.

Credits
ShootToMaim for the 2 PermissionsEx Tutorials (Basic and Advanced)!
ApacheKiller for the PermissionsEx Video Tutorial!

Advanced Tutorial

Notes/Warnings:
1. You'll have to delete all of your existing permissions before using this.
2. After using this, you'll be able to add in Group-Specific prefixes, and certain permissions for each map.
3. Make a backup of your permissions.yml. I cannot stress this enough. Make a backup of your permissions.yml!

Steps
1. Open up your permissions.yml in the PermissionsEx folder in your Server folder.

2. Delete everything in there.

3. Now use this template:
users:[/SIZE]
ShootToMaim:
group:
- admin
permissions:
- '*'
worlds:
SurvivalCraft:
permissions:
- '*'
group:
- admin
prefix: '&4[Admin]&f'
groups:
admin:
permissions:
inheritance:
- moderator
options:
test.test: '100500'
worlds:
SurvivalCraft:
permissions:
- nocheat.fly
prefix: '&4[Admin]'
moderator:
permissions:
inheritance:
- VIP
options:
test.test: '100500'
worlds:
SurvivalCraft:
permissions:
- nocheat.fly
prefix: '&1[Moderator]'
VIP:
permissions:
inheritance:
- advanceduser
options:
test.test: '100500'
worlds:
SurvivalCraft:
permissions:
- nocheat.fly
prefix: '&6[VIP]'
advanceduser:
permissions:
inheritance:
- default
options:
test.test: '100500'
worlds:
SurvivalCraft:
permissions:
- nocheat.fly
prefix: '&2[AdvancedUser]'
user:
default: true
permissions:
inheritance:
- null
options:
test.test: '100500'
worlds:
SurvivalCraft:
permissions:
- nocheat.fly
prefix: '&a[User]'
Let's focus on the "groups" part of the permissions.yml now. You can add/delete groups, modify the prefixes, and add custom permissions for each group per world.
Example:
You want Group A to be able to build in world1, but not in world2, so you would modify this part of the group's permissions:

worlds:
world1: <----------------- World 1
permissions:
- permissions.build: true <------ Players can build here.
world2: <----------------- World 2
permissions:
-permissions.build: false <------ Players cannot build here.

These are world specific permissions, so what applies to world 1 won't apply to world 2 unless you put the same permissions.
Ignore the options part of the code:

options:
test.test: '100500'


4. More Information Before You Start Using This Template:

a) The "user" group is the default group in this template because there is a "default: true" underneath the group name
b) You can change the prefix the group to whatever you'd like. If you'd like a suffix for your group as well, just add this:

user:
default: true
permissions:
inheritance:
- null
options:
test.test: '100500'
worlds:
SurvivalCraft:
permissions:
- nocheat.fly
prefix: '&a[User]'
suffix: '&a[ThisIsMyAwesomeSuffix]' <---------------



c) Remember that when you are personalizing this template that you can add specific group permissions for each world!

user:
default: true
permissions:
-
inheritance:
- null
options:
test.test: '100500'
worlds:
SurvivalCraft: <-------------- Remember to put your world name here!
permissions:
- nocheat.fly <--------------- Permissions go here!
prefix: '&a[User]'


d) The "- null" under the inheritance just means that the group doesn't inherit from any other group. You can also use just "-" instead of "- null".

e) The "permissions:" at the top of the group settings means that you'll be able to use all the permissions nodes in every world that are below the "permissions:". If you'd like the group "Snipers" to be able to use "SimpleJail.jail" in every world, but "SimpleJail.unjail" only in the world "OnlyUnjailHere", you would put this in:


Snipers:
permissions:
-SimpleJail.jail
inheritance:
- null
options:
test.test: '100500'
worlds:
OnlyUnjailHere: <-------------- Remember to put your world name here!
permissions:
- SimpleJail.unjail <--------------- Permissions go here!
prefix: '&a[ExtremeSniper]'


f) You can also change the color of your prefix! As you can see:


Snipers:
permissions:
-SimpleJail.jail
inheritance:
- null
options:
test.test: '100500'
worlds:
OnlyUnjailHere: <-------------- Remember to put your world name here!
permissions:
- SimpleJail.unjail <--------------- Permissions go here!
prefix: '&a[ExtremeSniper]' <----- Prefix



The group Snipers has the prefix [ExtremeSniper], but notice how there is a &a before it. This is a color code! Here is a complete list of color codes:



NOTICE: Use & instead of #.
So if you want the prefix [ExtremeSniper] to be black, you would change &a to &0.

g) Only put the suffix part in if you're actually using a suffix.

h) PermissionsEx has some commands and permissions nodes as well! Check them out here! (If the website says "ladder", it means "group".

i) If you want your group to have a prefix, without all the annoying multi-world prefix/permissions stuff, you can use this:


Snipers:
prefix: <=====
'&f[&4Admin&f]' <=====
permissions:
-SimpleJail.jail
inheritance:
- Noobs
options:
test.test: '100500'


In doing this, the group Snipers will have the prefix [Admin] in all worlds. They will also have the ability to use the permissions node SimpleJail.jail in all worlds as well.

More Information/Notes
All quotes (") in the steps should be ignored. If you found this useful, please ask in the comments to sticky this! Thanks!
If you get any errors, do NOT hesitate to post your errors here! You can get your errors in the server.log in the "Server" folder!
Always put the "users" section below the "groups" section of the permissions.yml if you're using the Basic Tutorial. If you're using the Advanced Tutorial, put the "users" section below the "groups" section.
These tutorials aren't perfect. Please post errors that you've found within these tutorials.

If my tutorials don't work for you, send me a PM![/SIZE]

I added some fixes to the OP.

Wow, this really helped me get my permissions system up and going! thanks! before I found permissions hard and intimidating, but this simplifies it a lot. But why does Notepad++ mark whatever I add red? i've used Notepad++ for a long time now, and I've never seen it do that. and the code that I add works., it just turns it red.

Thanks for your feedback!
Notepad++ marks whatever you add red to show you the difference between what was the original text, and what was the new text that you added.
Notepad++ marks whatever you add red to show you that .yml files doesn't read tabs.

You referenced the CraftBukkit installer, didn't you. TnT hates that
I'll take a look in a bit.

nah, I found why it was red: I forgot that yaml files don't read tabs, so I replaced them all with spaces and now it looks normal. Great tutorial!

I figure you probably know this but for those who don't.

I can't remember if Notepad++ Is set to do it by default but you can change the configuration to automatically use 4 spaces instead of a tab. It should be under: Edit -> Preferences -> Language Menu/Tab Settings.

no it is not, but I found this setting just a little bit ago.

Why doesn't he like it? It's great!
Thanks for the reply!

Any news?
BTW, thanks for taking a look for me!

Bump to let newbies see this!

I would bump, but I don't want to get an infraction for it... i'd like to keep my record clean.

I fixed some grammar in the original post.

Doesn't work. Under the "Edit" tab, there is no "Preferences".

i meant the edit menu

Edit: Nvm... wow try the settings menu lol

Anything new about the status of this being stickied?

@TnT says no

I'm glad you made a tutorial for this @ShootToMaim

PermissiosnEX is by far the permissions plugin with which people have the most trouble. Hopefully this will lower the amount of posts asking for help with it!

These tutorials are always welcome on the wiki, feel free to set it up there @ShootToMaim and link it to the Bukkit Developers Portal.

I plan on making a bPermissions version of this whenever I get the time...

Would you like to work with me to make a complete Permissions tutorial with me?
When I say "complete Permissions", I mean PermissionsEx, bPermissions, GroupManager, and PermissionsBukkit.
If you want to, PM me for more details!

Alright, thanks @resba.

I say "Thanks anyway".

Thanks!
BTW, congratulations on your new position!

Ah, thanks

Hmm I'm sure @TnT will want it in Bukkit docs later.

I only use bPerms.