As mentioned previously, PEX supports a rich chat/console command interface allowing you to do almost everything in-game or from the server console.

Note: The following page and tutorial assumes that you have access to the server console and are entering the commands in-game. All commands can be used in-game or at the server console. Commands used in-game must start with a /, while commands entered at the server console do not use the /.

• Permission Nodes
  • Important Information on the '*' node
  • Important File Back-end Notes
• Tutorial Goals
• Preparations
  • Setup a basic and simple permissions infrastructure
    • If you do not have access to the console
  • Create additional groups
  • Setup rank order
  • Add fancy prefixes!
  • Add permissions to each group
• Testing your environment
• Test the ranks
• File Back-end Example

PEX works on the general principal that permission to run a command is not allowed unless the permission node is specifically listed. For those commands and events that are allowed by default, PEX allows for denying access to those commands with permission node negation.

Giving or denying access to a permission node is as simple as using the pex group <group> add <node> command. Negating a permission node uses the same command, you just need to add a hyphen (-) to the beginning of the node name.

For example, lets look at the /give and /plugins commands as they are part of bukkit.

• /give has a permission node of bukkit.command.give and is normally limited to players listed in the ops.txt file
• /plugins has a permission node of bukkit.command.plugins and is normally given to everyone on the server

The commands to add or deny access to these commands are:

• To allow a group access to /give, the command for PEX is pex group groupname add bukkit.command.give
• To deny a group access to /plugins, the command for PEX is pex group groupname add -bukkit.command.plugins

• PEX does support a 'give all permissions' node with '*'. However, before using this, read and understand how it works and it's possible side affects.
  • At first glance, it seems simple, giving a group '*' gives it access to all permission nodes. The catch is that there may be permission nodes that you normally would not want a group to have. For example, consider the plugin VanishNoPacket (Referred to as VNP.) VNP offers the node vanish.silentjoin which makes anyone with the node log into the server without a join announcement, which many server owners do not want. This behavior can be simply dealt with by negating the node. Any permission node that is enabled by default can be negated to "turn it off".

If you are going to edit the permissions file by hand, make sure to read, understand and follow these rules:

• Permission nodes must start with a hyphen and a space.
  • - modifyworld.chat and - -modifyworld.mobtarget.* are valid entries in the file back-end
  • modifyworld.chat and -modifyworld.mobtarget.* are invalid entries in the file back-end
• All formatting rules listed in the YAML notes section on the PEX Basics page must be strictly followed. Failure to do this can and often does cause PEX to fail on startup, as well as filling your log files with great amounts of error message text.
• PEX reads the file in a 'top to bottom' manner when checking group and user permission nodes. Similar to a network firewall, once it finds a node that matches what it is looking for, it stops searching. What this means in practice is that if a node gives access to a main group and all subgroups, PEX will find the node that allows access then stop checking, never reaching the negation node.

Consider the following (incorrect!) example:

default:
  options:
    default: true
  permissions:
  - modifyworld.*
  - -modifyworld.blocks.interact.23

With this node layout, if a player tried to open a dispenser (data value 23), the first match would be modifyworld.*, causing PEX to stop checking at this point and allow access!

However, if the two lines were reversed (-modifyworld.blocks.interact.23 came before the modifyworld.*), the player would be denied when trying to open the dispenser (node check modifyworld.blocks.interact.23) as the negation node for block ID 23 is the first one to be matched. If the player tried to open a furnace (block ID 61), it would be allowed as the modifyworld.* node would match a check of modifyworld.blocks.interact.61

• Setup a basic and simple permissions infrastructure
  • Create additional groups: Member, VIP, Mod, Admin
    • "Default" is able to chat but cannot modify anything and doesn't have a prefix
    • "Member" is a trusted player group. Those players can modify the world and have a colored prefix ("&0(&8M&7ember&0)&7 ")
    • "VIP" is able to modify the world and is not targeted by creepers. Those players will have a prefix "&0(&eVIP&0)&7 ".
    • A "Mod" (Moderator) is able to modify the world and is not targeted by any mobs.
    • An "Admin" (Administrator) is a superuser and has access to all PEX commands. They get a fancy prefix like "&0(&4Admin&0)&7 ".
  • OPTIONAL: Remove modifyworld.* permission from "Default" group
  • OPTIONAL: Add modifyworld.chat permission to "Default" group
