Skip to content

Home

Jump to bottom
Tanguy edited this page Oct 7, 2024 · 38 revisions

Download

You can download the expansion on PlaceholderAPI's eCloud at https://api.extendedclip.com/expansions/playerlist/

Usage:

Config examples and Placeholder Syntaxes

Head over to PlaceholderAPI's config file and search for the playerlist section

  • playerlist:
  # Text shown when the index is out of range
  offline-text: "Offline"
  # Separator for filters such as PERMISSION, WORLD and PLACEHOLDER
  argument-separator: ','

  # Here's where you defined all your lists
  lists:
    # The name of this list is "staff"
    staff:
      # We only want online staff members
      type: ONLINE
      # If we're part of the list, we want to be included
      included: true
      filters:
      # Does the player have the group.staff permission? 
      - PERMISSION:group.staff
      # Can you see the player? (usually managed by vanish plugins)
      - CANSEE
    all:
      # We want all players that ever joined the server
      type: ALL
      included: true
      sorting-types:
        # Sorting players that are online first
        - PLACEHOLDER:%player_online%:yes,no
    custom:
      type: CUSTOM
      # Your custom list of elements (supports placeholders)
      input: "4, 2, 9, 5"
      # Character(s) that separates each element in the input
      separator: ", "
      # Filters are supported if the input contains player names.
      sorting-types:
        # Sorting elements starting with the lowest number (in this case: 2, 4, 5, 9)
        - LOW_TO_HIGH

  groups:
    myGroup: # name of the group
      gap: 2 # slots gap between each list
      lists:
        staff: # list name
          title: "Staff Members (%amount%)"
          max: 10 # will display a max of 10
          remaining: "... and %remaining% more"
        all:
          title: "All Players (%amount%)"
  • %playerlist_<name>_<list|amount|#>% (see Output Types)

Types:

  • ALL - Matches all players
  • ONLINE - Matches online players
  • OFFLINE - Matches offline players

Filters:

Filters Description Valid Lists Note
PERMISSION:<permission> Matches all players that have the defined permission ONLINE Supports multiple permissions separated by , (Ex: perm1,perm2)
WORLD:<world> Matches all players in the specified world ONLINE Supports multiple worlds separated by , (Ex: world1,world2)
NEARBY:<distance> Matches all players in the defined radius in blocks Online
WHITELISTED Matches all players in the whitelist. ONLINE, OFFLINE, ALL
BANNED Matches all players banned from the server OFFLINE ONLINE and ALL type work but for obvious reason don't exactly matter
CANSEE Matches all players you can see ONLINE This feature checks players which aren't hidden from you in game by other plugins such as vanish plugins.
PLACEHOLDER:<input1>=<output1>,<input2>=<output2>,... Matches all players which the placeholder defined in the input returns the specified output (only 1 condition must be met by the player) ONLINE, OFFLINE, ALL Not all placeholders support offline players, this is not an issue with this expansion but with the author of the placeholder's expansion. I can't do anything about that.
VERSION:<protocolVersion> Matches all players with the version specified Online To specify versions, you have to use the Version Numbers defined here. Supports multiple versions separated by a + and range of versions with - (both can be mixed!) Ex: ver1-ver3+ver5. Requires ViaVersion.
GAMEMODE:<gamemode> ONLINE List of online players in the specified gamemode

Sorting Types:

Types Description
A_TO_Z:<placeholder> Sorts alphabetically
Z_TO_A:<placeholder> Sorts reverse alphabetically
LOW_TO_HIGH:<placeholder> Sorts numerically
HIGH_TO_LOW:<placeholder> Sorts reverse numerically
PLACEHOLDER:<placeholder>:<output1>,<output2>,... Sorts by the placeholder's output in the defined order

Note: Aside from the PLACEHOLDER sorting type, when no placeholder is provided, the name of the player/element of the custom list will be used instead.

Output Types:

  • list - Returns a list of players separated by ,
  • amount - Returns amount of players matched
  • <number> - Returns the player at the specified index, starts from 0.

Groups

Groups can have both a list of, well, player lists, and gaps (amount of empty slots separating each list) When adding a player list to a group, you can specify its title (text that will be shown before listing the players), a max amount of players to display, as well as a text with the amount of remaining players in case you defined a max amount.

Examples:

List of players in group

If you're using LuckPerms (which most people do and should), you can easily check if a player has a group by checking the group. permission.
Head over to your PlaceholderAPI config.yml file and find the playerlist section, then add the following:

  playerlist:
    lists:
      my_awesome_group_list:
        type: ONLINE
        included: true
        filters:
        - PERMISSION:group.<groupName>
        - CANSEE

Now you can use %playerlist_my_awesome_group_list_amount% to get the amount of players that have your group! (don't forget to replace <groupName> by your actual group without the <>, you can also change my_awesome_group_list to whatever you want)
Note: Players with OP or the * permission will always be included, as well as people that have multiple groups.
If you instead want the player's primary group or just not include OP/* permission, or you're using another plugin aside from LuckPerms, use the PLACEHOLDER filter and check if %vault_group% is equal to your group (e.g. replace the PERMISSION:group.<groupName> line by PLACEHOLDER:%vault_group%=<groupName>)

List of players in a WorldGuard region

This requires the WorldGuard expansion to be installed

  playerlist:
    lists:
      spawn:
        type: ONLINE
        included: true
        filters:
        - PLACEHOLDER:%worldguard_region_name%=spawn
        - CANSEE

Group of staff members, VIPs and players

  playerlist:
    groups:
      tablist: # name of the group
        gap: 1 # slots gap between each list
        lists:
          staff:
            title: "Staff Members (%amount%)"
            max: 10 # will display a max of 10
            remaining: "... and %remaining% more"
          vips:
            title: "VIPs (%amount%)"
            max: 0 # 0 = no max, redundant
          players:
            title: "Members (%amount%)"
    lists:
      staff:
        type: ONLINE
        included: true
        filters:
          - PERMISSION:group.staff
          - CANSEE
      vips:
        type: ONLINE
        included: true
        filters:
          - "!PERMISSION:group.staff" # We don't count staff members who may also have the VIP group
          - PERMISSION:group.vip
          - CANSEE
      players:
        type: ONLINE
        included: true
        filters:
          - "!PERMISSION:group.staff" # Same thing, but for both staff members & VIPs
          - "!PERMISSION:group.vip"
          - CANSEE

You can then either use %playerlist_group_tablist_amount% to get the combined amount of players of all the lists within the group, or %playerlist_group_tablist_<index>% to get a player/list title at a specific index. Can be used with TAB's layout feature for dynamic playerlists sizes!

Clone this wiki locally