Feature guide: Sorting players in tablist

Content

• Enabling
• Sorting types
• Methods of sorting
  • Sorting by primary group
    • Step 1 - Configure primary groups
    • Step 2 - Configure sorting
  • Sorting by permission nodes
  • Sorting by placeholder - pre-defined values
  • Sorting by placeholder - A to Z
  • Sorting by placeholder - Z to A
  • Sorting by placeholder - high to low
  • Sorting by placeholder - low to high
• Additional settings
• Additional info
  • Additional note 1 - Limitations
  • Additional note 2 - per-world sorting
  • Additional note 3 - Compatibility with other plugins
• Common mistakes

Enabling

To enable sorting, you must set

scoreboard-teams:
  enabled: true

Why this is required is explained in the Nametags feature's Introduction
To verify you enabled sorting, run /tab debug. It will say Sorting type: followed by anything except DISABLED.

You can then choose your sorting types by setting them in sorting-types under scoreboard-teams. Each sorting type takes arguments for how it should be applied to a user. For example, to configure the GROUPS sorting type with the groups owner, admin, mod, and default, you would write something like GROUPS:owner,admin,mod,default.

In addition, if you require that your sorting be done case sensitive, you can enable case-sensitive-sorting.
If this option is set to true, the case of the sorting options entered in to each sorting type is important. For example, when sorting is case sensitive, Joe will be considered different from joe, and depending on the sorting type, may appear in a different place.

Sorting types

Plugin allows you to sort players in many ways. Here is the list of all supported sorting types:

• GROUPS - Sorting by primary permission group
• PERMISSIONS - Sorting by custom permission nodes
• PLACEHOLDER - sorting by predefined placeholder values.
• PLACEHOLDER_A_TO_Z - sorting alphabetically by sorting placeholder. Every character used in placeholder has it's ID, which is used. That means it properly supports non-alphanumeric characters as well.
• PLACEHOLDER_Z_TO_A - sorting alphabetically by sorting placeholder from Z to A. This only reverts letters, other character are unaffected.
• PLACEHOLDER_LOW_TO_HIGH - sorting by value of a numeric placeholder from lowest to highest. This requires a placeholder that returns a number.
• PLACEHOLDER_HIGH_TO_LOW - sorting by value of a numeric placeholder from highest to lowest. This requires a placeholder that returns a number.

Methods of sorting

Below are all of the different methods that you can use to sort players in TAB.

Sorting by primary group

This is the default and recommended method. Players will be sorted by their primary group, according to the configured group list.

Step 1 - Configure primary groups

Put your players into groups in your permission plugin. All ways to do it can be found at How to assign players into groups.
Verify player group using /tab debug <player>. It should say Primary permission group: followed by group you configured. If not, you did not assign players into groups correctly.

Step 2 - Configure sorting

Place all of your groups in to a comma separated list in order of priority. For example, if you have the groups owner, admin, mod, and default, and want to have groups assigned in that order, you would end up with a configuration like GROUPS:owner,admin,mod,default.
This line should then be placed under sorting-types, which is under scoreboard-teams. This should look something like this:

scoreboard-teams:
  sorting-types:
    - "GROUPS:owner,admin,mod,default"

If you want 2 or more groups with the same priority, separate them with | symbol. Example:

scoreboard-teams:
  sorting-types:
    - "GROUPS:owner,admin,vip1|vip2,default"

Where vip1 and vip2 will be sorted with the same priority (3).

Sorting by permission nodes

This is not recommended, as many low quality servers give OP to every staff member and don't know how to negate permissions, making this option not function as intended. If you think you can pull it off, and sorting by primary group is not an option, you can give this a try.
This method is, however, handy when trying to sort specific players without assigning them into a group.

Place all of your permissions in to a comma separated list in order of priority.
For example, if you have the permissions my.permission.1, my.permission.2, my.permission.3, and my.permission.4, and want to have players sorted in that order, you would end up with a configuration like PERMISSIONS:my.permission.1,my.permission.2,my.permission.3,my.permission.4.
Example:

scoreboard-teams:
  sorting-types:
    - "PERMISSIONS:my.permission.1,my.permission.2,my.permission.3,my.permission.4"

Sorting by placeholder - pre-defined values

This method sorts players using the output of a placeholder and comparing that to pre-defined values.

To configure this sorting type, write the placeholder that you want to use, followed by a colon (:), followed by a comma separated list of outputs to check against.
For example, if you want to sort players using the output of the %afk% placeholder, depending on whether it is yes or no, you would do that using a configuration such as PLACEHOLDER:%afk%:yes,no, where players who the placeholder outputs yes for will be sorted above players who the placeholder outputs no for in this case.
Example:

scoreboard-teams:
  sorting-types:
    - "PLACEHOLDER:%afk%:yes,no"

Sorting by placeholder - A to Z

This method sorts players alphabetically according to the output of a placeholder.

To configure this sorting type, write the placeholder that you want to use. That's it.
For example, if you want to sort players using the output of the %displayname% placeholder, you would do that using a configuration such as PLACEHOLDER_A_TO_Z:%displayname%.
Example:

scoreboard-teams:
  sorting-types:
    - "PLACEHOLDER_A_TO_Z:%displayname%"

Sorting by placeholder - Z to A