• Testing your environment

• Install and configure (Plugin Configuration) PermissionsEx.
• OPTIONAL: Activate ModifyWorld. See Modifyworld, Configuration for more.
• Start your server.
• Open up the Commands section in a separate web browser window
• Open the YAML Notes in the PEX Basics page in a separate web browser window

These commands must be entered at the console

• Create the "Admin" group with pex group Admin create
• Add the permissions.* permission to this group with pex group Admin add permissions.*.
• Add yourself to this group with pex user YourPlayerName group set Admin, replacing YourPlayerName with your in-game name.
• OPTIONAL: Give yourself permissions to access all PEX commands regardless of the group you are in with pex user YourPlayerName add permissions.*

Create a permissions.yml file as follows and upload it to the PermissionsEx directory, making sure that the formatting is exact and correct! See the YAML Notes in the PEX Basics page page for details.

groups:
  Default:
    options:
      default: true
    permissions:
    - modifyworld.*
  Admin:
    options:
      prefix: '&0(&4Admin&0)&7 '
    permissions:
    - permissions.*
users:
  YourPlayerName:
    group:
    - Admin
    permissions:
    - permissions.*

Now connect to your server to create groups Member, VIP and Mod.

• Create the Member group with /pex group Member create
• Create the VIP group with /pex group VIP create
• Create the Mod group with /pex group Mod create

Next, we will assign ranks to those groups and set the Rank order to Member -> VIP -> Mod -> Admin. See Ranks (Promotion and Demotion) for more.

• /pex group default set rank 1000
• /pex group Member set rank 900
• /pex group VIP set rank 800
• /pex group Mod set rank 100
• /pex group Admin set rank 1

Rank 100 is now the highest promotion status.

Be aware that the promote and demote commands have restrictions in-game (but not in the console). In-game, you can not:

• promote a player who is below your rank up to your rank (Mod to Admin, using the previous example)
• demote a player that is above your rank down to your rank (Admin to Mod, using the previous example)
• promote/demote a player who is at your rank (you can't promote/demote a Mod at all if you are a Mod; you can't promote/demote an Admin at all if you are an Admin)

If you are (for example) an Admin group member and want to assign another player to the Admin group while you are in-game, you must set it directly by using the command /pex user PlayerName group set Admin.

The promote and demote commands will work on any player of any rank from the console, without restrictions.

• /pex group Member prefix "&0(&8M&7ember&0)&7 "
• /pex group VIP prefix "&0(&eVIP&0)&7 "
• /pex group Mod prefix "&0(&1Mod&0)&7 "
• /pex group Admin prefix "&0(&4Admin&0)&7 "

Be aware that there is a blank space after each prefix. This prevents the prefix of your group from being smashed up against the username in chat. (And, similarly, a blank space comes before any suffix you would use for the same reason - so the username is not smashed up against the suffix. To assign suffixes, simply replace the word prefix with the word suffix when using the commands above and your own custom suffixes.)

NOTE: If you have not enabled ModifyWorld, the modifyworld.* lines can be skipped.

• OPTIONAL: /pex group default remove modifyworld.*
• OPTIONAL: /pex group default add modifyworld.chat (Only needed if modifyworld.* has been removed)
• /pex group Member add modifyworld.*
• /pex group VIP add modifyworld.*
• /pex group VIP add -modifyworld.mobtarget.monster.creeper
• /pex group Mod add modifyworld.*
• /pex group Mod add -modifyworld.mobtarget.*
• /pex group Admin add permissions.*
• /pex group Admin add modifyworld.*
• /pex group Admin add -modifyworld.mobtarget.*

Now it's time to test your setup

For each section, change your group to the specified group with /pex user YourPlayerName group set GroupName ####Default

