Every option of the four configuration files, with its type, default and accepted values. The
other pages explain how to use them; this one is for looking things up.
A value outside its range, or of the wrong type, is reported and replaced by its default;
the rest of the file still loads. The report says the file and the exact path, e.g.
config.yml → display.opacity: must be between 26.0 and 255.0, got 300.
A YAML syntax error (a tab, a missing quote) cancels a /nametag reload and nothing changes;
at startup the built-in copy of that file is used instead. See updating.
Durations are in ticks (20 ticks = 1 second), distances and offsets in blocks.
Colours are #RRGGBB, #RGB or a name (gold, dark_aqua...). Where an alpha channel is
possible it comes first: #AARRGGBB, like Minecraft (#80000000 = half-transparent black).
Global settings. A missing option takes the default shown here, and on the next start it is added
back to your file with its explanation (the previous file is kept as config.yml.old). So to turn
something off, change its value; do not delete it. See updating.
General
Key
Type
Default
Effect
language
text
en
Messages file lang/<language>.yml. Bundled: en, es, de, fr, pt_br, ru, zh_cn. Any other name works if you create the file; missing messages fall back to English.
update-checker
true/false
true
Tell admins (console and on join) when a newer version exists. Never downloads anything.
disabled-worlds
list of world names
[]
No nametags in these worlds (names compared ignoring case).
display
The default look of every line. Templates and lines can override the style options
(billboard to brightness); the rest only exist here.
Key
Type
Default
Values
Effect
billboard
text
center
center, vertical, horizontal, fixed (default = center)
How the text turns towards the camera. vertical keeps it upright; fixed never turns (spinning items).
Effect of a bare <anim> tag when the template sets no animation. An invalid one is reported and rainbow is used.
text-effect-interval
whole number
2
1–100
Ticks between colour frames of text effects (2 = 10 frames per second).
To turn a reaction off, set it to none: an option deleted from config.yml comes back with its
default on the next start (new and missing options are added automatically).
menu
Key
Type
Default
Effect
styles
true/false
true
Players who qualify for several templates may pick one (/nametag style, the menu).
Motions players may give their nametag. Each also needs advancednametags.motion.<name> (or .*). Unknown names are reported and left out.
sneak, self-view and updates
Key
Type
Default
Values
Effect
sneak.opacity
whole number
110
26–255
Text opacity while the player sneaks (vanilla dims it).
sneak.disable-see-through
true/false
true
Turn see-through off while sneaking, like vanilla.
sneak.hide
true/false
false
Hide the nametag completely while sneaking.
self-view.default
true/false
true
Whether players see their own nametag in third person until they change it with /nametag self.
updates.refresh-ticks
whole number
20
1–72000
Default placeholder refresh of lines that contain placeholders. Lines without them are never refreshed.
updates.permission-check-ticks
whole number
100
20–72000
How often each player's template is re-checked when nothing asks for it. With LuckPerms, permission changes apply instantly anyway.
visibility
Key
Type
Default
Values
Effect
max-distance
number
48
1–512
Nametags are never shown farther than this.
always-visible-distance
number
24
0–512
Closer than this, nametags are always shown. Cannot exceed max-distance.
fov.enabled
true/false
true
Between both distances, only show nametags the viewer looks towards.
fov.angle
number
110
10–360
Full width of that view cone, in degrees.
hide-invisible
true/false
true
Invisible players have no nametag (spectator viewers still see them).
hide-spectators
true/false
true
Spectators have no nametag (spectator viewers still see them).
check-interval
whole number
4
1–40
Ticks between visibility checks.
through-walls
text
show
show, dim, hide
Players hidden behind solid blocks: nothing special, fade to through-walls-opacity, or no nametag at all (PvP). Glass, leaves, fences and other see-through blocks never hide a player.
through-walls-opacity
whole number
70
26–255
Opacity used by dim.
through-walls-interval
whole number
5
1–100
Ticks between line-of-sight checks (up to two rays per nearby player).
Placeholders whose values may use every tag (badges, images...). Others keep colours and decorations only. '*' trusts all. See placeholders.
replacements
section
{}
placeholder → {value: replacement}. Values are matched ignoring case; unmatched values are shown as they are. Works with built-in and PlaceholderAPI placeholders.
Changing type needs a restart (a reload only warns). See
MySQL and MariaDB.
Key
Type
Default
Values
Effect
type
text
yaml
yaml, mysql, mariadb
yaml: one file per customised player in data/players/. mysql/mariadb: a shared database (both use the bundled MariaDB driver).
sql.host
text
localhost
Database host.
sql.port
whole number
3306
1–65535
sql.database
text
minecraft
The database must exist; the tables are created.
sql.username / sql.password
text
root / ''
sql.table-prefix
text
an_
letters, digits, _
Tables <prefix>profiles and <prefix>meta.
sql.pool-size
whole number
4
1–64
Connections kept open.
sql.sync-interval
whole number
5
0–3600
Seconds between checks for profiles changed by other servers (0 = off).
sql.properties
section
{}
Extra MariaDB Connector/J properties, e.g. sslMode: verify-full.
Template files
nametags.yml and every .yml file in templates/ (alphabetical order) have a templates:
section. Ids may only use a-z, 0-9, _ and - (upper case is lowered); an id used twice keeps
the first definition (nametags.yml first). Explained in templates.
Template keys
Key
Type
Default
Effect
priority
whole number
0
The highest-priority template a player qualifies for wins.
permission
text
advancednametags.template.<id>
Who qualifies. none (or empty) together with no groups = everyone.
groups
list
[]
Groups that qualify, checked as the permission group.<name> (LuckPerms grants it for inherited groups too).
worlds
list
[] (all)
Only apply in these worlds.
lines
list
required
Text lines (strings) or line sections, top to bottom; at least one, at most performance.max-lines.
Four sections; every name uses a-z, 0-9, _ and -. The entries bundled with the plugin are
always available, even if your file predates them; an entry with the same name in your file
replaces the bundled one. Explained in animations.
Section
Entry
Used as
motions
a string (a combination of motions, e.g. "float:amount=0.03, breathe:amount=0.02") or length + keyframes (loops)
motion: <name>; accepts speed
reactions
length + keyframes (plays once, starts and ends at rest)
length is 2–2400 ticks (default 20). Keyframes are tick: {properties} with ticks from 0 to
length:
Property
Unit
Rest value
x, y, z
blocks (y up)
0
scale, scale-x, scale-y
factor
1
yaw, pitch, roll
degrees
0
opacity
0–1
1
ease
linear (default), in, out, in-out, back, step
A property left out keeps the previous keyframe's value; the first keyframe starts from rest.
Custom reactions and transitions take no options (:ticks=N only works on the built-in ones).
Preset names cannot be a built-in effect type or a standard MiniMessage tag (gold, rainbow,
shadow...).
Value formats
Backgrounds
Value
Result
none (also transparent, off, false)
no box
default (also vanilla)
the vanilla nametag box; follows the client's "Text Background Opacity"
#RRGGBB
opaque colour
#AARRGGBB
colour with alpha first
rainbow, rainbow :30
blends through six translucent colours
"#60FF3B6B, #603A86FF :20"
blends through these colours; the number after : is ticks per colour (2–1200, default 20)
Motions, transitions and reactions
All three are written as a name followed by options, separated by spaces or colons:
"spin speed=0.6", "float:amount=0.08", "roll:ticks=14".
Kind
Built-in names
Options
motion
float (alias bob), breathe (pulse), sway (wiggle), swing, spin (rotate), orbit, plus motions: of animations.yml
speed 0.05–5, amount -45–45; combine several with commas: "float, sway:amount=4"
transition
flip, roll, pop, fade, none, plus transitions:
ticks 2–100 (default 10)
reaction
pop (8), fade (8), bounce (12), shake (10), jump (12), spin (16), none, plus reactions:
ticks 2–100 (default in brackets)
Text effects
An effect spec is a type or preset name followed by options, separated by spaces or colons (in a
tag: colons only). Bare colours are added to colors.
Type
Options (default)
wave
colors (none = rainbow), wavelength characters per cycle (0 = the text length, at least 6), saturation (0.85), brightness (1)
rainbow
wave without colours
pulse
color (#FF55FF) or colors, min (0.35), max (1), spread per character (0)
shine
color (#B0B0B0) or colors, highlight (white), width characters (3), pause seconds (1.5)
Every type also takes speed (above 0, up to 50; default 1). Option names ignore case and treat
_ and - alike.