Guide

Configuration

Guide on configuring CustomPlayerNametags.

config.yml

Reload any change with /nametags reload. Most settings can also be changed in-game, without editing the file, using /nametags config.

# ---- Formats ----
# Global format used for all player nametags. Default: "{player}"
nametag-format: "{player}"

# Give Bedrock players their own global format
enable-separate-bedrock-global-format: false
bedrock-nametag-format: "{player}"

# Text added to the start/end of Bedrock players' formats
bedrock-nametag-prefix: ""
bedrock-nametag-suffix: ""
apply-bedrock-prefix-suffix-to-global-format: false
apply-bedrock-prefix-suffix-to-player-format: false
apply-bedrock-prefix-suffix-to-group-format: false

# Store a separate set of LuckPerms group formats for Bedrock players
enable-separate-bedrock-group-formats: false

# ---- Format length ----
# Maximum visible characters per line. Default: 24
nametag-line-max-characters: 24
nametag-truncate-indicator: true
nametag-widget-truncate-indicator: true

# ---- Player format notifications ----
# NOTIFY | SILENT | BOTH. Default: NOTIFY
nametag-format-notify-mode: NOTIFY
nametag-format-changed-notify: "&7Your nametag format was just changed by {player} to: \n{format}"
nametag-format-disabled-notify: "&7Your custom nametag format has been cleared. Now using {type} format: \n{format}"

# ---- Nametag behavior ----
enable-tablist-format: true
enable-nametag-format-placeholder-refresh: true
nametag-format-placeholder-refresh-interval-ticks: 20
# NONE | DEFAULT | HIDE
nametag-crouch-effect: DEFAULT
enable-nametags-through-walls: true
stop-nametags-through-walls-while-crouching: true
nametag-render-distance: 64

# ---- Nametag dismounting ----
# NONE | AUTO | MANUAL
nametag-dismount-mode: AUTO
# MANUAL mode only. Commands (no leading slash) that dismount the nametag.
dismount-commands:
  - examplecommand1
  - examplecommand2
dismount-duration-ticks: 5
notify-multiverse-passenger-mode-default: true

# ---- Fine-tuning (in blocks) ----
global-nametag-height-adjust: 0.0
bedrock-height-adjust: 0.0
bedrock-sneak-height-adjust: 0.0
bedrock-per-line-height-adjust: 0.0

Other files

messages.yml and gui.yml (in the storage folder) are reset to their defaults every time the server starts and are not meant to be edited. The only messages you can change are the two format-change notifications described below.

nametag-format