• Verify that you can chat
• Verify that the right prefix is shown in the chat window (you need a chat plugin or it won't work)
• Verify that you can modify the world by breaking a block outside of the spawn area
  • NOTE: If modifyworld was enabled and the modifyworld.* node was removed, you should not be able to
• If you have enabled modifyworld and the modifyworld.* node was removed, find and run into a creeper! (Don't be afraid, it will not be able to target you, nor can you harm it)

####Member

• Verify that you can chat
• Verify that the right prefix is shown in chat window
• Verify that you can modify the world by breaking a block outside of the spawn area

####VIP

• Verify that you can chat
• Verify that the right prefix is shown in chat window
• Verify that you can modify the world by breaking a block outside of the spawn area
• If you have enabled modifyworld and the modifyworld.* node was removed, find and run into a creeper! (Don't be afraid, it will not be able to target you, but you should be able to hurt it)

####Admin

• Verify that you can chat
• Verify that the right prefix is shown in chat window
• Verify that you can modify the world by breaking a block outside of the spawn area (if you have put your player name in the ops.txt and set allowOps to true in the PEX Configuration File, you will be able to break blocks in the spawn area).
• Verify that you have access to all PEX commands (Run /pex reload as a test, it should respond with "Permissions Reloaded")
• Verify that you are not targeted by any mobs

For the next step, you will be creating a "virtual" user. Alternately, have a friend join the server and use them as the test subject (It's for Science!)

• /pex user AnotherPlayer group set default
• Verify that the promotion/demotion queue is working by using /pex promote AnotherPlayer. You should see "User AnotherPlayer promoted to NextGroup"
• Keep doing this until you see "Promotion error: User is not promotable". Running /pex user AnotherPlayer should show the following:

  playername are member of:
  Mod (rank 100 @ default)
  

playername's permissions: -modifyworld.mobtarget.* (from Mod) modifyworld.* (from Mod) playername's options:

• Demotion is the same as promotion, just change the word promote with demote
• If the player was virtual, remove them afterwards with /pex user AnotherPlayer delete if you want
• If the player was real, check every group to verify that it is working as it should (see the Goals list)

For reference, following the example above will result in the following permissions.yml file. If you use this as an example for making your permissions file, make note of the indenting and capitalization of the various header names:

groups:
  default:
    options:
      rank: '1000'
      default: true
    permissions:
    - modifyworld.chat
  Member:
    permissions:
    - modifyworld.*
    options:
      rank: '900'
      prefix: '&0(&8M&7ember&0)&7 '
  VIP:
    permissions:
    - -modifyworld.mobtarget.monster.creeper
    - modifyworld.*
    options:
      rank: '800'
      prefix: '&0(&eVIP&0)&7 '
  Mod:
    permissions:
    - -modifyworld.mobtarget.*
    - modifyworld.*
    options:
      rank: '100'
      prefix: '&0(&1Mod&0)&7 '
  Admin:
    permissions:
    - -modifyworld.mobtarget.*
    - modifyworld.*
    - permissions.*
    options:
      rank: '1'
      prefix: '&0(&4Admin&0)&7 '
users:
  AnotherPlayer:
    group:
    - default
  YourPlayerName:
    group:
    - Admin

And this is how the file looks to PEX after being parsed. Use an on-line YAML checker to verify your permissions file looks similar. If it does not, PEX will not work as expected and may throw all kinds of errors!

{
  "users": {
    "AnotherPlayer": {
      "group": [
        "default"
      ]
    }, 
    "YourPlayerName": {
      "group": [
        "Admin"
      ]
    }
  }, 
  "groups": {
    "default": {
      "options": {
        "default": true, 
        "rank": "1000"
      }, 
      "permissions": [
        "modifyworld.chat"
      ]
    }, 
    "Member": {
      "options": {
        "prefix": "&0(&8M&7ember&0)&7 ", 
        "rank": "900"
      }, 
      "permissions": [
        "modifyworld.*"
      ]
    }, 
    "VIP": {
      "options": {
        "prefix": "&0(&eVIP&0)&7 ", 
        "rank": "800"
      }, 
      "permissions": [
        "-modifyworld.mobtarget.monster.creeper", 
        "modifyworld.*"
      ]
    }, 
    "Mod": {
      "options": {
        "prefix": "&0(&1Mod&0)&7 ", 
        "rank": "100"
      }, 
      "permissions": [
        "-modifyworld.mobtarget.*", 
        "modifyworld.*"
      ]
    }, 
    "Admin": {
      "options": {
        "prefix": "&0(&4Admin&0)&7 ", 
        "rank": "1"
      }, 
      "permissions": [
        "-modifyworld.mobtarget.*", 
        "modifyworld.*", 
        "permissions.*"
      ]
    }
  }
}