This method sorts players reverse alphabetically according to the output of a placeholder.
This is identical to the above A to Z sorting, except that the alphabet is backwards, so Z comes first, and A comes last.

To configure this sorting type, write the placeholder that you want to use. That's it.
For example, if you want to sort players using the output of the %displayname% placeholder, you would do that using a configuration such as PLACEHOLDER_Z_TO_A:%displayname%.
Example:

scoreboard-teams:
  sorting-types:
    - "PLACEHOLDER_Z_TO_A:%displayname%"

Sorting by placeholder - high to low

This method sorts players numerically according to their natural sorting order (i.e. 10 comes before 1), depending on the output of a numeric placeholder.
Only placeholders that output number values will work with this sorting type!

To configure this sorting type, write the placeholder that you want to use. That's it.
For example, if you want to sort players using the output of the %health% placeholder, you would do that using a configuration such as PLACEHOLDER_HIGH_TO_LOW:%health%.
Example:

scoreboard-teams:
  sorting-types:
    - "PLACEHOLDER_HIGH_TO_LOW:%health%"

Sorting by placeholder - low to high

This method sorts players numerically according to the reverse of their natural sorting order (i.e. 1 comes before 10), depending on the output of a numeric placeholder.
Only placeholders that output number values will work with this sorting type!

To configure this sorting type, write the placeholder that you want to use. That's it.
For example, if you want to sort players using the output of the %health% placeholder, you would do that using a configuration such as PLACEHOLDER_LOW_TO_HIGH:%health%.
Example:

scoreboard-teams:
  sorting-types:
    - "PLACEHOLDER_LOW_TO_HIGH:%health%"

Additional settings

case-sensitive-sorting: true
When enabled, players will be sorted as A-Z a-z. When disabled, Aa-Zz.

Additional info

Additional note 1 - Limitations

All sorting elements and player names must together build a team name up to 16 characters long. Because of that, cuts in placeholder outputs may be required. TAB is already using the shortest possible values for all sorting types - values are internally replaced with numbers 1-9 (01-99 if 10+ results are defined etc) to avoid this limit as much as possible, however the rest is completely up to user. When trying to sort by a custom placeholder that returns multiple independent values or just using multiple sorting types, this might result in a second placeholder being entirely cut off. To avoid this, cut the placeholders yourself. For example, by only taking the first 4 characters from each one. If possible, use the PLACEHOLDER sorting type, which sorts by pre-defined values, to avoid this issue.

Additional note 2 - per-world sorting

Defining a per-world sorting type is not supported. However, this can be achieved with Conditional placeholders. Simply check for %world% and return one placeholder if it matches, another one if not. This will work with anything, not just worlds (server, regions, etc).

Additional note 3 - Compatibility with other plugins

As you already know by now, sorting is managed by scoreboard teams (their names to be exact). Player can only be member of one team. In other words, only one plugin can handle teams at a time. Having multiple plugins handle teams is supposed to end in a disaster.

Fortunately, TAB contains a function that prevents other plugins from assigning players into teams. This can be enabled/disabled by toggling anti-override setting under scoreboard-teams. This is however highly recommended to keep enabled, unless all of your plugins are configured correctly. When a plugin tries to override TAB's teams, this action is logged into anti-override.log file. If your file is empty / does not exist, it means you have no conflicting plugins / settings and can disable this option, slightly boosting performance. If the file exists, most of the time you can guess where the teams come from by their name.
Here are a few common teams and their sources (xxxx means any, usually random character sequence):

• collideRule-xxxx - this comes from Paper. Not going to explain why as that would be quite long, but the way you can avoid is by setting collision to true in paper config and false in tab config (yes, collisions will be disabled).
• CMIxxxx - CMI, disable team management in configuration.
• CIT-xxxxxxxxxxxx - Citizens NPC with the same name as some online player. Make NPC names not match real players and use holograms to display your desired text (/npc name or something).
• PVP-xxxxxxxxxxxx - Team coming from PvPManager plugin.

This detection, however, is not 100%. Because of that, you may still be experiencing a compatibility issue even with anti-override enabled. To identify such issue, check if /tab reload fixes your sorting issue. If it does, it's a compatibility issue of some sort. If not, it is most likely a misconfiguration issue. The most common cause of a compatibility issue is with plugins that hook into TAB, that might be outdated. Most recent compatibility issue was with outdated eGlow versions.

Common mistakes

Every possible mistake could be called "not reading this wiki page", but that would make this section pointless. For that reason let's call it list of mistakes made when following this page.

The most common mistakes include:

• Mistaking primary-group-finding-list for sorting list, despite that list having nothing to do with sorting and by default even having a comment above it saying it has nothing to do with sorting.

• Not configuring primary groups correctly. This can have multiple reasons, such as

  • Not configuring group weights in luckperms
  • Accidentally enabling use-bukkit-permission-manager option when on bungeecord without knowing what it does
  • Installing the plugin on bungeecord without having any permission plugin.

  Debug command will help you identify if this is your case.

• Using a plugin that causes TAB to fail to apply teams (ProtocolLib 5.0.0 dev builds, outdated eGlow versions, Tablisknu). This includes installing TAB plugin on both bukkit and bungeecord, causing the installations to conflict.