The global format applied to every player by default. It is set as {player} (player's username) until you change it. More information is covered on the Nametag Formats page.

Format Length

nametag-line-max-characters

The maximum number of visible characters on each line of a nametag. Defaults to 24, and the lowest value allowed is 1. This applies to every nametag format. Anything longer is cut off and, if nametag-truncate-indicator is true, ends in ....

Individual players can be given a different limit with permissions — see Permissions.

nametag-truncate-indicator

When true (default), a line that is cut off by the limit above ends with .... When false it is cut off without one.

nametag-widget-truncate-indicator

The same as above, but for the separate character limit set on an individual widget.

Player Nametag Formats

Players change their own nametag through the /nametag menu, which is available to everyone with the customplayernametags.nametag permission (granted by default). They can only edit the widgets you place in a format — see Widgets. Admins can set any player's format with /nametags format player.

nametag-format-notify-mode

Controls whether a player is told in chat when someone else changes or clears their individual nametag format (for example, an admin using /nametags format player set). Changing your own format never sends a notification.

Mode	Behavior
`NOTIFY` (default)	Always notifies the player.
`SILENT`	Never notifies the player.
`BOTH`	Adds an optional `announce` or `silent` argument to `/nametags format player set`. If it is left out, the player is notified. `disable` and the admin editor have no such argument and always notify in this mode.

The customplayernametags.notify.override.notify and .silent permissions can force a specific player to always (or never) be notified, regardless of this setting.

nametag-format-changed-notify

The message sent when a player's format is changed. Supports & colors and \n for a new line, plus these placeholders:

{player} — the name of whoever made the change.
{format} — the new format.

nametag-format-disabled-notify

The message sent when a player's individual format is cleared with /nametags format player disable. Supports the same placeholders, plus:

{type} — what they are using now: global or group.

Bedrock-specific nametag formats

You can give Bedrock players an entirely separate global nametag format, and separate prefixes/suffixes, instead of reusing the Java format. LuckPerms group formats can also have their own Bedrock variant. This is useful since some formatting (like certain fonts or symbols) doesn't render the same way on Bedrock. It is also useful to differentiate players between both versions. These are set in config.yml:

Setting	Purpose
`enable-separate-bedrock-global-format`	Enables a separate global format for Bedrock players.
`bedrock-nametag-format`	The global format shown to Bedrock players, used when the setting above is `true`.
`bedrock-nametag-prefix` / `bedrock-nametag-suffix`	Text automatically added before/after the format for Bedrock players.
`apply-bedrock-prefix-suffix-to-global-format` / `-player-format` / `-group-format`	Controls whether the prefix/suffix above is applied to the global, individual, and group formats. All three default to `false`.
`enable-separate-bedrock-group-formats`	Lets each LuckPerms group format also have its own Bedrock-specific variant.

When either separate-format setting is enabled, the /nametags format commands for that format will ask whether you want to modify the java or bedrock format.

Nametag Behavior

enable-tablist-format

When true (default), each player's tab list entry shows their nametag format instead of their username.

enable-nametag-format-placeholder-refresh

When true (default), nametags are refreshed automatically so placeholders that change over time (ranks, balances, and so on) stay up to date.

nametag-format-placeholder-refresh-interval-ticks

How often, in ticks, nametags are refreshed when the setting above is enabled. Defaults to 20 (once a second) and cannot go below 1. Lower values update faster but cost more performance.

nametag-crouch-effect

Controls what happens to a nametag while its owner is crouching.

Value	Behavior
`NONE`	The nametag is not dimmed while crouching.
`DEFAULT` (default)	The nametag dims while crouching (it turns grey for Bedrock viewers).
`HIDE`	The nametag is hidden from every viewer while its owner is crouching.

enable-nametags-through-walls / stop-nametags-through-walls-while-crouching

When enable-nametags-through-walls is true (default), a nametag can be seen through blocks. When it is false, blocks in the way hide it. stop-nametags-through-walls-while-crouching (default true) turns through-walls visibility off while the nametag's owner is crouching, even if the first setting is true.

nametag-render-distance

Maximum distance (in blocks) at which the nametag renders for other players. Defaults to 64, matching the vanilla nametag render distance.

Nametag Dismounting

The nametag is attached to each player using an invisible passenger entity so it stays fixed above their head. Some teleport commands that move a player between worlds/dimensions can fail while that passenger is still attached. These settings control the feature that temporarily detaches and reattaches the nametag to solve this issue.

nametag-dismount-mode

Mode	Behavior
`NONE`	Never automatically dismounts the nametag.
`AUTO` (default)	Dismounts the nametag on every command the player runs.
`MANUAL`	Only dismounts the nametag when the command matches an entry in `dismount-commands`.

Picking a mode:

No world-management plugin? Use NONE.
Using Multiverse-Core? Use NONE here, and set passenger-mode to dismount_passengers in Multiverse-Core's own config.
Using a different world/teleport plugin? Use MANUAL and list its teleport commands in dismount-commands.
Using Skript? Run /nametags dismount <player> from console before a cross-world teleport — see the dismount command.

AUTO

It is recommended to not leave nametag-dismount-mode as AUTO because of minor visual bugs that can occur on commands that don't involve world changes.

dismount-commands

Commands that trigger the nametag dismount. MANUAL mode only, and one command per line with no leading slash.

dismount-duration-ticks

How long (in ticks) a dismounted nametag stays detached before automatically remounting. Defaults at 5 ticks. You generally shouldn't need to change this. 2 ticks is the lowest value that will work, so if the value is set to 1 or lower, the plugin falls back to 2 ticks internally.

notify-multiverse-passenger-mode-default

When true (default), players with the customplayernametags.multiversenotify permission get a message on join if Multiverse-Portals is installed and Multiverse-Core's teleport.passenger-mode is still set to default, which can stop portals from teleporting players. The message includes a clickable fix that runs /mv config passenger-mode dismount_passengers. Set this to false to never show it.

Fine-Tuning Nametag Positions

These settings allow you to fine-tune nametag height in blocks.

Setting	Purpose
`global-nametag-height-adjust`	Adjusts the height of all nametags.
`bedrock-height-adjust`	Adds an extra height adjustment for nametags rendered through Bedrock players.
`bedrock-sneak-height-adjust`	Adds an extra adjustment for Bedrock-rendered nametags while sneaking.
`bedrock-per-line-height-adjust`	Adds an extra adjustment, once for every line after the first, for multi-line nametags rendered through Bedrock players.

Recommended adjustments

When fine-tuning the position, start with small changes of ±0.1 blocks. This makes it easier to find the correct position without moving the nametag too far at once.

Positive values move the nametag higher, while negative values move it lower. The adjustments are cumulative.

For example:

global-nametag-height-adjust: 0.1
bedrock-height-adjust: -0.2
bedrock-sneak-height-adjust: -0.1

This moves all nametags up 0.1 blocks, applies an additional -0.2 blocks to Bedrock-rendered nametags, and an additional -0.1 blocks while sneaking.

← Previous

Nametag Formats

Commands