Configuration

Default Configuration

The defaults section is applied to all players online regardless of permissions.

Options

All following entries should be under the defaults section OR a group section.

• 📝 text The text displayed as a String List

  • Text Example

      text:
      - "<red>%player_name%"
      - "<light_gray>%player_ping%"

• 🟥 background The background color as a hex (AARRGGBB or RRGGBB) or named text color or transparent.

  • Hex Example

      background: "#AAFFBB" # MUST start with a '#' in the format RRGGBB

  • Hex Example (With opacity)

      background: "#90AAFFBB" # The first two chars (90 in this example) are the text opacity as a hex.

  • Named Color

      background: red # By default this will apply the opacity of 0x40 (Mojank's default)

• 🪧 billboard The type of text display

  • Can either be center, vertical or horizontal.

• 🌑 text-shadow Should the text have background shadow

  • Can either be true or false.

• 👀 range Display range of the nametag

  • default will use the server's simulation distance - recommended.

  • Can also be a custom value (in blocks) Setting to 0 will not display your name tags.

  • Range Example

      range: 64 # 64.0 blocks of range (as long as the player is already visible)

• ↕️ gap The vertical gap above the player's head.

  • The closest to vanilla I found is 0.2 - recommended
  • Adjusting the translation.y will override this!

• 🔎 scale The scale of the text display

  • Scale Example

      scale:
        x: 1.5 # Generally you want to keep x and y the same otherwise it will stretch.
        y: 1.5
        z: 1 # Changing the Z can result in some strange but interesting results.

• ⬅️ translate The offset of the text display

  • Random Translation Example

      translate:
        x: 2.0
        y: 0.2 # Default offset from gap section
        z: 2.0

• 🔁 refresh-every The period (in milliseconds) between refreshing players' nametag.

  • Can be any long value. Setting to -1 will not refresh the nametag.

• 🫗 remove-empty-lines Remove empty lines from the text.

  • Can be either true or false.

Extra Options

Further features not particularly categorized.

• ✒️ formatter What type of formatting should we use for text.

  • legacy Will handle older symbols such as &c&l&#RRGGBB etc.
  • minimessage Modern formatting <red><bold><#RRGGBB> - recommended.
  • smart Attempts to format any legacy codes to minimessage format.

• 🤫 sneak Will change background and text opacity if a player is sneaking.

  • enabled Should we use this feature? (true or false)
  • opacity What opacity should we set the background and text to when they sneak?
    • Will not affect transparent backgrounds.

Permission-based configuration

If you wish for different ranks to have unique appearances, we can use the groups section to configure as many as we wish.

Note

NameTags will first apply the defaults section then apply the highest group a user has permission to.

You should set priority to an integer for your groups to override each other and take priority.

Example: MVP Rank

config.yml

defaults:
  text:
  - "<white>%player_name%"
  background: black

groups:
  donator:
    background: gray
  mvp:
    priority: 2 # Will always override donator
    background: red

Giving the player the permission node nametags.groups.mvp will give them a red nametag background!

Placeholders Support

NameTags will use Placeholder API if installed as well as relational placeholders (as of version 1.5).

Note

If placeholders such as %player_name% do not work, ensure you have the Players expansion installed.

PlaceholderAPI no longer comes with it installed by default.