Ranks (Promotion and Demotion) - PEXPlugins/PermissionsEx GitHub Wiki

Many servers have multiple groups. Some are configured with a hierarchy of groups where there are various levels of groups, with each successive group having more permissions and 'perks'. Role Playing themed servers, for example, make very heavy use of this idea. PEX makes implementing this concept easy with its support for rank ladders.

• Basic PEX Ranking
  • Assigning Ranks to a Group
  • Promoting and Demoting
• Multiple Ranking Ladders

The PEX ranking system is based upon group ranks. The higher the number assigned to the rank, the lower the group is on the ladder. This means that a rank number of 1 is the highest rank PEX offers, with larger numbers being considered a lower rank (less is more). Removing a group from a ranking ladder can be done by assigning the group a rank value of zero (0) or removing the rank section.

To elaborate, a rank of 0, while it is a valid rank number, does effectively remove that group from the specified rank ladder. Players can not be promoted or demoted to or from a group with a rank of 0, not even from the console.

The basic command for assigning a rank to a group is pex group <group> rank <rank>. This will assign the specified group the rank number you enter in the info section of your permissions for the group.

For example, if you assigned a group named "trusted" a rank value of 100, you would use the command pex group trusted rank 100. The resulting entry in a file back-end would look like this:

  trusted:
    options:
      rank: '100'

Use /pex promote <user> [ladder] and /pex demote <user> [ladder] to quickly and easily promote and demote a player. The permission nodes are permissions.user.promote.<ladder> and permissions.user.demote.<ladder>, and must have the ladder name specified in the node. The User that is running the command has to have these permissions!

If there is a single ladder on a server (such as Guest > Member > Mod > Admin > Owner), it does not have to be named. When a ladder is not named, PEX will internally name it "default" when performing permissions checks for promotion and demotion command access. This means permissions.user.promote.default needs to be given to a group that will have promote abilities, and permissions.user.demote.default needs to be given to a group that will have demote abilities. If the promote and demote commands are used without specifying a ladder, on a server using multiple ladders, PEX will attempt to execute the commands based on the "default" ladder.

• The command of /pex promote Jim needs the permission node permissions.user.promote.default
• The command of /pex demote Jim needs the permission node permissions.user.demote.default

See Multiple Ranking Ladders for information on multiple ladder setups.

PEX also supports having multiple ranking ladders, each with their own name and permission nodes. This allows you to have separate communities with their own hierarchy.

Creating a separate ranking ladder, referred to as a named ladder, is as simple as adding the name of the ladder to the end of the command used to create or assign a rank to a group: pex group <group> rank <rank> <ladder>.

As mentioned earlier, permission nodes and commands for promotion and demotion need to specify the ladder by name: permissions.user.promote.<ladder> and /pex promote <user> <ladder>

For example, pretend you have two communities called CityA and CityB. Each city has its own leader (called the Mayor), its own officials (such as a Sheriff), regular members (Citizen) and recruits (Recruit). Only Mayors should have the ability to promote or demote members of the city.

To set this up for each city, we will need to make two ladders and name them "CityA" and "CityB".

CityA setup commands:

• pex group CityA-Major rank 100 CityA
• pex group CityA-Sheriff rank 200 CityA
• pex group CityA-Citizen rank 300 CityA
• pex group CityA-Recruit rank 400 CityA

CityB's setup would be the same, just with CityB replacing any reference to CityA.

But how does the CityA-Major group promote and demote players on the CityA ladder? Assign the CityA-Major group the permission node for the CityA ladder:

• /pex group CityA-Major add permissions.user.promote.CityA
• /pex group CityA-Major add permissions.user.demote.CityA

If the CityA-Major wanted to promote a player named Bob, they would use the command /pex promote Bob CityA.

This is what a section of a file back-end permissions file would look like if the above example is used:

groups:
    CityA-Major:
        options:
            rank: '100'
            rank-ladder: CityA
    CityB-Major:
        options:
            rank: '100'
            rank-ladder: CityB
    CityA-Sheriff:
        options:
            rank: '200'
            rank-ladder: CityA
    CityB-Sheriff:
        options:
            rank: '200'
            rank-ladder: CityB
...