Guide

Configuration

Guide on configuring CustomPlayerNametags.

config.yml

Reload any change with /nametags reload.

# Global format used for all player nametags.
# Supports PlaceholderAPI placeholders and '&' colors.
# Use \n in the format to start a new line.
# Default: %player_name%
nametag-format: "%player_name%"

# NONE | AUTO | MANUAL — see below
nametag-dismount-mode: AUTO

# MANUAL mode only. Commands (no leading slash) that dismount the tag.
dismount-commands:
  - examplecommand1
  - examplecommand2

# How long (in ticks) the tag stays dismounted. Default: 5
dismount-duration-ticks: 5

# Maximum render distance for nametags. Default: 64 (vanilla's own value)
nametag-render-distance: 64

nametag-format

The global format applied to every player who doesn't have a custom individual format. More information is covered on the Nametag Formats page.

nametag-dismount-mode

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. This setting controls the feature that temporarily detaches and reattaches the nametag to solve this issue.

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`.

Direct teleport handling

Regardless of mode (as long as it isn't NONE), the plugin also dismounts on any PlayerTeleportEvent — nether/end portals, and other plugins calling the teleport API directly — not just typed commands. The tag remounts automatically the moment the world change actually happens, or when dismount-duration-ticks expires, whichever comes first.

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

MANUAL mode only. One command per line, 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 raise this. 2 ticks is the lowest value that will work, so the value is set to 1 or lower, the plugin falls back to 2 ticks internally.

nametag-render-distance

Maximum distance (in blocks) at which the nametag renders for other players. Defaults to 64, matching vanilla's own fixed nametag cutoff regardless of your server's entity-tracking-range settings.

plugin-version

config.yml also contains a plugin-version key used internally to migrate the file across updates. Leave it as-is.

Extra Plugin Files

The following sections describe the other two files generated by the plugin. These files don't need to be edited manually, but feel free to read how they work!

messages.yml

Contains all messages used by the plugin.

Key	Sent when...
`no-permission`	Sender lacks the admin permission.
`reload-success`	`/nametags reload` completes.
`player-not-found`	A named target player isn't online.
`console-only`	A player tries a console-only subcommand.
`dismount-usage`	The `dismount` console command is used incorrectly.
`update-checking` / `update-check-failed` / `update-available` / `update-up-to-date`	`/nametags update` is run.
`op-update-notice`	An OP joins while an update is available.
`format-view-`, `format-set-`, `format-reset-*`	A `/nametags format` command is run.
`usage-top-level`, `usage-format`, `usage-format-view`, `usage-format-set`, `usage-format-reset`	A command is run with missing or invalid arguments.

player-formats.yml

Stores each individual player nametag formats keyed by player UUID.

formats:
  069a79f4-44e9-4726-a5be-fca90e38aaf5: '&f%player_name%'
  ec561538-f3fd-461d-aff5-086b6a97e6f8: '%luckperms_prefix%%player_name%'

← Previous

Nametag Formats

Commands