PEX Basics - PEXPlugins/PermissionsEx GitHub Wiki

PermissionsEx, being based on the ideas of the original Permissions 2/3 series, uses the same general style as many other permissions managers. Plugins, PEX, and bukkit itself assign lines of text, called permission nodes, to represent the various commands, features and events offered.

• Permissions Terminology
• Permissions Hierarchy
• PEX File Format (YAML)

• Server Console (AKA Console); The window that appears when the server is started. Displays server and plugin startup information, as well as server and plugin errors.
• Global Permissions: Permissions that are applied to all worlds on a server.
• World Specific Permissions: Permissions that are applied only to specified worlds.
• Users: Your players.
• Group: A name given to a set of permission nodes, often used to designate various levels of support on a server.
• Groups can have global and world specific permissions, as well as other information used by other plugins.
• Node: A line of text that represents a command, action or ability. For example, the /give command in bukkit has the node of bukkit.command.give
• Negation: Mark a node as not available. Generally used only in certain specific situations.
• Inheritance: The ability of a group to have the permissions from another group automatically apply. PEX supports group and world level Inheritance.
• Metadata: (Also know as damage value) Metadata is another value added to an item ID number for various things, such as the different colours of wool blocks, the position of a switch, if a door is open or not, and so on. Primary used with Modifyworld.

PEX supports both a file based and SQL permissions hierarchy. For the purposes of explanation and ease of visualization, the following example will use a file based permissions hierarchy.

users:                                            <- Users Section
    t3hk0d3:                                      <- Player Name
        group:                                    <- Player Group(s) Section
        - default                                 <- Player Group Name
        permissions:                              <- Player Specific Permissions Section
        - permissions.*                           <- Permissions node
        worlds:                                   <- World Specific Permission Section
            world:                                <- World designator
                permissions:                      <- World Specific Permission Group
                - test.*                          <- World Specific Permission
                group:                            <- World Specific Group Section
                - testers                         <- World Specific Group
                prefix: '&5[YARR]&f'              <- World Specific Prefix
groups:                                           <- Group Section
    default:                                      <- Group Name
        default: true                             <- Default Group Setting
        permissions:                              <- Group Permissions Section
        - -modifyworld.blocks.interact.23         <- Negated Permission Node
        - modifyworld.*                           <- Permission Node
    admins:
        inheritance:                              <- Group Inheritance Section
        - default                                 <- Groups) To Inherit From
        permissions:
        - example.permission
        - -punish.noobs
        options:                                  <- Group Options Section
            test.test: '100500'                   <- Extra Data
            rank: '1'                             <- Rank Designator
        worlds:
            nether:
                permissions:
                - nocheat.fly
                prefix: '&7[ADMIN FROM HELL]'
    testers:
        inheritance:
        - admins
        options:
            test.test: '9000'
worlds:                                           <- World Specific Section
    nether:                                       <- World Name
        inheritance:                              <- World Inheritance Section
        - world                                   <- World To Inherit From

PEX, like many other plugins, uses a format for it's files called YAML (YAML Ain't Markup Language, see http://yaml.org/ if you want to know more). YAML, unlike some other file formats, is very picky about the formatting and characters used. Config files used by PEX, including the permissions file, must be indented correctly! Capitalization matters as well!

The rules for YAML as they apply to PEX are:

• Certain characters are reserved for use by YAML. Some of the characters are ' - : # and %. If the data for an entry is going to use one of those characters, it must be in quotes.
• %prefix%player%suffix> &e%message is invalid. "%prefix%player%suffix> &e%message" is valid
• Any entries that are made of numbers only must be in quotes.
• rank: 1000 or 45625: is invalid. rank: '1000' or '45625': is valid.
• Tabs are not allowed to be in the file anywhere, unless it is in quotes. Any place where you would use a tab must use exactly two spaces.
• Each group must start at the very beginning of the line, and each section contained within that section must be indented.

Due to the regex support in PEX, there are other characters that one has to be aware of. Characters such as } { ) ( ? and * must be quoted or escaped (a backslash works well). This isn't a YAML limitation, but is a similar situation to the reserved characters in YAML.